Hub::Perl::Language

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- INTERNAL
- AUTHOR
- COPYRIGHT
- UPDATED

# NAME

Hub::Perl::Language -

Part of the Hub Library

Top

# SYNOPSIS

Top

# DESCRIPTION

Top

# METHODS

abort | cpref | getbyname | min | sortkbyv
array | dice | getgid | objopts | subfield
asa | diff | getuid | opts | subhash
asarray | digout | hash | replace | subst
bestof | expect | hashget | rmsubhash | touch
check | fear | intdiv | rmval | uniq
checksum | flatten | max | scalar
cmdopts | flip | merge | sizeof

abort

       Usage: abort
       Usage: abort -msg => 'Croak message'
       Usage: abort -back => LEVEL

  Croak nicely.

array

  is the passed in thingy an ARRAY reference?

asa
  As ARRAY

  Example: This example:

          join 'X', asa(undef);

  matches:

asarray

       Usage: asarray HASHREF|ARRAYREF [KEY] [OPTIONS]

  Turn a hashref of hashref's, or an array of hashref's into an array.

  Sort by KEY

  OPTIONS

       --asref              Return a reference instead
       --lose               Lose the key (for hash references)
       --filter:key=val     Only include items where key eq val

  Unless --lose is specified, we will modify the provided hash, storing the outer key as '_id' of each subhash.

bestof

       Usage: bestof @list
       Usage: bestof @list, -by=max|min|def|len|gt|lt

  Best value by criteria (default 'def').

check
  True if all items in list pass the test.

       Usage: check [OPTIONS], [TEST], LIST

  OPTIONS:

        -opr    (or|and|xor)                            Operator  (default: 'and')

  TEST:

        -test   (def|num|str|match|blessed|eval)        Test type (default: 'def')
        -isa    EXPR
        -ref    EXPR

  OPERATORS:

        and             True when all items pass the test.

        or              True when any single item passes the test.

        xor             Alternation pattern. True unless two consecutive values
                        both pass or fail the test.

  BASIC TEST:

        def             Items are defined
        num             Items are numeric
        str             Items are *not* numeric

  OTHER TESTS:

        match=EXPR      Items match EXPR
        eval            Items are eval'd and truth is based on $@.  Note that the
                        eval *actually* happens, so don't do anything that will
                        break your code.  The intention of this check is for:

  This example returns: abort:

          my $compression = check( '-test=eval', 'use IO::Zlib' ) ? 1 : 0;

  STRUCTURE TESTS:

        blessed         Items are blessed
        ref=EXPR        Item's ref matches EXPR (does *not* include @ISA)
        isa=EXPR        Item's ref or @ISA match EXPR.  Much like UNIVERSAL::isa
                        except allows regular expressions.

  none are defined returns: false:

          check( undef, undef, undef );

  only one is defined returns: false:

          check( 1, undef );

  both are defined returns: true:

          check( 1, 1 );

  one is defined returns: true:

          check( 1, undef, -opr => 'or' );

  This example returns: false:

          check( -opr => 'xor', 1, 1 );

  This example returns: false:

          check( -opr => 'xor', undef, undef );

  This example returns: true:

          check( -opr => 'xor', undef, 1 );

  This example returns: true:

          check( -opr => 'xor', 1, undef );

  This example returns: true:

          check( -opr => 'xor', 1, undef, 1, undef );

  This example returns: false:

          check( -opr => 'xor', 1, undef, 1, 1, undef );

  This example returns: true:

          check( -opr => 'xor', undef, 1, undef, 1 );

checksum

  Hub::checksum( @params )

  Create a unique identifier for the provided data

  Params can be scalars, hash references, array references and the like. We use the HashFile's print routine to transform nested structures into flat strings. As for performance, improvements should be made in the HashFile module. The only reason I create a new instance of HashFile each time is because I know there are symbol tables (such as the order of elements) in that class which get update when the print method is called.

cmdopts
  Extract short and long options from @ARGV

       Usage: cmdopts \ARRAY
       Usage: cmdopts \ARRAY, \HASH

  Convienence method which deals with short single-dash and long double-dash options.

cpref
  Recursively clone the reference, returning a new reference.

  The Clone module found on CPAN crashes under my mod_perl and FastCGI test servers...

  Note: Have not tested recursive references.

dice
  Break apart the string

       Usage: dice STRING

diff

       Usage: diff &HASH, &HASH

  Creates a nest of the differences between the two provided. If a conflict of types (with the same key) is encounterred, the right-hand sturcture is used.

  NOTE: Although this routine compares contents, it returns references to the original hashes (use cpref on the result to detatch.)

