Navigation.pm

This module exposes basic methods for navigation and query of universaltext.

This module extends UText class methods. It provides a cursor for reading an universaltext.

Note: this cursor is independent from the cursor used to write into a text with set() etc.

Synopsis

use UText::UText;
$ut = new UText;
my $selector = '... select some text units ...';
$ut->foreach($selector, sub { [... current child at $ut ...] });
$ut=undef;

Cursors

foreach

Visits each item returned by a selector. If the selector is empty, it loops through all children. It can be called with a scalar pattern or with a function as parameter.

1. foreach($selector, $pattern)

Loops through all items returned by the selector and evaluates for each of them the pattern.

The return value of each evaluation is concatenated and returned.

Example, to print out the name of each child unit:

print $ut->foreach('', '[u]');

2. foreach($selector, $function)

Loops through all items returned by the selector and calls for each of them the function.

The return value of function call is concatenated and returned.

For example, this outputs the same as above:

$ut->foreach('', sub { print $ut->out('[u]') });

The called function gets the UText object as its only parameter.

$ut->foreach('<selector>', \&myfunc);
sub myfunc
{
    my $self = shift;
    [... do something with the $self UText object here ...]
}

Note: The selector can contain ustring tags, they get expanded before opening the cursor. For example $ut->foreach('[v]') opens a cursor passing it the binary contents of the current unit as selector.

Note: nested cursors are possible. No level limit. To apply doSomething() recursive to all child units, beginning with current unit:

$ut = new UText;
[...]
doSomething();
[...]
sub doSomething
{
    [... do something to current unit here ...]
    $ut->foreach('', sub { doSomething() });
}

The method foreach is a shortcut for this:

$selector = $self->out($selector) if $selector;
for($ut->cursor_open($selector);
	!$ut->cursor_end();
	$ut->cursor_step)
{
    &$function($ut);
}
$ut->cursor_close();

cu Change Unit

$ut->cu($selector) jumps to the first unit returned by the selector.

cursor_open

cursor_open([$selector[,$type]])

Opens a cursor which contains all units returned by the selector.

If $type is ”alfa“, children appear in alfabetical order.

After opening, the current unit is the first one in cursor.

Note: Other as the functions foreach, getVar, getUnit etc. the function cursor_open does not expand the selector string before opening it, thus are here ustring tags not supported.

cursor_step

Goes to the next unit at last opened cursor.

cursor_end

Returns true iif end of last opened cursor was reached.

cursor_close

Closes last opened cursor. After closing, current unit is the one at which cursor was opened (restored).

Retrieve Current Unit Information

get

get($link)

Counterpart to set(). It returns an array reference:

	role => ...,
	type => ...,
	ref => ...,
	unit => ... ,
	children => N,
	roles =>...
	bin =>...

Same fields as set() (except level, bin) plus this ones:

• children amount of children units
• roles a hash { role1 => N1, role2 => N2, ...} returning the amount of children for each existing role
• bin a string with this values and meanings:
  • ”NA“ if field is not binary
  • ”present“ if binary data available
  • ”missing“ if field is binary but no data has ben loaded

If no $link, get returns data for the current unit. Possible $link values: role, type, punit, ptype. These return information respectively for the role, type, parent unit und parent type of current unit.

get_field

get_field('role-name');

returns the binary data associated to the given field, which must be a child of the current unit. if missing, returns ''. The current unit remains unchanged.

get_fields('role1','role2',...);

same but returns a list of values, each corresponding to a field in the parameter list.

is_bin

returns whether the current unit is binary

get_bin

returns the binary data associated to the current field. if missing, returns '', it fails if not a binary field

get_binx

get_binx($link,$role)

makes jump($link,$role) and returns get_bin(), it does not change current id

isType

isType($typename)

returns 1 if the current unit has the given type (or a descendant subtype of it) and 0 otherwise.

get_childnames

get_childnames(), get_childnames($role)

returns an array with child names in alfabetical order. if $role is present, it returns only children with this role, otherwise all. (Note that this method only returns named children)

node_date

node_date(), node_date('up')

returns the update time of the current unit. The update time of a node is automatically set to the last update time of the node and all its descendants.

node_date('cr')

returns the creation time of the current unit. The creation time of a node is automatically set to the first creation time of the node and all its descendants.

node_date($type,$unit)

returns the creation or update time of the unit named $unit.

When node_date is invoked in list context it returns a pair of values ($cr,$up) with creation and update time (the type is ignored if given).

Retrieve Selector Information

The following functions can be called with a selector containing ustring tags, they get expanded before opening the cursor.

getVar

getVar()

returns the value of the current unit, that is its own binary data or, if it is not a binary unit, the binary data of its default binary child.

getVar($selector)

returns the value of the given selector. The current unit remains unchanged.

getVars($selector1,$selector2,...)

same but returns a list of values, each corresponding to a selector in the parameter list.

getUnitProperty

getUnitProperty($property)

getUnitProperty($property,$selector)

returns the name of the $property for the given $selector. If no selector is given, it refers to the current unit.

Property must be one of: unit, role, type, ref, children, roles, bin (correspond to get, s. above). For debug purposes there is also available the property ”cid“, which returns the internal unit ID.

getUnitName

getUnitName()

getUnitName($selector)

returns the name of the current unit or of the first unit returned by the selector. Alias for getUnitProperty('unit',...).

getCount

getCount($selector)

returns the amount of items that the given selector returns. The current unit remains unchanged.

cnum

$ut->{cnum} returns the ordinal number of the current unit inside a cursor. If called after a cursor is closed, it returns the number of items the cursor had.

Older navigation methods

This methods are deprecated and might be soon droped.

copen

copen($link,$parameter)

Saves current id and jumps to the given parameters (s. jump() below).

cclose

Restores last copen()-ed id.

jump

jump($link,$parameter)

Selects a unit relative to current one according to $link:

• unit - selects unit with name $parameter
• role, type - role/type of current unit
• punit, ptype - unit/type of parent unit
• next, prev - (deprecated!) next/previous unit (same parents)
• first,last - first/last child of current unit
• rnext, rprev - (deprecated!) next/previous unit (same parents) for given role $parameter
• rfirst,rlast - first/last child of current unit for given role $parameter

Jump returns the $id of this unit. If not found, $id is undefined and current not changed.

Note: instead of next,prev,rnext,rprev you should use a cursor, which is more efficient!