Boldh - Object manipulation library

You need to create hash of hashes, in which each entry defines one attribute. This hash takes the following form:

   my $attributes = {
      Product => {
         Plural => 'Products',
         Root => 1
      },
      Category => {
         Type => 'Text',
         Reference => 'Product',
         Plural => 'Categories'
      },
      # More attributes
   };
         

   FinalPrice => {
      Reference => 'Price',
      Type => 'Money',
      Virtual => 'if(Sale > 0, Sale, Price)'
   }
               

   Surcharge => {
      Reference => 'Price',
      Type => 'Float',
      Virtual => 1
   }
   FinalPrice => {
      Reference => 'Price',
      Type => 'Money',
      Virtual => 'Surcharge * if(Sale > 0, Sale, Price)'
   }

   $boldh->attr('Surcharge')->virtual(1.1);
               

   <Riddle ID="425" RowID="425">
      <Formal Value="0" RowID="425"/>
      <PhrasalVerb Value="1" RowID="425"/>
      <PartOfSpeech ID="1" Value="Verb" RowID="425">
   </Riddle>
               

   <Riddle ID="425" RowID="425" PhrasalVerb="1" Formal="0" PartOfSpeechID="1" PartOfSpeech="Verb">
               

   <Description RowID="2">
      <Text>Some text with <i>italic part</i></Text>
   </Description>
               

There is a subclass Boldh::SqlGenerator of a Boldh class that will help you to start. It inherits new() constructor from Boldh. It has one method - sqlGenerator([Deploy => 1|0]), that dumps SQL to STDERR. If you set parameter Deploy to true value it will also create all tables. A generated DDL is good to make things start working and as a template for subsequent changes.

See example to learn more about database structure.

new(PARAMETER => VALUE [, PARAMETER => VALUE [...]])

The first step in using Boldh is creating a new object using the new() constructor.

   my $boldh = Boldh->new(
      Attributes => $attributes,
      SupportedLanguages => [qw/en pl/],
      Language => $lang
   );
         

   <Category ID="2">
      <eBayShopCategory Value="11369"/>
      <Text lang="en">Some regular category</Text>
      <Text lang="pl">Jakaś przeciętna kategoria</Text>
   </Category>
               

select(ATTRIBUTE [, ATTRIBUTE [...]])

This method takes a list of attributes names as argument. The job is to join all tables that contain these attributes. You can find more information here on using modes.

   $boldh->select(qw/Category Price Sale Pack Currency/);
         

You may also specify some common field (-Foobar here) for a group of attributes and call select() method like this:

   $boldh->select('-Foobar');
         

See also getSelect() method and removeSelect() method

search(Attribute => ATTRIBUTE, Equals => VALUE)
search(STATEMENT [, VALUE [...]])

The simplest form takes a hash that specifies attribute name and value. In case of enumeration attributes you search by its ID not value.

   $boldh->search(
      Attribute => 'Category',
      Equals => 5
   );
         

Above example will result in SQL condition 'WHERE CategoryID = 5'.

If you call this method multiple times all conditions have to be met. If you want to join conditions with OR just provide reference to an array of values. So if you want to select products which category ID is equal to 5 or 6 and color ID is equal to 10 you can write:

   $boldh->search(
      Attribute => 'Category',
      Equals => [ 5, 6 ]
   );
   $boldh->search(
      Attribute => 'Color',
      Equals => 10
   );
         

This is good for most cases but you can't create complex conditions or use functions. To do this you can use another way to call search() method where you specify SQL-like statement and values to bind. In that statement all names of attributes will be replaced with table and column name, so it is the same like writing an actual SQL condition. See example below.

   $boldh->search('Price > ? AND Price <= ?', 2, 10); 
         

These 3 calls altogether will result in a SQL condition like this '(CategoryID = 5 OR CategoryID = 6) AND ColorID = 10 AND Price >= 2 AND Price <= 10'.

In this approach you have to exactly specify which column you want to use and there are 3 types of columns.

   $Boldh::isuff = 'ID';
            

   $boldh->search(
      Attribute => 'Category',
      Equals => 5
   );

   $boldh->search('CategoryID = ?', 5);
            

filter(Attribute => ATTRIBUTE, Equals => VALUE)
filter(STATEMENT [, VALUE [...]])

To remove some attributes you can use filter() method. It has exactly the same syntax as search() method.

   $boldh->filter(
      Attribute => 'Currency',
      Equals => 'EUR'
   );

   # It will result in this SQL
   # ...
   # LEFT JOIN  AttrPrice ON Products.ProductID = AttrPrice.ProductID AND (AttrPrice.Currency = 'EUR')
   # ...
         