digout

       Usage: digout REF, ID

  Return an array of all nested values in an order that can be processed.

  NOTE! Scalar values are returned as references.

  See how 'packdata' uses this method to dereference.

  Arrays are ignored unless their members are hashes with an _id member.

  Reverse the results of this array to process data in a way that the children are affected before their parents.

expect
  Croak if arguments do not match their expected type

       Usage: expect [OPTIONS], [TEST], LIST

  OPTIONS:

        -back   \d      # Carp level (for reporting further up the callstack)
        -not    0|1     # Invert the result

  TESTS:

        -blessed        # All LIST items are blessed
        -match=EXPR     # All LIST items match /EXPR/
        -ref=EXPR       # All LIST items' ref match /EXPR/

  By default, LIST is made up of key/value pairs, where the key is the type (what `ref()` will return) and the value is what will be tested. LIST may contain one or more key/value pairs such as:

        HASH            => arg
        REF             => arg
        My::Package     => arg

fear

  Croak if arguments match their feared type.

  This is a shortcut to expect with a '-not=1' option.

flatten

flip

  given a hash reference, swap keys with values and return a new hash reference.

getbyname

getgid

       Usage: getgid

  Return the GID of the user of the provided login id.

getuid

       Usage: getuid

  Return the UID of the user of the provided login id.

hash

  is the passed in thingy a HASH reference?

hashget

       Usage: hashget KEY, HASHREF

  Get a nested hash member using the colon-delimited key format.

intdiv
  Integer division

       Usage: intdiv $DIVIDEND, $DIVISOR

  Returns an array with the number of times the divisor is contained in the dividend, and the remainder.

max
  Maximum value

       Usage: max @LIST

  Returns the greatest element in a set.

merge

       Usage: merge TARGET_HREF, SOURCE_HREF..., OPTION...

  Merges the provided hashes. The first argument (destination hash) has precedence (as in values are NOT overwritten) unless --overwrite is given.

  OPTIONS:

        --overwrite             Overwrite values as they are encounterred.

        --prune                 Gives the destination hash the same structure as
                                the source hash (or the composite of all which is
                                in common when multiple source hashes are provided).

                                If the destination is missing a value, it is
                                initialized from the source hash.

                                If the destination has a value which is not in all
                                of the source hashes, it is deleted.

        --keeparrays            When the destination contains the same key as the
                                source, but the destination is an array where the
                                source is a hash, take all of the hash elements and
                                merge them into the array.

min
  Minimum value

       Usage: min @LIST

  Returns the least element in a set.

objopts
  Split @_ into ($self,$opts), leaving @_ with remaining items.

       Usage: objopts \ARRAY

  Convienence method for splitting instance method parameters.

  Returns an array.

