NAME

XDR::Parse - Creation of an AST of an XDR specification

SYNOPSIS

  use XDR::Parse;
  use Data::Dumper;

  my $p = XDR::Parse->new;
  print Dumper( $p->parse( \*STDIN ) );

VERSION

0.1.3

DESCRIPTION

This module contains a parser for the XDR (eXternal Data Representation) language. The result is an abstract syntax tree (AST) which can be used for further processing.

AST

At the top level, the AST is an array of nodes which can be one of the following, distinguished by the def key in the node's hash:

• a 'pass through' instruction (passthrough)

  This type of nodes contains a line which starts with '%'; the instruction to rpcgen to copy that line to output verbatim

• a preprocessor instruction (preprocessor)

  This type of nodes contains a line which starts with '#'; rpcgen typically invokes cpp to preprocess its input -- this module simply takes input and parses that; input which hasn't been preprocessed may contain this type of node

• constant declarations (const)

• type declarations

  Type definitions come in four subtypes enum, subst, typedef and union

• trailing comment

  Comments in the input are linked to the first syntax node following the comment; files having comments between the last syntax and the end of the file, will contain a special trailing comment node, which doesn't model syntax, but is required to prevent loosing the last comments in the file.

Each node in the tree -not just the toplevel - is a hash which may have any or all of the following keys:

• comments

  Is an array containing all comments following the previous syntax node and preceeding the one to which the comment(s) are attached

• location

  Is an array of two elements: the line and column number of the beginning of the syntax captured by that node

• trailing_comments

  Trailing comments happen when a node encloses a scope with a termination which itself is not included in the AST representation. E.g. the closing ';' in a typedef:

     typedef string our_string<> /* trailing comment */ ;

Constant declarations

Constant declarations exist in two types, distinguished by the type key in the node's hash:

• numeric

    const my_const = 0x123;
    const my_other_const = 123;

• symbolic

    const the_const = my_other_const;

Type declarations

Top level nodes with a def key valued typedef, enum, struct or union define types of the named language construct. These nodes share the following keys, in addition to the keys shared by all nodes:

• name

  Name of the type being defined.

• declaration

  The nodes making up the definition of the type. The content of the declaration is detailed in the sections below.

'typedef' declarations

This node is a 'declaration' node as documented in the section 'declaration' nodes below.

'enum' declarations

This node has a single key elements: an array of nodes with name and value keys, one for each value defined in the enum type.

'struct' declarations

This node has a single key fields: an array of nodes with name and type keys describing the fields of the struct type. For more details on the type node, see below.

'union' declarations

This node has a single key switch: itself a node which contains a handlers and a descriminator key. The descriminator node has a name and a type key; the handlers node contains one or two keys: cases and optionally default. cases is an array of nodes defining the fields of the union; each element consists of three keys: value, name and <declaration>. value is the value associated with the descriminator, to indicate the current definition. name is the name of the field. declaration contains the type declaration for the field.

'declaration' nodes

These nodes contain a type key specifying the basic type of the declaration as documented below under "'type' nodes in declarations", with a number of modifiers:

• pointer

  Optional. Mutually exclusive with the array indicator.

• array

  Optional. Mutually exclusive with the pointer indicator.

  When the array boolean is true, the following additional keys may exist:

  • variable

    Indicates whether the array is of variable length.

  • max

    Indicates the maximum number of items in the array. May be undef, if no maximum was specified.

    Note: this value may be specified using symbolic constant.

  • count

    Indicates the exact number of items in the array, when variable is false or absent.

    Note: this value may be specified using symbolic constant.

'type' nodes in declarations

These nodes either define an inline enum, struct or union, or refer to any of the types defined in the standard or at the toplevel, as indiceted by the spec key using these values:

• primitive

  The value in the name key refers to a built-in type. When the named type is one of the integer type (char, short, int, long or hyper), the type hash contains the additional key unsigned.

  The primitive types string and opaque support the same additional keys as arrays (count, max and variable). These apply to the data within them and do not mean to define arrays of strings/"opaques".

• named

  The value in the name key refers to a defined type.

• enum

  Defines an inline enum through the type's declaration key.

• struct

  Defines an inline struct through the type's declaration key.

• union

  Defines an inline union through the type's declaration key.

The node in the declaration key of the inline enum, struct and union fields follow the same pattern as documented in the respective sections on declarations above.

METHODS

new

  my $parser = XDR::Parse->new;

parse

  my $ast = $parser->parse( \*STDIN );

YYParse (inherited)

LICENSE

This distribution may be used under the same terms as Perl itself.

AUTHOR

• Erik Huelsmann

SEE ALSO

XDR, perlrpcgen

cpanm XDR::Parse

perl -MCPAN -e shell
install XDR::Parse