NAME

Treex::PML::Seq - sequence of PML values of various types

DESCRIPTION

This class implements the data type 'sequence'. A sequence contains of zero or more elements (Treex::PML::Seq::Element), each consisting of a name and value. The ordering of elements in a sequence may be constrained by a regular-expression-like pattern operating on element names. Validation of a sequence against this constraint pattern is not automatic but can be performed at any time on demand.

Treex::PML::Seq->new (element_array_ref?, content_pattern?,$reuse?)

NOTE: Don't call this constructor directly, use Treex::PML::Factory->createSeq() instead!

Create a new sequence (optionally populated with elements from a given array_ref). Each element should be a Treex::PML::Element::Seq object. The second optional argument is a regular expression constraint which can be stored in the object and used later for validating content (see validate() method below). The $reuse argument is a boolean flag indicating whether the passed array reference can be used directly (if $reuse is true) or copied (if $reuse ise false).

$seq->elements ($name?)

Return a list of [ name, value ] pairs representing the sequence elements. If the optional $name argument is given, select only elements whose name is $name.

$seq->elements_list ()

Like elements without a name, only this method returns directly the Treex::PML::List object associated with this sequence.

$seq->content_pattern ()

Return the regular expression constraint stored in the sequence object (if any).

$seq->set_content_pattern ()

Store a regular expression constraint in the sequence object. This expression can be used later to validate sequence content (see validate() method).

$seq->values (name?)

If no name is given, return a list of values of all elements of the sequence. If a name is given, return a list consisting of values of elements with the given name.

In array context, the returned value is a list, in scalar context the result is a Treex::PML::List object.

$seq->names ()

Return a list of names of all elements of the sequence. In array context, the returned value is a list, in scalar context the result is a Treex::PML::List object.

$seq->element_at (index)

Return the element of the sequence on the position specified by a given index. Elements in the sequence are indexed as elements in Perl arrays, i.e. starting from $[, which defaults to 0 and nobody sane should ever want to change it.

$seq->name_at (index)

Return the name of the element on a given position.

$seq->value_at (index)

Return the value of the element on a given position.

$seq->delegate_names (key?)

If all element values are HASH-references, then it is possible to store each element's name in its value under a given key (that is, to delegate the name to the HASH value). The default value for key is #name. It is a fatal error to try to delegate names if some of the values is not a HASH reference.

$seq->validate (content_pattern?)

Check that content of the sequence satisfies a constraint specified by means of a regular expression content_pattern. If no content_pattern is given, the one stored with the object is used (if any; otherwise undef is returned).

Returns: 1 if the content satisfies the constraint, 0 otherwise.

$seq->push_element (name, value)

Append a given name-value pair to the sequence.

$seq->push_element_obj (obj)

Append a given Treex::PML::Seq::Element object to the sequence.

$seq->unshift_element (name, value)

Prepend a given name-value pair to the sequence.

$seq->unshift_element_obj (obj)

Unshift a given Treex::PML::Seq::Element object to the sequence.

$seq->delete_element (element)

Find and remove (all occurences) of a given Treex::PML::Seq::Element object in the sequence. Returns the number of elements removed.

$seq->delete_element (element)

Find and remove (all occurences) of a given Treex::PML::Seq::Element object in the sequence. Returns the number of elements removed.

$seq->delete_value (value)

Find and remove all elements with a given value. Returns the number of elements removed.

$seq->index_of ($value)

Search the sequence for a particular value and return the index of its first occurence in the sequence.

Note: Use $seq->elements_list->index_of($element) to search for a Treex::PML::Seq::Element.

$list->empty ()

Remove all values from the sequence.

AUXILIARY FUNCTIONS

Treex::PML::Seq::content_pattern2regexp($pattern)

This utility function converts a given sequence content pattern string into a Perl regular expression. The resulting expression matches a list of element 'tags', where a tag is an element name surrounded by < and >. For example, the content pattern 'A,#TEXT,(B+|C)*' translates roughly to '<A><\#TEXT>(?:(?:<B>)+(?:<C>))*' and matches (a substring of) each of the following strings:

'<A><#TEXT>'
'foo<A><#TEXT><B><B><C>bar'
'<A><#TEXT><B><C><D>'

SEE ALSO

Treex::PML, Treex::PML::Factory, Treex::PML::Schema, Treex::PML::Seq::Element, Treex::PML::List

COPYRIGHT AND LICENSE

Copyright (C) 2006-2010 by Petr Pajas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.