EPICS::Readfile

# NAME

EPICS::Readfile - DBD and DB-file input for EPICS tools

# SYNOPSIS

      use lib '/path/to/base/lib/perl';
      use EPICS::macLib;
      use EPICS::Readfile;

      my $macros = EPICS::macLib->new('a=1', 'b=2');
      my @path = qw(../dbd /opt/epics/base/dbd);
      my $contents = Readfile('input.dbd', $macros, \@path);
      printf "Read in %d files", scalar @inputfiles;

# DESCRIPTION

This module provides a function for reading DBD and DB files that is commonly needed by EPICS tools.

# FUNCTIONS

`Readfile($file, $macros, \@path)`

  This function reads an EPICS DBD or DB file into a string, substitutes any macros present, then parses the contents for any `include`, `addpath` and `path` commands found therein and recursively executes those commands. The return value from the function is a string comprising the fully expanded contents of those files. Before executing them any commands will be replaced with specially formatted comments that allow the original command to be recovered during later parsing.

  Readfile takes as arguments the input filename, an optional handle to a set of macro values from EPICS::macLib, and a reference to an array containing the current search path.

  If macro expansion is not required, the second argument may be any boolean False value such as `0` or `()`. See EPICS::macLib for more details about this argument.

  The path argument is a reference to an array of directory paths to be searched, in order. These paths may be used to locate the original input file and any include files that it references. The path array will be modified by any `addpath` or `path` commands found while parsing the input files.

  While processing input filenames (either the original argument or an include filename) if the filename does not contain any forward-slash `/` characters the path will be searched and the first file matching that name will be used. If the filename contains one or more forward-slash characters it must be either an absolute path or one that is relative to the current working directory; the search path is not used in this case.

# VARIABLES

`@inputfiles`

  As new files are processed their names are added to this array which may be examimed after the Readfile function returns, for example to calculate the complete set of dependencies for the input file.

# COPYRIGHT AND LICENSE

Copyright (C) 2015 UChicago Argonne LLC, as Operator of Argonne National Laboratory.

This software is distributed under the terms of the EPICS Open License.