Because it affects the way tables are joined, one statement can only contain conditions for one table. See example for details how attributes are scattered around a database.

execute()

This method is responsible for preparing SQL statement, executing it and fetching all data.

fingerprint()

This method returns a 36 characters long string that uniquely identifies a fetched data. Use this method after calling execute().

transform(Stylesheet => STYLESHEET_PATH [[, ]Gzip => 1|0 ])

This method will transform XML tree with a provided stylesheet and will return a result. A result will be also compressed if you set Gzip option to true.

print([Stylesheet => STYLESHEET_PATH] [[, ]Gzip => 1|0])

This method dumps XML tree to a string and optionally creates processing instruction with a path to a stylesheet. A result will be also compressed if you set Gzip option to true.

getSearch([ATTRIBUTE])

When called without any argument returns a list of all attributes that will be used to search. If an attribute name is specified returns true (1) if an attribute is used to perform search, otherwise returns false (undef).

removeSearch()

This method removes all conditions set by search() or sqlStatement() method.

getSelect([Attribute => ATTRIBUTE] [[, ]Mode => MODE])

When called without any arguments returns a list of all attributes that will be selected. If an attribute name is specified returns true (1) if an attribute will be selected, otherwise returns false (undef). You may also specify mode, see advanced usage.

removeSelect([[MODE:]ATTRIBUTE [, [MODE:]ATTRIBUTE]])

If you call this method without any arguments it will remove all attributes set by select() method. Otherwise it will remove only specified attributes. Mode is optional, see advanced usage.

setLimit(LIMIT)

Sets a limit on a number of objects that will be selected from a database. See setOffset() method.

getLimit()

Returns a maximal number of objects per page that will be selected from a database.

setOffset(PAGE)

Sets an offset. See setLimit() method.

getOffset()

Gets an offset.

setSortOrder(1|2)

This method allows to define wheather results should be sorted in ascending (1) or descending (2) order. It is possible to set a default sort order for every attribute using a SortOrder field, see attributes configuration.

getSortOrder()

Returns 1 if results are sorted in ascending order or 2 if sorted in descending order.

setSortAttribute(ATTRIBUTE)

This methods allows to set an attribute which should be used to sort results. If you want to sort results in random order, create virtual attribute with SQL rand() function.

getSortAttribute()

Returns a name of an attribute that will be used to sort results.

count()

Returns a number of found objects.

language([LANGUAGE])

It returns current language. It also sets a language when invoked with an argument.

attr([ATTRIBUTE])

Returns a Boldh::Attribute instance. It is live and it might be tweaked during runtime. Without any argument this method returns a list of attributes. See Boldh::Attribute.

attributes(XPATH)

This method returns a list of nodes of selected attributes.

   foreach my $node ($boldh->attributes('Product[@ID=12]/Price')) {
      # ...
   }
         

select(MODE:ATTRIBUTE [, MODE:ATTRIBUTE [...]])

It is common that objects in a database are related in some way with each other, for example they are grouped into sets. In this case it useful to select some attributes of those related objects and it is where modes come. First we need an attribute that will define the ids of related products. It will be special attribute and this is an example how to configure it.

   SetPart => {
      Type => 'Complex',   # important!
      Reference => 'Set',  # Any attribute
      EnumTable => 'Bar'   # important! Root attribute defined in a configuration hash
      Namespace => 'Qux'   # important! See below
   }
   

This is a Complex attribute that uses the main table with objects ids as a enumeration table. The namespace is any name despite the reserved modes: Select, Search, Sort. Now to select an attribute you use select() method and attributes names prefixed with a namespace.

   $boldh->select(qw/Qux:Price Qux:FinalPrice Qux:Pack Qux:Sale/);
         

This will result in a XML:

   <Bar ID="1" RowID="1">
      ...
      <Set ID="5" RowID="14">
         <SetPart ID="2" RowID="13">
            <Price Value="10.00" RowID="2912">
               <FinalPrice Value="10.00"/>
               <Sale Value="0.00"/>
               <Pack Value="1" RowID="3140"/>
            </Price>
         </SetPart>
         ...
      </Set>
   </Bar>
         

filter(STATEMENT [, VALUE [...]])

All conditions defined by filter() method will be applied in all modes. If you want to apply a condition to a certain mode you must specify a mode prefix. Each attribute in a statement need to have the same prefix.

   $boldh->filter('Select:Currency = ?', 'EUR');
         

sqlStatement(STATEMENT [, VALUE [...]])

