NAME

RDF::Base::List

DESCRIPTION

Represents lists of nodes.

Boolean operations are overloaded to /size. And cmp are overloaded to /cmp.

It's not compatible with Para::Frame::List but may/should work as a Template::Iterator.

Constructors

These can be called with the class name or any List object.

new

  $l->new( \@list, \%args )

This constructor takes an array ref, a RDF::Base::List object or a Para::Frame::List object. The RDF::Base::List object will be returned unchanged. The Para::Frame::List object will be used for extracting the elements and creating a new separate RDF::Base::List object.

If the first argument is undef, the list will be marked as unpopulated.

The special arg initiate_rel will cause the materialization of the arc to initialize all rel properties directly

Returns the object.

Exceptions:

Dies on other type of input.

init

Searches

Methods that returnes new modified lists

find

  # Returns true/false
  $l->find( $value, \%args )

  # Returns true/false
  $l->find( \@list, \%args )

  # Returns a list
  $l->find( \%proplim, \%args )

  # Returns the same object
  $l->find()

The first two forms calls /contains with the params and returns 1 or 0. It will call /contains for all cases where the first parameter is not a hashref.

The third form finds the elements in the list that meets the given proplim, using RDF::Base::Node/meets_proplim and returns a new Para::Frame::List with those elements.

For the last form, the same list object will be returned if the first param is undef or an empty hashref, regardless of \%args.

Details

The corresponding search method in RDF::Base::Search/modify should not be confused with this one, but we tries to proviede the same syntax for making searches. Except that we here search in a given list instead of the whole DB.

Only nodes that matches all the given properties are placed in the new list.

If the key has dots ('.'), that sequence of methods will be called to get the property to be compared with the value. For example, for the key a.b.c we will call $element->a. At least one of the elements returned must match the value. A new find will be called as $subelement->find('b.c' => $value ). This find will make the next step by doing $subsubelement->b and $subsubsubelement->find('c' => $value ).

If the key begins with rev_ a reverse property will be looked for, there the element is the subject and the value is the object.

If the key ends with _$matchtype there $matchtype is any of eq, exact, like, begins, gt, lt and ne, the corresponding comparsion to the value will be used. The default is eq for mathing the elements those property is the same as the value. ne matches if the property is not the same as the value. (The other matchtypes are not implemented here).

If the key begins with count_pred_ we count the number of properties the element has with the given predicate. Use rev_ prefix for couting reverse properties. The value is compared with the resulting number. For this comparsion, the matchtypes eq, exact, ne, gt and lt are supported, using numerical comparsion.

If the key begins with predor_ the rest of the key is expected to be a list of predicate names separated by _-_. There is a match if at least one of the properties matches the value.

If the key is not, the value should be a \%proplim that is negated.

The value can be a * for matching all values of the property. That would be a test for the existence of that property.

The value can be a list of values. There is a match if at least one of the values in the list matches. The list may be an arrayref or a RDF::Base::List or Para::Frame::List object.

The actual comparsion for the eq and ne matchtypes are done by the RDF::Base::Resource/has_value method.

If an element in the list is a RDF::Base::List, it will be searchd in the same way.

The supported args are:

  private?
  clean
  arclim

unique_arcs_prio filter is NOT used here. Do the filtering before or after this find.

See also

The combination of this and other methods creates a very powerful query language. See /AUTOLOAD, /contains, RDF::Base::Resource/AUTOLOAD, RDF::Base::Resource/has_value, RDF::Base::Resource/find_by_anything and /sorted for some of the methods you can combine.

Example 1

  [% item.in_region(is='city').name %]

This is translated to

  [% item.list('in_region', {is='city'}).name %]

that in the next step translates to

  [% item.list('in_region').find({is='city'}).name %]

and will thus give the names of the regions the item is in that is cities, ie; the name of the city of the item.

Example 2

  [% FOREACH arc IN node.revarc_list('has_member').find(subj={is=C.partner_group}).sorted %]

Iterates through the arcs that points to the node and is of the predicate has_member, those subj node is a partner_group (as given in the constant), sorted in the default way (on the arc desig).

Example 3

  [% node.is('organization') %]

