Provided by: libbio-perl-perl_1.6.923-1_all bug

NAME

       Bio::DB::HIV::HIVQueryHelper - Routines and packages used by Bio::DB::HIV and
       Bio::DB::Query::HIVQuery

SYNOPSIS

         Used in Bio::DB::Query::HIVQuery. No need to use directly.

DESCRIPTION

       "Bio::DB::HIV::HIVQueryHelper" contains a number of packages for use by
       Bio::DB::Query::HIVQuery. Package "HIVSchema" parses the "lanl-schema.xml" file, and
       allows access to it in the context of the relational database it represents (see APPENDIX
       for excruciating detail). Packages "QRY", "R", and "Q" together create the query string
       parser that enables NCBI-like queries to be understood by "Bio::DB::Query::HIVQuery". They
       provide objects and operators to perform and simplify logical expressions involving "AND",
       "OR", and "()" and return hash structures that can be handled by
       "Bio::DB::Query::HIVQuery" routines.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Mark A. Jensen

       Email maj@fortinbras.us

CONTRIBUTORS

       Mark A. Jensen

APPENDIX

       The rest of the documentation details each of the contained packages.  Internal methods
       are usually preceded with a _

   HIVSchema -  objects/methods to manipulate a version of the LANL HIV DB schema
       HIVSchema SYNOPSIS

           $schema = new HIVSchema( 'lanl-schema.xml' );
           @tables = $schema->tables;
           @validFields = $schema->fields;
           @validAliases = $schema->aliases;
           @query_aliases_for_coreceptor = $schema->aliases( 'SEQ_SAMple.SSAM_second_receptor' );
           $pk_for_SequenceEntry = $schema->primarykey('SequenceEntry');    # returns 'SequenceEntry.SE_id'
           $fk_for_SEQ_SAMple_to_SequenceEntry =
                     $schema->foreignkey('SEQ_SAMple', 'SequenceEntry');    # returns 'SEQ_SAMple.SSAM_SE_id'

           $table = $schema->tablepart('SEQ_SAMple.SSAM_badseq');           # returns 'SEQ_SAMple'
           $column = $schema->columnpart('SEQ_SAMple.SSAM_badseq');         # returns 'SSAM_badseq'

       HIVSchema DESCRIPTION

       HIVSchema methods are used in Bio::DB::Query::HIVQuery for table, column, primary/foreign
       key manipulations based on the observed Los Alamos HIV Sequence Database (LANL DB) naming
       conventions for their CGI parameters. The schema is contained in an XML file
       ("lanl-schema.xml") which is read into an HIVSchema object, in turn a property of the
       HIVQuery object. HIVSchema methods are used to build correct cgi queries in a way that
       attempts to preserve the context of the relational database the query parameters
       represent.

       HIVSchema CONSTRUCTOR

       HIVSchema::new

        Title   : new
        Usage   : $schema = new HIVSchema( "lanl-schema.xml ");
        Function:
        Example :
        Returns : an HIVSchema object
        Args    : XML filename

       HIVSchema INSTANCE METHODS

       HIVSchema tables

        Title   : tables
        Usage   : $schema->tables()
        Function: get all table names in schema
        Example :
        Returns : array of table names
        Args    : none

       HIVSchema columns

        Title   : columns
        Usage   : $schema->columns( [$tablename] );
        Function: return array of columns for specified table, or all columns in
                  schema, if called w/o args
        Example :
        Returns :
        Args    : tablename or fieldname string

       HIVSchema fields

        Title   : fields
        Usage   : $schema->fields();
        Function: return array of all fields in schema, in format "table.column"
        Example :
        Returns : array of all fields
        Args    : none

       HIVSchema options

        Title   : options
        Usage   : $schema->options(@fieldnames)
        Function: get array of options (i.e., valid match data strings) available
                  to specified field
        Example :
        Returns : array of match data strings
        Args    : [array of] fieldname string[s] in "table.column" format

       HIVSchema aliases

        Title   : aliases
        Usage   : $schema->aliases(@fieldnames)
        Function: get array of aliases to specified field[s]
        Example :
        Returns : array of valid query aliases for fields as spec'd in XML file
        Args    : [an array of] fieldname[s] in "table.column" format

       HIVSchema ankh

        Title   : ankh (annotation key hash)
        Usage   : $schema->ankh(@fieldnames)
        Function: return a hash translating fields to annotation keys for the
                  spec'd fields.
                  (Annotation keys are used for parsing the tab-delimited response
                  to Bio::DB::Query::HIVQuery::_do_lanl_request.)
        Example :
        Returns : hash ref
        Args    : [an array of] fieldname[s] in "table.column" format

       HIVSchema tablepart

        Title   : tablepart (alias: tbl)
        Usage   : $schema->tbl(@fieldnames)
        Function: return the portion of the fieldname[s] that refer to the
                  db table
        Example : $schema->tbl('SequenceEntry.SE_id'); # returns 'SequenceEntry'
        Returns : table name as string
        Args    : [an array of] fieldname[s] in "table.column" format

       HIVSchema columnpart

        Title   : columnpart (alias: col)
        Usage   : $schema->col(@fieldnames)
        Function: return the portion of the fieldname[s] that refer to the
                  db column
        Example : $schema->col('SequenceEntry.SE_id'); # returns 'SE_id'
        Returns : column name as string
        Args    : [an array of] fieldname[s] in "table.column" format

       HIVSchema primarykey

        Title   : primarykey [alias: pk]
        Usage   : $schema->pk(@tablenames);
        Function: return the primary key of the specified table[s], as judged by
                  the syntax of the table's[s'] fieldnames
        Example : $schema->pk('SequenceEntry') # returns 'SequenceEntry.SE_id'
        Returns : primary key fieldname[s] in "table.column" format, or null if
                  no pk exists
        Args    : [an array of] table name[s] (fieldnames are ok, table part used)

       HIVSchema foreignkey

        Title   : foreignkey [alias: fk]
        Usage   : $schema->fk($intable [, $totable])
        Function: return foreign key fieldname in table $intable referring to
                  table $totable, or all foreign keys in $intable if $totable
                  unspec'd
        Example : $schema->fk('AUthor', 'SequenceEntry'); # returns 'AUthor_AU_SE_id'
        Returns : foreign key fieldname[s] in "table.column" format
        Args    : tablename [, optional foreign table name] (fieldnames are ok,
                  table part used)

       HIVSchema foreigntable

        Title   : foreigntable [alias ftbl]
        Usage   : $schema->ftbl( @foreign_key_fieldnames );
        Function: return tablename of table that foreign keys points to
        Example : $schema->ftbl( 'AUthor.AU_SE_id' ); # returns 'SequenceEntry'
        Returns : tablename
        Args    : [an array of] fieldname[s] in "table.column" format

       HIVSchema find_join

        Title   : find_join
        Usage   : $sch->find_join('Table1', 'Table2')
        Function: Retrieves a set of foreign and primary keys (in table.column
                  format) that represents a join path from Table1 to Table2
        Example :
        Returns : an array of keys (as table.column strings) -or- an empty
                  array if Table1 == Table2 -or- undef if no path exists
        Args    : two table names as strings

       HIVSchema _find_join_guts

        Title   : _find_join_guts
        Usage   : $sch->_find_join_guts($table1, $table2, $stackref, \$found, $reverse)
                  (call with $stackref = [], $found=0)
        Function: recursive guts of find_join
        Example :
        Returns : if a path is found, $found==1 and @$stackref contains the keys
                  in table.column format representing the path; if a path is not
                  found, $found == 0 and @$stackref contains garbage
        Args    : $table1, $table2 : table names as strings
                  $stackref : an arrayref to an empty array
                  \$found   : a scalar ref to the value 0
                  $rev : if $rev==1, the arrays of table names will be reversed;
                         this can give a shorter path if cycles exist in the
                         schema graph

       HIVSchema loadSchema

        Title   : loadHIVSchema [alias: loadSchema]
        Usage   : $schema->loadSchema( $XMLfilename )
        Function: read (LANL DB) schema spec from XML
        Example : $schema->loadSchema('lanl-schema.xml');
        Returns : hashref to schema data
                  Keys are fieldnames in "table.column" format.
                  Each value is a hashref with the following properties:
                  {name}    : HIVWEB 'table.column' format fieldname,
                              can be used directly in the cgi query
                  {aliases} : ref to array containing valid aliases/shortcuts for
                              {name}; can be used in routines creating the HTML query
                  {options} : ref to array containing valid matchdata for this field
                              can be used directly in the HTML query
                  {ankey}   : contains the annotation key for this field used with
                              Bioperl annotation objects
                  {..attr..}: ..value_of_attr.. for this field (app-specific metadata)
        Args    :

       HIVSchema _sfieldh

        Title   : _sfieldh
        Usage   : $schema->_sfieldh($fieldname)
        Function: get hashref to the specified field hash
        Example :
        Returns : hashref
        Args    : fieldname in "table.column" format

   Class QRY -  a query algebra for HIVQuery
       QRY SYNOPSIS

         $Q = new QRY(
                      new R(
                             new Q('coreceptor', 'CXCR4'),
                             new Q('country', 'ZA')
                            )
                      );
         QRY::Eq(QRY::And($Q, $Q), $Q);                     # returns 1
         QRY::Eq(QRY::Or($Q, $Q), $Q);                      # returns 1
         $Q2 = $Q1->clone;
         $Q2 = new QRY(
                       new R(
                              new Q( 'coreceptor', 'CCR5' ),
                              new Q( 'country', 'ZA')
                             )
                      );
         (QRY::And($Q, $Q2))->isnull;                       # returns 1
         $Q3 = QRY::Or($Q, $Q2);
         print $Q3->A;                                      # prints '(CCR5 CXCR4)[coreceptor] (ZA)[country]'

       QRY DESCRIPTION

       The QRY package provides a query parser for Bio::DB::Query::HIVQuery. Currently, the
       parser supports AND, OR, and () operations. The structure of the LANL cgi makes it tricky
       to perform NOTs, though this could be implemented if the desire were great.

       Two class methods do the work. "QRY::_parse_q" does a first-pass parse of the query
       string. "QRY::_make_q" interprets the parse tree as returned by "QRY::_parse_q" and
       produces an array of hash structures that can be used directly by
       "Bio::DB::Query::HIVQuery" query execution methods. Validation of query fields and options
       is performed at the "Bio::DB::Query::HIVQuery" level, not here.

       "QRY" objects are collections of "R" (or request) objects, which are in turn collections
       of "Q" (or atomic query) objects. "Q" objects represent a query on a single field, with
       match data options "OR"ed together, e.g. "(A B)[subtype]". "R" objects collect "Q" objects
       that could be processed in a single HTTP request; i.e., a set of atomic queries each
       having different fields "AND"ed together, such as

         (A B)[subtype] AND ('CCR5')[coreceptor] AND (US CA)[country]

       The "QRY" object collects "R"s that cannot be reduced (through logical operations) to a
       single HTTP request, e.g.

         ((C)[subtype] AND (SI)[phenotype]) OR ( (D)[subtype] AND (NSI)[phenotype] ),

       which cannot be got in one go through the current LANL cgi implementation (as far as I can
       tell). The parser will simplify something like

         ((C)[subtype] AND (SI)[phenotype]) OR ((C)[subtype] AND (NSI)[phenotype])

       to the single request

         (C)[subtype] AND (NSI SI)[phenotype]

       however.

       The operators "&" and "|" are overloaded to "QRY::And" and "QRY::Or", to get Perl
       precedence and grouping for free. "bool" is overloaded to get symbolic tests such as "if
       ($QRY) {stuff}". "==" is overloaded with "QRY::Eq" for convenience. No overloading is done
       for "R" or "Q".

       QRY _make_q

        Title   : _make_q
        Usage   : QRY::_make_q($parsetree)
        Function: creates hash structures suitable for HIVQuery from parse tree
                  returned by QRY::_parse_q
        Example :
        Returns : array of hashrefs of query specs
        Args    : a hashref

       QRY _make_q_guts

        Title   : _make_q_guts (Internal class method)
        Usage   : _make_q_guts($ptree, $q_expr, $qarry, $anarry)
        Function: traverses the parse tree returned from QRY::_parse_q, checking
                  syntax and creating HIVQuery-compliant query structures
        Example :
        Returns :
        Args    : $parse_tree (hashref), $query_expression (scalar string ref),
                  $query_array (array ref : stack for returning query structures),
                  $annotation_array (array ref : stack for returning annotation
                  fields)

       QRY _parse_q

        Title   : _parse_q
        Usage   : QRY::_parse_q($query_string)
        Function: perform first pass parse of a query string with some syntax
                  checking, return a parse tree suitable for QRY::_make_q
        Example : QRY::_parse_q(" to[be] OR (not to)[be] ");
        Returns : hashref
        Args    : query string

       QRY CONSTRUCTOR

       QRY Constructor

        Title   : QRY constructor
        Usage   : $QRY = new QRY()
        Function:
        Example :
        Returns :
        Args    : array of R objects, optional

       QRY INSTANCE METHODS

       QRY requests

        Title   : requests
        Usage   : $QRY->requests
        Function: get/set array of requests comprising this QRY object
        Example :
        Returns :
        Args    : array of class R objects

       QRY put_requests

        Title   : put_requests
        Usage   : $QRY->put_request(@R)
        Function: add object of class R to $QRY
        Example :
        Returns :
        Args    : [an array of] of class R object[s]

       QRY isnull

        Title   : isnull
        Usage   : $QRY->isnull
        Function: test if QRY object is null
        Example :
        Returns : 1 if null, 0 otherwise
        Args    :

       QRY A

        Title   : A
        Usage   : print $QRY->A
        Function: get a string representation of QRY object
        Example :
        Returns : string scalar
        Args    :

       QRY len

        Title   : len
        Usage   : $QRY->len
        Function: get number of class R objects contained by QRY object
        Example :
        Returns : scalar
        Args    :

       QRY clone

        Title   : clone
        Usage   : $QRY2 = $QRY1->clone;
        Function: create and return a clone of the object
        Example :
        Returns : object of class QRY
        Args    :

       QRY CLASS METHODS

       QRY Or

        Title   : Or
        Usage   : $QRY3 = QRY::Or($QRY1, $QRY2)
        Function: logical OR for QRY objects
        Example :
        Returns : a QRY object
        Args    : two class QRY objects

       QRY And

        Title   : And
        Usage   : $QRY3 = QRY::And($QRY1, $QRY2)
        Function: logical AND for QRY objects
        Example :
        Returns : a QRY object
        Args    : two class QRY objects

       QRY Bool

        Title   : Bool
        Usage   : QRY::Bool($QRY1)
        Function: allows symbolic testing of QRY object when bool overloaded
        Example : do {stuff} if $QRY1 *same as* do {stuff} if !$QRY1->isnull
        Returns :
        Args    : a class QRY object

       QRY Eq

        Title   : Eq
        Usage   : QRY::Eq($QRY1, $QRY2)
        Function: test if R objects in two QRY objects are the same
                  (irrespective of order)
        Example :
        Returns : 1 if equal, 0 otherwise
        Args    : two class QRY objects

   Class R - request objects for QRY algebra
       R SYNOPSIS

         $R = new R( $q1, $q2 );
         $R->put_atoms($q3);
         $R->del_atoms('coreceptor', 'phenotype');
         return $R->clone;
         $R1 = new R( new Q('subtype', 'B') );
         $R2 = new R( new Q('subtype', 'B C'),
                      new Q('country', 'US') );
         R::Eq( (R::And($R1, $R2))[0],
                new R( new Q('subtype', 'B' ),
                       new Q('country', 'US') ));                 # returns 1
         QRY::Eq( new QRY(R::Or($R1, $R2)), new QRY($R1, $R2) );  # returns 1
         R::In( (R::And($R1, $R2))[0], $R1 );                     # returns 1

       R DESCRIPTION

       Class R objects contain a list of atomic queries (class Q objects). Each class R object
       represents a single HTTP request to the LANL DB. When converted to a DB query, the class Q
       objects contained by an R object are effectively "AND"ed.

       R CONSTRUCTOR

       R constructor

        Title   : R constructor
        Usage   : $R = new R()
        Function: create a new R (request) object
        Example :
        Returns : class R (request) object
        Args    : optional, array of class Q objects

       R INSTANCE METHODS

       R len

        Title   : len
        Usage   : $R->len
        Function: get number of class Q objects contained in R object
        Example :
        Returns : scalar
        Args    :

       R atoms

        Title   : atoms
        Usage   : $R->atoms( [optional $field])
        Function: get array of class Q (atomic query) objects in class R object
        Example : $R->atoms(); $R->atoms('coreceptor')
        Returns : array of class Q objects (all Qs or those corresponding to $field
                  if present)
        Args    : optional, scalar string

       R fields

        Title   : fields
        Usage   : $R->fields
        Function: get array of fields of all Q objects contained in $R
        Example :
        Returns : array of scalars
        Args    :

       R put_atoms

        Title   : put_atoms
        Usage   : $R->put_atoms( @q )
        Function: AND an atomic query (class Q object) to the class R object's list
        Example :
        Returns : void
        Args    : an [array of] class Q object[s]

       R del_atoms

        Title   : del_atoms
        Usage   : $R->del_atoms( @qfields )
        Function: removes class Q objects from R object's list according to the
                  field names given in arguments
        Example :
        Returns : the class Q objects deleted
        Args    : scalar array of field names

       R isnull

        Title   : isnull
        Usage   : $R->isnull
        Function: test if class R object is null
        Example :
        Returns : 1 if null, 0 otherwise
        Args    :

       R A

        Title   : A
        Usage   : print $R->A
        Function: get a string representation of class R object
        Example :
        Returns : string scalar
        Args    :

       R clone

        Title   : clone
        Usage   : $R2 = $R1->clone;
        Function: create and return a clone of the object
        Example :
        Returns : object of class R
        Args    :

       R CLASS METHODS

       R In

        Title   : In
        Usage   : R::In($R1, $R2)
        Function: tests whether the query represented by $R1 would return a subset
                  of items returned by the query represented by $R2
        Example : print "R2 gets those and more" if R::In($R1, $R2);
        Returns : 1 if R1 is subset of R2, 0 otherwise
        Args    : two class R objects

       R And

        Title   : And
        Usage   : @Rresult = R::And($R1, $R2)
        Function: logical AND for R objects
        Example :
        Returns : an array containing class R objects
        Args    : two class R objects

       R Or

        Title   : Or
        Usage   : @Rresult = R::Or($R1, $R2)
        Function: logical OR for R objects
        Example :
        Returns : an array containing class R objects
        Args    : two class R objects

       R Eq

        Title   : Eq
        Usage   : R::Eq($R1, $R2)
        Function: test if class Q objects in two R objects are the same
                  (irrespective of order)
        Example :
        Returns : 1 if equal, 0 otherwise
        Args    : two class R objects

   Class Q -  atomic query objects for QRY algebra
       Q SYNOPSIS

           $q = new Q('coreceptor', 'CXCR4 CCR5');
           $u = new Q('coreceptor', 'CXCR4');
           $q->fld;                                 # returns 'coreceptor'
           $q->dta;                                 # returns 'CXCR4 CCR5'
           print $q->A;                             # prints '(CXCR4 CCR5)[coreceptor]
           Q::qeq($q, $u);                          # returns 0
           Q::qeq( Q::qor($q, $q), $q );            # returns 1
           Q::qin($u, $q)                           # returns 1
           Q::qeq(Q::qand($u, $q), $u );            # returns 1

       Q DESCRIPTION

       Class Q objects represent atomic queries, that can be described by a single LANL cgi
       parameter=value pair. Class R objects (requests) are built from class Qs. The logical
       operations at the higher levels ("QRY, R") ultimately depend on the lower level operations
       on Qs: "qeq, qin, qand, qor".

       Q CONSTRUCTOR

       Q constructor

        Title   : Q constructor
        Usage   : $q = new Q($field, $data)
        Function: create a new Q (atomic query) object
        Example :
        Returns : class Q object
        Args    : optional $field, $data strings

       Q INSTANCE METHODS

       Q isnull

        Title   : isnull
        Usage   : $q->isnull
        Function: test if class Q object is null
        Example :
        Returns : 1 if null, 0 otherwise
        Args    :

       Q fld

        Title   : fld
        Usage   : $q->fld($field)
        Function: get/set fld (field name) property
        Example :
        Returns : scalar
        Args    : scalar

       Q dta

        Title   : dta
        Usage   : $q->dta($data)
        Function: get/set dta (whsp-separated data string) property
        Example :
        Returns : scalar
        Args    : scalar

       Q A

        Title   : A
        Usage   : print $q->A
        Function: get a string representation of class Q object
        Example :
        Returns : string scalar
        Args    :

       Q clone

        Title   : clone
        Usage   : $q2 = $q1->clone;
        Function: create and return a clone of the object
        Example :
        Returns : object of class Q
        Args    :

       Q CLASS METHODS

       Q qin

        Title   : qin
        Usage   : Q::qin($q1, $q2)
        Function: tests whether the query represented by $q1 would return a subset
                  of items returned by the query represented by $q2
        Example : print "q2 gets those and more" if Q::qin($q1, $q2);
        Returns : 1 if q1 is subset of q2, 0 otherwise
        Args    : two class Q objects

       Q qeq

        Title   : qeq
        Usage   : Q::qeq($q1, $q2)
        Function: test if fld and dta properties in two class Q objects are the same
                  (irrespective of order)
        Example :
        Returns : 1 if equal, 0 otherwise
        Args    : two class Q objects

       Q qor

        Title   : qor
        Usage   : @qresult = Q::qor($q1, $q2)
        Function: logical OR for Q objects
        Example :
        Returns : an array of class Q objects
        Args    : two class Q objects

       Q qand

        Title   : qand
        Usage   : @qresult = Q::And($q1, $q2)
        Function: logical AND for R objects
        Example :
        Returns : an array of class Q objects
        Args    : two class Q objects

       Q INTERNALS

       Q unique

        Title   : unique
        Usage   : @ua = unique(@a)
        Function: return contents of @a with duplicates removed
        Example :
        Returns :
        Args    : an array

   Additional tools for Bio::AnnotationCollectionI
       Bio::AnnotationCollectionI SYNOPSIS (additional methods)

           $seq->annotation->put_value('patient_id', 1401)
           $seq->annotation->get_value('patient_ids')                   # returns 1401
           $seq->annotation->put_value('patient_group', 'MassGenH')
           $seq->annotation->put_value(['clinical', 'cd4count'], 503);
           $seq->annotation->put_value(['clinical', 'virus_load'], 150805);
           foreach ( qw( cd4count virus_load ) ) {
               $blood_readings{$_} = $seq->annonation->get_value(['clinical', $_]);
           }

       Bio::AnnotationCollectionI DESCRIPTION (additional methods)

       "get_value()" and "put_value" allow easy creation of and access to an annotation
       collection tree with nodes of Bio::Annotation::SimpleValue. These methods obiviate direct
       accession of the SimpleValue objects.

   get_value
        Title   : get_value
        Usage   : $ac->get_value($tagname) -or-
                  $ac->get_value( $tag_level1, $tag_level2,... )
        Function: access the annotation value assocated with the given tags
        Example :
        Returns : a scalar
        Args    : an array of tagnames that descend into the annotation tree

   put_value
        Title   : put_value
        Usage   : $ac->put_value($tagname, $value) -or-
                  $ac->put_value([$tag_level1, $tag_level2, ...], $value) -or-
                  $ac->put_value( [$tag_level1, $tag_level2, ...] )
        Function: create a node in an annotation tree, and assign a scalar value to it
                  if a value is specified
        Example :
        Returns : scalar or a Bio::AnnotationCollection object
        Args    : $tagname, $value scalars (can be specified as -KEYS=>$tagname,
                  -VALUE=>$value) -or-
                  \@tagnames, $value (or as -KEYS=>\@tagnames, -VALUE=>$value )
        Note    : If intervening nodes do not exist, put_value creates them, replacing
                  existing nodes. So if $ac->put_value('x', 10) was done, then later,
                  $ac->put_value(['x', 'y'], 20), the original value of 'x' is trashed,
                  and $ac->get_value('x') will now return the annotation collection
                  with tagname 'y'.

   get_keys
        Title   : get_keys
        Usage   : $ac->get_keys($tagname_level_1, $tagname_level_2,...)
        Function: Get an array of tagnames underneath the named tag nodes
        Example : # prints the values of the members of Category 1...
                  print map { $ac->get_value($_) } $ac->get_keys('Category 1') ;
        Returns : array of tagnames or empty list if the arguments represent a leaf
        Args    : [array of] tagname[s]