NAME
   RPSL::Parser - Router Policy Specification Language (RFC2622) Parser

SYNOPSIS
       # The new interface doesn't requires the creation of
       # a parser object anymore:
       use RPSL::Parser;
       my $data_structure = RPSL::Parser->parse( $data );

       ###########

       # Alternativelly, use the old and deprecated interface:
       use RPSL::Parser;
       # Create a parser
       my $parser = new RPSL::Parser;
       # Use it
       my $data_structure = $parser->parse($data);

DESCRIPTION
   This is a rather simplistic lexer and tokenizer for the RPSL language.

   It currently does not validate the object in any way, it just tries
   (rather hard) to grab the biggest ammount of information it can from the
   text presented and place it in a Parse Tree (that can be passed to other
   objects from the *RPSL* namespace for validation and more RFC2622
   related functionality).

PUBLIC METHODS
 "new()" deprecated
   Constructor. Handles the accessor creation and returns a new
   RPSL::Parser object.

   This method is deprecated, under request of some users. The RPSL::Parser
   interface will change, and there will be no need to create a "parser"
   object anymore.

 "parse( [ $rpsl_source | IO::Handle | GLOB ] )"
   Parses one RPSL object for each call, uses the parser internal fields to
   store the data gathered. This is the method you need to call to
   transform your RPSL text into a Perl data structure.

   It accepts a list or a scalar containing the strings representing the
   RPSL source code you want to parse, and can read it directly from any
   IO::Handle or "GLOB" representing an open file handle.

   This is a mixture between a class and a object method at this moment,
   due to the deprecation of the "new()" method. It can detect whenever it
   was called with a class as the first parameter, and will try to
   instantiate and use that class as the parser implementation.

ACCESSOR METHODS
 "comment()"
   Stores an array reference containing all the inline comments found in
   the RPSL text.

 "object"
   Stores a hash reference containing all the RPSL attributes found in the
   RPSL text.

 "omit_key"
   Stores an array reference containing all the position of the keys we
   must omit from the original RPSL text.

 "order"
   Stores an array reference containing an ordered list of RPSL attribute
   names, to enable the RPSL to be rebuilt from the parsed data version.

 "key"
   Stores the value found in the first RPSL attribute parsed. This is
   sometimes refered as the RPSL object key.

 "text"
   Stores an scalar containing the RPSL text to be parsed.

 "tokens"
   Stores an array reference containing an ordered list of tokens and token
   values produced by the tokenize method.

 "type"
   Stores a string representing the name of the first RPSL attribute found
   in the RPSL text parsed. The RFC 2622 requires that the first attribute
   declares the "data type" of the RPSL object declared.

Private Interface
 "_read_text( @input )"
   Checks if the first element from @input is a IO::Handle or a "GLOB", and
   reads from it. If the first element is not any type of file handle,
   assumes it's an array of scalars containing the text for the RPSL object
   to be parsed, "join()" it all toghether and feed it to the parser.

 "_tokenize()"
   This method breaks down the RPSL source code read by "read_text()" into
   tokens, and store them internally. For commodity, it returs a reference
   to the object itself, so you can chain up method calls.

 "_cleanup_attribute( $value )"
   Returns a cleaned-up version of the attribute passed in: no trailling or
   leading whitespace or newlines.

 "_store_attribute( $attribute_name, $attribute_value )"
   Auxiliary method. It clean up the value and store the attribute in the
   data structure being built, and does the necessary storage upkeep.

 "_store_comment( $comment_position_index, $attribute_and_comment_text )"
   This method extracts inline comments from the inline part of an object
   and store those comments into the parse tree being built. It returns the
   attribute passed in with the comments stripped, so it can be stored into
   the appropriated place afterwards.

 "_build_parse_tree()"
   This method consumes the tokens produced by "_tokenize()" and builds a
   data structure containing all the information needed to re-build the
   RPSL object back.

   It returns a reference to the parser object itself, making easy to chain
   method calls again.

 "_parse_tree()"
   This method assembles all the information gathered during the RPSL
   source code tokenization and parsing into a hash reference containing
   the following keys:

 data
   Holds a hash reference whose keys are the RPSL attributes found, and the
   values are the string passed in as values to the respective attributes
   in the RPSL text. Multi-valued attributes are represented by array
   references. As this parser doesn't enforces all the RPSL business rules,
   you must take care when fiddling with this structure, as any value could
   be an array reference.

 order
   Holds an array reference containing the key names from the data hash, in
   the order they where found in the RPSL text. This is stored here because
   the RFC 2622 commands that the order of the attributes in a RPSL object
   is important.

 type
   Holds a string containing the name of the first RPSL attribute found in
   the RPSL text. RFC 2622 commands that the first attribute must be the
   type of the object declared. Knowing the type of object can allow proper
   manipulation of the different RPSL object types by other RPSL namespace
   modules.

 key
   Holds the value contained by the first attribute of an RPSL object. This
   is sometimes the "primary key" of a RPSL object, but not always.

 comment
   Comment is a hash structure where the keys are index positions in the
   order array, and values are the inline comments extracted during the
   parsing stage. Preserving inline comments is not a requirement from RFC
   2622, just a nice thing to have.

 omit_key
   RFC 2622 allows some attribute names to contain multiple values. For
   every new value, a new line must be inserted into the RPSL object. For
   brevity, and to allow humans to read and write RPSL, the RFC 2622 allows
   the attribute name to be omited and replaced by whitespace. It also
   dictates that lines begining with a "+" sign must be considered as being
   part of a multi-line RPSL attribute.

   This array reference stores integers representing index positions in the
   order array signaling attribute positions that must be omited when
   generating RPSL text back from this parse tree. As RFC 2622 doesn't
   request that attributes omited by starting a line with whitespace or "+"
   must preserve this characteristic, this is only a nice-to-have feature.
   =back