This expands to

  [% node.list('is').find('organization') %]

which is the same as

  [% node.list('is').contains('organization') %]

and Contains uses RDF::Base::Resource/equals for the comparsion which in turn uses RDF::Base::Resource/find_simple looking for a node with the corresponding name. (Note that will not work if the name is containd in a literal resource.)

This will return true if the node is an organization. That is; has an arc node --is--> organization.

Example 4

  [% node.has_subscription([sub_010, sub_030]).name %]

This expands to

  [% node.list('has_subscription').find([sub_010, sub_030]).name %]

TODO: Is example 4 correct..?

See also

Para::Frame::List/complement for finding what is not matching criterions

find_one

  $l->find_one({ $key1 => $value1, $key2 => $value2, ... }, \%args )

Expects a hashref as the only param.

Calls /find with the hashref.

Returns: The first element found.

Exceptions:

If more than one match found: alternatives: Flera noder matchar kriterierna

If no matches are found: notfound: No nodes matches query

limit

  $list->limit()

  $list->limit( $limit )

  $list->limit( 0 )

Limit the number of elements in the list. Returns the first $limit items.

Default $limit is 10. Set the limit to 0 to get all items.

Returns: A List with the first $limit items.

sorted

  $list->sorted()

  $list->sorted( $prop )

  $list->sorted( $prop, $dir )

  $list->sorted( [$prop1, $prop2, ...] )

  $list->sorted( [$prop1, $prop2, ...], $dir )

  $list->sorted( { on => $prop1, dir => $dir } )

  $list->sorted( [{ on => $prop1, dir => $dir },
                  { on => $prop2, dir => $dir2, cmp => '<=>' },
                  ...
                 ] )

Returns a list of nodes, sorted by the selected proprty of the node.

The default sorting property is desig.

$dir is the direction of the sort. It can be asc or desc and defaults to asc. It can also be exists (for a SQL search).

$prop can be of the form p1.p2.p3 which translates to a property lookup in several steps. For example; $arcs-sorted('obj.name')>

The type of sort (numeric or string) is decided by the predicate type. Numeric predicates will give numeric sorts. If the sort property isn't a predicate, we can tell the type of value by the cmp argument.

Examples:

Sort all predicates on id:

  my $predlist = RDF::Base::Pred->find->sorted('id');

Loop over the name arcs of a node, sorted by firstly on the is_of_language code and secondly on the weight in reverse order:

  [% FOREACH arc IN n.arc_list('name').sorted(['obj.is_of_language.code',{on='obj.weight' dir='desc'}]) %]

Returns:

A List object with 0 or more Resources, with properties cloned from the soruce list.

If sort key is the same, the same object is returned without sorting

Exceptions:

Dies if given faulty parameters.

parse_sortargs

  $class->parse_sortargs( ... )

uniq

  $l->uniq()

Returns a list with multiple list items filtered out. Operates on the unmaterialized items. Populates the list.

For more than one element, returns a list. If nothing was filtered, returns the same object.

For less than one element, returns RDF::Base::Undef.

For just one element, returns the element.

unique_arcs_prio

  $list->unique_arcs_prio( \@arcproperties )

Example:

  $list->unique_arcs_prio( ['new','submitted','active'] )

Returns:

A List object with arc duplicates filtered out

Accessors

get

  $l->get(@params)

Calls /find with the params and expects just one match.

Returns:

A RDF::Base::Resource object.

Exceptions:

See RDF::Base::Resource/get_by_anything

as_string

  $l->as_string

Deprecated...

literal

  $l->literal

Selects the best literal from the nodes. The list could be diffrent translations of a text.

It could also be a list of names, each having its own translations.

Returns: A string

loc

  $l->loc

  $l->loc(@params)

Choose a value, based on language option. After that; sort on weight.

Params are given to Para::Frame::L10N/compute.

The language priority should have been set by Para::Frame::Resource/set_language for the request.

Returns: A plain string

loc_by_lang

my $prop = $list->loc_by_lang( [ 'sv', 'c' ] );

Returns one prop from the list, chosen first on is_of_language and then on weight.

desig

  $l->desig

Return a SCALAR string with the elements designation concatenated with ' / '.

