NAME

Gestinanna::Util - utility functions

SYNOPSIS

 use Gestinanna::Util qw(:path);

 my $regex = path2regex($path)
 my $cmp   = path_cmp($path_a, $path_b);

 use Gestinanna::Util qw(:hash);

 my $new_hash = deep_merge_hash(@hashes);

DESCRIPTION

This module provides utility functions that have no better place to be. Sets of utility functions may be imported by specifying their tags.

:path: Imports: path2regex, path_cmp

PATHS

Paths are made up of a sub-set of the XPath language:

/: The slash (/) is the component separator. Alone, it describes the root of the resource heirarchy.
//: The double slash (//) stands in place of any number of components (zero or more). Alone, it matches any possible path that does not specify attributes or a final component. To match any component with any attributes, use //*|//*@*.
@: The at sign (@) is the attribute separator. A path should only have one. It separates the final component from any attribute. If no attribute follows it, it stands for the general collection of attributes for an object.
|: The pipe symbol (|) separates paths which together specify a union.
&: The ampersand (&) separates paths which together specify an intersection. Intersection has higher precedence to union. For example, the path //a/* & //*@name | //b/* is considered to be (//a/* & //*@name) | //b/*, not //a/* & (//*@name | //b/*). There are no parenthesis for grouping in actual path expressions.
!: An odd number of initial bangs (!) will negate the following clause, up to a pipe (|) or ampersand (&). An even number of initial bangs will have no effect.

Examples

The following are some examples of paths.

//*: This matches any path. Attaching attributes to this path will apply them to all objects.
//*@name: This matches the name attribute of all objects.
//*/*: This matches any component that is not at the top-level.
!//a//* & //b//*: This matches any path that has a b component and not an a component.

METHODS

path2regex

This method will translate a path to a regular expression. The path_cmp method uses this for certain comparisons.

Some example translations (cleaned up a little):

//*@*

 qr(?-xism:(?:
     /+           # one or more initial slashes
     ((?:
         [^/@|&]+
         /+
     )*)          # any number of slash-separated path components
     (?:/)*       # any number of trailing slashes
     ([^/@|&]+)   # component
     @
     ([^/@|&]+)   # attribute
 ) )x

/*/a | /*/b

 qr(?-xism:
     (?:/([^/@|&]+)/b)  # /<any component>/b
     |                  # OR
     (?:/([^/@|&]+)/a)  # /<any component>/a
 )x

/*/a & /*/*@*

 qr(?-xism:(?:
    (?(?=/([^/@|&]+)/a)   # if we match /<any component>/a
        (?:               # then match:
            /
            ([^/\@\|&]+)  # any component
            /
            ([^/\@\|&]+)  # any component
            @
            ([^/\@\|&]+)  # any attribute
        )
    )                     # otherwise, we fail
 ))x

!//a//* & //b//*

 qr(?-xism:(?:
    (?(?=
        (?:
            (?! /+((?:[^/@|&]+/+)*)(?:/)*a/+((?:[^/@|&]+/+)*)(?:/)*([^/@|&]+))
            |
            (?:!/+((?:[^/@|&]+/+)*)(?:/)*a/+((?:[^/@|&]+/+)*)(?:/)*([^/@|&]+))
        )
      )
      (?:
                /+((?:[^/@|&]+/+)*)(?:/)*b/+((?:[^/@|&]+/+)*)(?:/)*([^/@|&]+)
      )
    )
 ))x

path_cmp

Comparisons of intersections with other intersections are not supported (i.e., only one of the paths should have an intersection). Likewise, only one of the paths should contain negations.

This method returns one of four values:

undef: The two paths describe disjoint sets.
0: The two paths describe overlapping sets. Both of the paths describe elements not described by the other.
1: The first path describes a superset of the set described by the second path, or the two paths describe equivalent sets.
-1: The first path describes a subset of the set described by the second path.

AUTHOR

James G. Smith, <jsmith@cpan.org>

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CPAN RT