If it is not possible to perform search by using standard calls this method allows to pass a search statement.

   $boldh->sqlStatement('SELECT RootAttributeID FROM SomeTable WHERE exp(i * ?) + 1 = 0', 3.14);

   # SELECT SearchResults.*, ...
   # FROM RootTable
   # RIGHT JOIN (
   #    SELECT RootAttributeID
   #    FROM SomeTable
   #    WHERE exp(i * 3.14) + 1 = 0
   # ) SearchResults ON SearchResults.ID = RootTable.RootAttributeID
   # LEFT JOIN ...
         

If you call this method multiple time all statements will be unioned. They will be also unioned with sql statement generated from conditions applied by search() method so in some cases it might by important to use removeSearch() method first. See also example for naming convention.

getData()

This method returns a reference to a Perl data structure that is passed to addData() method and converted to XML.

addData(NodeName => NODENAME, Data => DATA [, Node => NODE_OBJECT])

This method allows a simple conversion from Perl data to XML. It was not designed to be capable of creating any XML structures, it just might be usuful in some simple cases. Few examples will show how to use this method.

   $boldh->addData(
      NodeName => 'Foo',
      Data => 'Bar'
   );

   # <Foo>Bar</Foo>

   $data->addData(
      NodeName => 'Foo',
      Data => { Baz => 1, _Content => 'Bar' }
   );

   # <Foo Baz=1>Bar</Foo>

   $data->addData(
      NodeName => 'Foo',
      Data => [
         'Qux',
         { Baz => 1, _XmlChunk => '<i>Bar</i>' },
         { Baz => 2, _NodeName => 'Fred' }
      ]
   );

   # <Foo>Qux</Foo>
   # <Foo Baz=1><i>Bar</i></Foo>
   # <Fred Baz=2/>
         

By default data is added to a root node but any node may be supplied by a Node parameter.

addFile(PATH_TO_XML_FILE)

This method parses and imports supplied XML file to an existing document.

doc()

This method returns a XML document. It will be XML::LibXML::Document object or XML::Sablotron::Document object. See xmlLibrary() method.

xmlLibrary()

Returns either 'XML::LibXML' or 'XML::Sablotron::DOM' depending on which library is used to perform operations on XML tree. XML::LibXML has a higher priority but it is possible to force the library by passing an appriopriate argument to the new() constructor.

dbh([ DATABASE ])

This method returns DBI handle for a database connection.

dump([ VARIABLE ])

Without any arguments it dumps an XML tree. Otherwise it will dump a specified variable with Data::Dumper.

debug(DEBUG_LEVEL)

This method sets debug level. It starts from 1 and more information is printed as the level increases.

new(PARAMETER => VALUE [, PARAMETER => VALUE [...]])

Usually it is not necessary to create this objects because they can be easily obtained by attr() method. If you want to create this object separately you need to supply configuration hash and optionally language and debugging level. See new() constructor for more details.

virtual([ DEFINITION ])

This method is the accessor of a 'Virtual' field in configuration hash. It allows to set a new definition and returns the current one. If Boldh::Attribute object is obtained by attr() method you may change this property during runtime. See attributes configuration for more details.

query([ DEFINITION ])

This method manipulates 'Query' field in configuration hash. It allows to set a new definition and returns the current one. If Boldh::Attribute object is obtained by attr() method you may change this property during runtime. See attributes configuration for more details.

bind(VALUE [, VALUE [...]]))

This method supplies values for placeholders in SQL statement defined by Query field or by query() method. It returns list of values to bind. This method manipulates 'Bind' field in configuration hash. If Boldh::Attribute object is obtained by attr() method you may change this property during runtime.

xmlChunk([0|1]))

This method manipulates 'XmlChunk' field in configuration hash. It allows to set a new value and returns the current one. If Boldh::Attribute object is obtained by attr() method you may change this property during runtime.

language([ LANGUAGE ])

This method allows to set a new language and returns the current one

addAttribute(Value => VALUE, Reference => ID)

This method adds new value to a database. It takes two arguments.

addEnumValue(Value => VALUE [, ID => ID] [, Parent => ID])

This method adds new enumeration value to a database. It takes following arguments.

updateAttribute(Value => VALUE, Row => RowID)

This method updates an attribute. It takes two arguments.

updateEnumValue(Value => VALUE, Row => ID [, Parent => ID])

This method updates enumeration value. It takes following arguments.

removeAttribute(Row => RowID)

This method removes attribute from a database. It takes one arguments.

removeEnumValue(Row => ID)

This method removes attribute from a database. It takes one arguments.

treeGet([ID])

This method returns a Tree object. If you call it without an argument it returns a root otherwise it returns a node with supplied ID.