opts

       Usage: opts [OPTIONS], \ARRAY, [\HASH]

  Split parameter arrays into options and arguments.

  OPTIONS:

        -prefix=EXPR            # specify option prefix, default is single dash (-).

        -assign=EXPR            # specify assignment character, default is the
                                  equal sign (=).

        -append=EXPR            # specify append character, default is the
                                  plus sign (+).

  In array context, we return two references. Which may cause confusion:

         my %opts = Hub::opts( \@_ );                # Wrong!
         my $opts = Hub::opts( \@_ );                # Correct!
         my ($opts,$args) = Hub::opts( \@_ );        # Correct!

  Options are extracted (via splice) from the referenced array. The advantage is both for performance (don't make a copy of the array), and so you may use @_ (or @ARGV, etc) normally, as data:

  Example: at-underscore contains everyting but the '-with' option:

         sub myjoin {
            my $opts = Hub::opts( @_ );
            return join( $$opts{'with'}, @_ );

  matches:

          a;b;c;d

  1. Arguments are elements which do *not* begin with a dash (-).

  2. Options are elements which begin with a single dash (-) and are not negative numbers.

  3. An option of '-opts' is reserved for passing in already parsed option hashes.

  4. Options will have their leading dash (-) removed.

  5. Options values are formed as:

        Given:                  opt1 will be:       because:

        -opt1=value             'value'             contains an equal sign
        -opt1 nextelem          'nextelem'          next element is *not* an option
        -opt1 -option2          1                   next element is also an option
        -opt1                   1                   it is the last element
        -opt1                   1                   it is the last element
        -opt1=a -opt1=b         b                   last one wins
        -opt1=a +opt1=b         [ 'a', 'b' ]        it was specified using '+'
        +opt1=a +opt1=b         [ 'a', 'b' ]        they can both be '+'

  For example:

        my($opts,$args) = Hub::opts( [ 'a', 'b', '-c' => 'c', '-x', '-o=out' ] );

        print "Opts:\n", Hub::hffmt( $opts );
        print "Args:\n", Hub::hffmt( $args );

  Will print:

        Opts:
        c => c
        o => out
        x => 1
        Args:
        a
        b

replace

       Usage: replace MATCHING_REGEX, SUBSTITUTION_REGEX, TEXT

  Do a s/// operation on a given segment of the string.

  For example, say we want to remove the ': ;' pattern from the style portion, but not from the data portion:

        <div style="font-family: ;">keep this: ;stuff</div>

  Use this method as:

        $text = Hub::replace( "style=\".*?\"", "s/[\\w\\-]+\\s*:\\s*;//g", $text );

rmsubhash

  remove an element from an array of hash refs, by some key's value

rmval

  remove an element from a hash or array, by value

scalar

  is the passed in thingy a SCALAR? NOTE: This does not mean a SCALAR ref!

sizeof
  Integer size of hashes, arrays, and scalars

       Usage: sizeof \%hash
       Usage: sizeof \@array
       Usage: sizeof \$scalar_ref
       Usage: sizeof $scalar
       Usage: sizeof \%more, @than, $one

  Sizes are computed as follows:

        HASH    - Number of keys in the hash
        ARRAY   - Number of elements
        SCALAR  - Length as returned by C<length()>

  The total size of all arguments is returned.

  Example: Hash:

          sizeof( { a=>1, b=>2, c=>3 } );

  matches:

          3

  Example: Array:

          sizeof( [ 'a1', 'b2', 'c3' ] );

  matches:

          3

  Example: Scalar:

          sizeof( "abc"                );

  matches:

          3

  Example: Scalar (ref):

          sizeof( \"abc"               );

  matches:

          3

  Example: Nothing:

          sizeof( undef                );

  matches:

          0

  Example: Multiple values:

          sizeof( "a", "b", "c"        );

  matches:

          3

sortkbyv

  given a hash reference, return an array of its keys sorted by their values.

subfield

       Usage: subfield POS, DELIMITER, STRING

  Given a delimited string, return the substring given a field position (zero based).

subhash

       Usage: subhash REF, KEY, VALUE

  Return the matching subhashes, which have KEY eq VALUE

  VALUE can be:

        'exactmatch'
        '~regex'

  The '~' is used to make the determination.

  Return value:

        When there *are* matches:
            wantarray ? all matches
            otherwise   the first match
        otherwise,
            wantarray ? an emtpy list
            otherwise,  undef

subst

       Usage: subst

  Call to perl's substitution operator. Represented here as a function to facilitate transformation by reducing the need for temporaries. In essence, the goal is to reduce:

        my $bakname = getfilename();
        $bakname =~ s/\.db$/\.bak/;

  to:

        my $bakname = Hub::subst( getfilename(), '\.db$', '.bak' );

  without modifying the original string returned by getfilename().

touch

       Usage: touch LIST

  Changes the access and modification times on each file of a list of files.

uniq

  given an array or hash reference, return the a new reference to an identical array, minus the duplicates. if a hash reference is passed, the hash's keys are used to determine uniqueness.

  return structure is sorted.

Top

# INTERNAL

_assignopt | _diff_arrays | _getId | _mergeElement | _prioritysort
_compscalar | _diff_hashes | _mergeArray | _mergeHash

_assignopt

       Usage: _assignopt \%options, \%, $key, $val

  Assign an option value.

_compscalar

       Usage: _compscalar

  Use cmp or <=> if the data is all numbers (decimal points included)

_diff_arrays

       Usage: _diff_arrays &ARRAY, &ARRAY

  Difference between two arrays.

_diff_hashes

       Usage: _diff_hashes &HASH, &HASH

  Difference between two hashes.

_getId

_mergeArray

_mergeElement

_mergeHash

_prioritysort

       Usage: _prioritysort

  Sorts by a key, with the intention of re-ordering. In order to do so, the secondary sort key is set to the *old* value of the item. For instance, we have three items, with sort values 1, 1, and 2:

        item1: 0
        item2: 1
        item3: 2

  So, to move item1 to the second position, set the _sort key to 1, and the _sort2 key to 0 (it's old value).

Top

# AUTHOR

Ryan Gies

Top

# COPYRIGHT

Copyright (c) 2006 Livesite Networks, LLC. All rights reserved.

Copyright (c) 2000-2005 Ryan Gies. All rights reserved.

Top

# UPDATED

This file created by on at

Top