NAME

parse_subst - a Perl module to parse epics substitution-files

SYNOPSIS

use parse_subst;
undef $/;

my $st= <>;

my $r_templates= parse_subst::parse($st);
parse_subst::dump($r_templates);

DESCRIPTION

Preface

This module contains a parser function for epics substitution-files. The contents of the db-file are returned in a perl hash-structure that can then be used for further evaluation.

Implemented Functions:

parse()
```
my $r_templates= parse_subst::parse($st,$mode,$filename); 
  or
my $r_templates= parse_subst::parse(\$st,$mode,$filename); 
```
This function parses a given scalar variable that must contain a complete substitution-file. It returns a reference to a hash, where the parsed datais stored. The parameter may either be a scalar variable containing the data or a reference to a scalar variable.

The new "global" statement in substitution files is also supported. Globals are resolved, meaning that definitions of global values are merged in the local per-file definitions. Applications that use parse_subst.pm do not have to be aware of the global statement.

The parameter $mode is optional, it may be 'templateHash' or 'templateList'. 'templateHash' is the default.

The parameter $filename is also optional, it is only used for error messages, if you want to parse a file with a given name, use parse_file instead.
parse_file()
```
my $r_templates= parse_subst::parse_file($filename,$mode);
```
This function parses the contents of the given filename. If the parameter $filename is not given it tries to read form STDIN. If the file cannot be opened, it dies with an appropriate error message. It returns a reference to a hash, where the parsed data is stored.

The parameter $mode is optional, it may be 'templateHash' or 'templateList'. 'templateHash' is the default.

dump()

my $r_templates= parse_subst::parse($st);
parse_subst::dump($r_templates);

This function prints a dump of the created structure to the screen.

create()
```
my $r_templates= parse_subst::parse($st);
parse_db::create($r_templates)
```
Print the contents of the substitution data sorted and in the standard substitution format to the screen.

data structures

In all the examples below, this is the substitution data parsed:

file adimogbl.template
  {
    {
      GBASE="U3IV:",
      TRIG1="U3IV:AdiMoVGblTrg.PROC",
    }
  }
file adimovhgbl.template
  {
    {
      GBASE="U3IV:",
      DRV="V",
      AdiMopVer="9",
      TRIG1="U3IV:AdiVGblPvr.PROC",
    }
    {
      GBASE="U3IV:",
      DRV="H",
      AdiMopVer="9",
      TRIG1="U3IV:AdiHGblPvr.PROC",
    }
  }

hash-structure

When the <mode> parameter of the parse function is not defined or set to 'templateHash', the parse function returns a hash structure.

Each template-name is a key in the template-hash. It is a reference to an array that contains the data for that template.

The array contains a reference to a hash for each instantiation of that template.

Each instantiation hash contains a key for each field name that gives the value of that field. Note that undefined fields-values are empty strings (""), not the perl undef-value.

Example of a hash that parse() returns:

$r_h= { 
        'adimovhgbl.template' => [
                                   {
                                     'TRIG1' => 'U3IV:AdiVGblPvr.PROC',
                                     'DRV' => 'V',
                                     'GBASE' => 'U3IV:',
                                     'AdiMopVer' => '9'
                                   },
                                   {
                                     'TRIG1' => 'U3IV:AdiHGblPvr.PROC',
                                     'DRV' => 'H',
                                     'GBASE' => 'U3IV:',
                                     'AdiMopVer' => '9'
                                   }
                                 ],
        'adimogbl.template' => [
                                 {
                                   'TRIG1' => 'U3IV:AdiMoVGblTrg.PROC',
                                   'GBASE' => 'U3IV:'
                                 }
                               ]
      };

list-structure

When the <mode> parameter of the parse function is set to 'templateList', the parse function returns a list containing the data.

Here is an example:

$r_h= [ 
        [
          'adimogbl.template',
          {
            'TRIG1' => 'U3IV:AdiMoVGblTrg.PROC',
            'GBASE' => 'U3IV:'
          }
        ],
        [
          'adimovhgbl.template',
          {
            'TRIG1' => 'U3IV:AdiVGblPvr.PROC',
            'DRV' => 'V',
            'GBASE' => 'U3IV:',
            'AdiMopVer' => '9'
          },
          {
            'TRIG1' => 'U3IV:AdiHGblPvr.PROC',
            'DRV' => 'H',
            'GBASE' => 'U3IV:',
            'AdiMopVer' => '9'
          }
        ]
      ];

old deprecated data structure

Version 1.0 of the parser used a hash instead of the array as explained above, with keys from "0" to .. "n". If you want a template-hash structure that is still compatible to this, set $old_parser to 1 like this:

$parse_subst::old_parser=1;

This format should no longer be used, however here is an example of the generated output:

$r_h= { 
        'adimovhgbl.template' => {
                                   '1' => {
                                            'TRIG1' => 'U3IV:AdiHGblPvr.PROC',
                                            'DRV' => 'H',
                                            'GBASE' => 'U3IV:',
                                            'AdiMopVer' => '9'
                                          },
                                   '0' => {
                                            'TRIG1' => 'U3IV:AdiVGblPvr.PROC',
                                            'DRV' => 'V',
                                            'GBASE' => 'U3IV:',
                                            'AdiMopVer' => '9'
                                          }
                                 },
        'adimogbl.template' => {
                                 '0' => {
                                          'TRIG1' => 'U3IV:AdiMoVGblTrg.PROC',
                                          'GBASE' => 'U3IV:'
                                        }
                               }
      };

AUTHOR

Goetz Pfeiffer, Goetz.Pfeiffer@helmholtz-berlin.de