See RDF::Base::Object/desig

as_html

  $l->as_html( \%args )

Return a SCALAR string with the elements html representations concatenated with '<br>' or with the content of arg join.

See RDF::Base::Object/desig

is_list

  $l->is_list

This is a list.

Returns: 1

nodes

  $l->nodes(@args)

Just as /as_list but regards the SCALAR/ARRAY context.

plain

  $l->plain()

Just as /nodes.

is_true

  $l->is_true

Returns 1 if the list has more than one element or if the one element is true.

Otherwise returns 0;

Public methods

contains

  $list->contains( $node, \%args )

  $list->contains( $list2, \%args )

Returns true if the list contains all mentioned items supplied as a list, list objekt or single item.

Each element is compared with Para::Frame::Object/equals.

Supported args are:

  arclim

TODO: Use iteration with the iterators

Returns: A boolean value

contains_any_of

  $list->contains_any_of( $node, \%args )

  $list->contains_any_of( $list2, \%args )

Returns true if the list contains at least one of the mentioned items supplied as a list, list objekt or single item.

Each element is compared with Para::Frame::Object/equals.

Supported args are:

  arclim

TODO: Use iteration with the iterators

Returns: A boolean value

has_value

  $l->has_value($val, \%args)

Returns true if at least one of the elements of the list has the given value.

See RDF::Base::Resource/find nad RDF::Base::Arc/has_value.

Supported args are:

  arclim

has_pred

  $l->has_pred($predname, $proplim, \%args)

Returns: A list of all elements that has a property with the pred to a value matching proplim and args

materialize

Primarly used by RDF::Base::Search/execute given to /new as argument materializer.

materialize_by_rec

initiate_rel

  $l->initiate_rel

Calls Para::Frame::Resource/initiate_rel for each element.

Returns: $l

cmp_by_overload

  $l->cmp_by_overload( $val )

Comparing something with the list compares with it's desig

as_listobj

  $o->as_listobj()

Returns a RDF::Base::List

equals

  $l->equals( $value )

Check each of the elements with the value

Returns: A boolean value

get_first_nos

Same as Para::Frame::List/get_first_nos, but returns RDF::Base::Undef if no element found

get_next_nos

Same as Para::Frame::List/get_next_nos, but returns RDF::Base::Undef if no element found

concatenate_by_overload

implemented concatenate_by_overload()

parse_prop

  $n->parse_prop( $criterion, \%args )

Parses $criterion...

Formats handled:

  prop1.prop2.prop3

Returns the values of the property matching the criterion. See /list for explanation of the params.

See also RDF::Base::Node/parse_prop

transform

  $l->transform( $lookup )

Returns: A new list with the nodes that is the result of the given lookup

AUTOLOAD

  $l->$method( @args )

For all method calls not catched by defined methods in this class, this AUTOLOAD is used.

The method is called for each element in the source list. Elements that are not RDF::Base::Object objects are silently ignored. RDF::Base::Undef objects are also ignored.

If the source list is empty, the method are called on RDF::Base::Undef in return context, and returned. That class will return the right type of value for most RDF::Base::Node methods.

A result list is prepared for the return values of each method call. The $method are called in scalar context and given the @args.

1. Results that isn't RDF::Base::Object objects are appended to the result list.

2. RDF::Base::Undef objects are ignored. Not placed in the result list.

3. RDF::Base::List objects are appended to the result list, only if they contain one or more elements. The lists are NOT flattened. The content of the returned lists are not altered. Undef value inside the lists are thus also left in place. We are just checking for the size of the list. Empty lists are not appended to the result list.

4. All other RDF::Base::Object objects are appended to the result list.

The return value depends on the size of the result list:

1. For an empty result list, we will return a an empty RDF::Base::List

2. For a result list with just one element, that element will be used as a return value, no matter what that value is. (It may, for example, be a RDF::Base::List object returned from one of the method calls.)

3. For a result list with more than one element, a RDF::Base::List containing the result list will be returned.

No exceptions are cathed.

SEE ALSO

RDF::Base, RDF::Base::Resource, RDF::Base::Arc, RDF::Base::Pred, RDF::Base::Search