treeAscendants(ID)

This method returns a node and all its ascendants.

treeYoungest(ID, ID [, ID [...]])

Gets the youngest (with highest level) node of a supplied branch (or part of if).

treeOldest(ID, ID [, ID [...]])

Gets the oldest (with lowest level) node of a supplied branch (or part of if).

treeNodeLeaves(ID)

This method returns all leaves that have supplied node as a ascendant.

treeLeaves(ID, ID [, ID [...]])

This method takes a list of nodes. Each node, for which a descendant is present in a list, is ignored. For all others it returns descendants that are leaves. This method is contrary to treeMinimize(). For example if you supply a root attribute it will return all leaves in a tree.

treeMinimize(ID, ID [, ID [...]])

This method is contrary to treeLeaves(). It takes leaves and returns the oldest possible nodes for which all descendants are present. For example if you supply all leaves it will return a root attribute.

   package Boldh;

   my $attributes = {
      User => {
         Type => 'Complex',
         Reference => 'Riddle',
         Plural => 'Users',
         OneOne => 1,
         Enum => 1
      },
      Login => {
         Type => 'String',
         Reference => 'User',
         OneOne => 1
      },
      Type => {
         Type => 'Text',
         Reference => 'Riddle',
         OneOne => 1,
         Enum => 1,
         Plural => 'Types'
      },
      Date => {
         Type => 'Date',
         Reference => 'Riddle',
         OneOne => 1
      },
      LastHit => {
         Type => 'Date',
         Reference => 'Riddle',
         OneOne => 1
      },
      Hits => {
         Type => 'Integer',
         Reference => 'Riddle',
         OneOne => 1
      },
      Successes => {
         Type => 'Integer',
         Reference => 'Riddle',
         OneOne => 1
      },
      Active => {
         Type => 'Integer',
         Reference => 'Riddle',
         Virtual => 'unix_timestamp()-unix_timestamp(LastHit) > if(Successes < 3, Successes + 1, 1) * 60 * 60 * 24'
      },
      Random => {
         Type => 'Float',
         Reference => 'Riddle',
         Virtual => 'rand()'
      }
   }

   package Boldh::English;

   my $attributes = {
      English => {
         Extends => 'Riddle'
      },
      EnglishExample => {
         Type => 'LongString',
         Reference => 'English',
         Plural => 'EnglishExamples'
      },
      EnglishCutExample => {
         Type => 'LongString',
         Reference => 'EnglishExample',
         OneOne => 1
      },
      Word => {
         Type => 'LongString',
         Reference => 'English',
         XmlChunk => 1,
         OneOne => 1
      },
      Definition => {
         Type => 'LongString',
         Reference => 'English',
         OneOne => 1
      },
      Pronunciation  => {
         Type => 'String',
         Reference => 'English',
         OneOne => 1
      },
      PartOfSpeech => {
         Type => 'String',
         Reference => 'English',
         Plural => 'PartsOfSpeech',
         OneOne => 1,
         Enum => 1
      },
      Prepositions => {
         Type => 'String',
         Reference => 'English',
         OneOne => 1
      },
      PhrasalVerb => {
         Type => 'Integer',
         Reference => 'English',
         AsAttribute => 1,
         OneOne => 1
      },
      Idiom => {
         Type => 'Integer',
         Reference => 'English',
         AsAttribute => 1,
         OneOne => 1
      },
   };
         

    <Riddles>
      <Riddle Approval="0" ID="425" Formal="0" PhrasalVerb="0" Idiom="0" Derogatory="0" Informal="0" RowID="425">
        <Type ID="1" RowID="425">
          <Text>English</Text>
        </Type>
        <Word Value="hawk" RowID="425"/>
        <Definition RowID="425">
          <Text>to go from place to place offering things for sale</Text>
        </Definition>
        <Prepositions Value="~ sth (about/around)" RowID="425"/>
        <EnglishExample RowID="510">
          <EnglishCutExample RowID="510">
            <Text>The streets were full of people ~ing their wares</Text>
          </EnglishCutExample>
          <Text>The streets were full of people hawking their wares</Text>
        </EnglishExample>
        <EnglishExample RowID="511">
          <EnglishCutExample RowID="511">
            <Text>He ~ed his songs around for ages until record company finally accepted them</Text>
          </EnglishCutExample>
          <Text>He hawked his songs around for ages until record company finally accepted them</Text>
        </EnglishExample>
        <PartOfSpeech ID="2" Value="Verb" RowID="425"/>
        <Pronunciation Value="hɔːk" RowID="425"/>
      </Riddle>
    </Riddles>