NAME

XDR::Parse - Creation of an AST of an XDR specification (RFC4506)

SYNOPSIS

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

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

VERSION

0.3.1

DESCRIPTION

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

This module extends the supported integer types with char, short and long, all of which seem to be supported by rpcgen, the tool consuming XDR to generate remote applications.

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;     # hexadecimal
  const my_other_const = 123; # decimal
  const my_third_const = 012; # octal

• 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.

• definition

  The node making up the definition of the type, holding a type node with two keys, spec and declaration. The value of the spec key is one of enum, struct or union. The elements are specified by the content of the declaration key.

'typedef' declarations

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

'enum' declarations

The declaration node of enum definitions 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

Th declaration node of struct definitions has a single key (members): an array of nodes with name and declaration keys describing the members of the struct type. For more details on the type node, see below.

'union' declarations

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

'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 members 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