EXAMPLES
 Example #1: retrieving information from the Whois Database
   Suppose you retrieve a RPSL Person object from the RIPE NCC WHOIS
   Database, like the one below. It's a simple query and I will not explain
   how you could do it here, because it's a bit out of scope for this
   module. Anyway, you have the following text as a result:

       person:       I. M. A. Fool
       address:      F.A.K.E Corporation
       address:      226 Nowhere st
       address:      10DD10 Nevercity
                     Neverland
       phone:        +99-99-999-9999
       fax-no:       +99-99-999-9999
       e-mail:       [email protected]
       nic-hdl:      XXX007-RIPE # Look, ma, I'm 007! ;)
       mnt-by:       NICE-GUY-MNT
       changed:      [email protected] 20001016
       source:       RIPE

   Let's assume you need to send an email (for example, to report routing
   problems) to Mr Fool. It means that you need to retrieve the *e-mail*
   field value from this RPSL object.

   Let's assume you have the previous text in the $text variable. In order
   to parse the contents of the text into a nice Perl data structure, all
   you need to do is instanciate a parser, with

       use RPSL::Parser;
       my $parser = new RPSL::Parser;

   And then pass it the contents of the $text variable, and collect the
   resulting data structure back:

       my $data_structure = $parser->parse( $text );

   It will give you something that will look more or less like this (dumped
   by Data::Dumper):

       $data_strucutre = {
           __META => {
               'omit_key' => [4],
               'comment'  => { 8 => q{Look, ma, I'm 007! ;)} },
               'order'    => [
                   'person',  'address', 'address', 'address',
                   'address', 'phone',   'fax-no',  'e-mail',
                   'nic-hdl', 'mnt-by',  'changed', 'source'
               ],
               'type' => 'person',
               'data' => {
                   'source'  => 'RIPE',
                   'mnt-by'  => 'NICE-GUY-MNT',
                   'phone'   => '+99-99-999-9999',
                   'nic-hdl' => 'XXX007-RIPE',
                   'fax-no'  => '+99-99-999-9999',
                   'e-mail'  => '[email protected]',
                   'changed' => '[email protected] 20001016',
                   'person'  => 'I. M. A. Fool',
                   'address' => [
                       'F.A.K.E Corporation',
                       '226 Nowhere st',
                       '10DD10 Nevercity',
                       'Neverland'
                   ]
               },
               'key' => 'I. M. A. Fool'
           },
       };

   In a near future, there will be other objects that will know how to
   interpret this as the specific RPSL object declared, and to write the
   corresponding RPSL representation of a given data structure, simmilar to
   this one.

SEE ALSO
   RFC2622 <http://www.ietf.org/rfc/rfc2622.txt>, for the full RPSL
   specification.

AUTHOR
   Luis Motta Campos, <[email protected]>

COPYRIGHT AND LICENSE
   Copyright (C) 2008 by Luis Motta Campos

   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.8 or, at
   your option, any later version of Perl 5 you may have available.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.