NAME

XDR::Gen - Generator for XDR (de)serializers

VERSION

version 0.0.4

SYNOPSIS

  use XDR::Gen;
  use XDR::Parse;

  my $parser = XDR::Parse->new;
  my $definition = <<'DEF';
  typedef string *optional_string;
  DEF

  open my $fh, '<', \$definition;
  my $ast = $parser->parse( $fh );

  # print the generated serializers on STDOUT
  XDR::Gen->serializers( $ast );

  # or print to a specific file handle
  open my $oh, '>', '/dev/null';
  XDR::Gen->serializers( $ast, $oh );

DESCRIPTION

This module contains a generator for Perl code to serialize data following an XDR data definition. Each type defined in the data definition results in a serializer and a deserializer function. For defined constants and the elements of enums, constants are defined.

The generated conversion routines include validation of input coming from encoded input (in case of deserialization) or from the enclosing application (in case of serialization).

Data conversion

Except for data passed to a 'pointer' type (defined using *) or boolean values, all values provided must be defined. In case of boolean values, an undefined value will be interpreted to indicate false. In case of a pointer type, an undefined value will be serialized as "not provided", the same way a C NULL pointer would have.

FUNCTIONS

generate

  XDR::Gen->generate( $ast, $output, [ %options ] )

Generates the code for $ast, sending it to $output. The %options determine the exact outputs being generated.

$output can be one of:

• A blessed reference supporting print

  When a blessed reference is passed on which the function print can be called, e.g. an IO::Handle instance, or a custom object with a print method.

• A code reference

  When a code reference is passed in $output, it is called as

    $coderef->( $node, $definition, type => $type );

  with $node the AST node for which the definition is generated, $definition the source code fragment and $type the type of source code having been generated. $type can have these values:

  • preamble

    Code fragment to preceed the generated code. Defaults to

        use v5.14;
        use warnings FATAL => 'uninitialized';
        use Config;
        use Carp qw(croak);

    If it's the intent to use the generated code as a stand-alone module, at the absolute minimum, a package statement needs to be prepended to the preamble.

  • postamble

    Code fragment to follow the generated code. Default to an empty string. If it's the intent to use the generated code as a stand-alone module, at the absolute minimum, a 1; statement should be appended to this postamble.

  • constant

    A constant generated from a const line in the input.

  • enum

    A value from an enum definition; note that this definition may be part of a nested enum specification inside a struct or union definition.

  • serializer

    Code generated to serialize a type specified in the XDR syntax.

  • deserializer

    Code generated to deserialize a type specified in the XDR syntax.

  Note that the $node does not need to be a top-level AST node, especially with enum types, which can be defined 'inline' as part of union or struct

• A scalar reference

  When a scalar reference is passed, the code fragments are appended to the contents of the referenced variable.

• undef

  When $output is undefined, the output is sent to STDOUT by default.

Supported values for options:

• transform

  A function to transform identifiers; e.g.,

     sub { $_[0] =~ s/^PREFIX_//ir }

  would strip PREFIX_ from PREFIX_IDENTI_FIER, using IDENTI_FIER in the generated code instead.

• exclude_constants

  Prevent emitting code for constant definitions.

• exclude_enums

  Prevent emitting code for enum elements.

• exclude_deserializers

  Prevent emitting code for deserializer routines.

• exclude_serializers

  Prevent emitting code for serializer routines.

• include_passthrough

  Emit passthrough instructions (as-is).

• include_preprocessor

  Emit preprocessor instructions (as-is).

• external_constants

    XDR::Gen->generate( $ast, $fh,
                        external_constants => { VIR_UUID_BUFLEN => 16 } );

  A hashref with constants defined outside of the scope of the xdr input file. rpcgen depends on cpp to resolve preprocessor macros; XDR::Gen does not, but allows values extracted by other means to be provided for use during code generation or in the generated code. External constants are resolved to their numeric value at code generation time by XDR::Gen.

LICENSE

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

AUTHOR

• Erik Huelsmann

SEE ALSO

XDR::Parse, perlrpcgen