NAME

Asm::Preproc - Preprocessor to be called from an assembler

SYNOPSIS

  use Asm::Preproc;
  my $pp = Asm::Preproc->new();
  my $pp = Asm::Preproc->new(@files);
  
  $pp->add_path(@path); @path = $pp->path;
  $pp->include($file); $pp->include($file, $from_line);
  my $full_path = $pp->path_search($file);

  $pp->include_list(@input);
  
  my $iter = sub {return scalar <STDIN>};
  $pp->include_list($iter);

  my $line = $pp->getline;     # isa Asm::Preproc::Line
  my $strm = $pp->line_stream; # isa Iterator::Simple::Lookahead

DESCRIPTION

This module implements a preprocessor that reads source files and handles recursive file includes. It is intended to be called from inside an assembler or compiler.

METHODS

new

Creates a new object. If an argument list is given, calls "include" for each of the file starting from the last, so that the files are read in the given order.

path

Returns the list of directories to search in sequence for source files.

add_path

Adds the given directories to the path searched for include files.

path_search

Searches for the given file in the "path" created by "add_path", returns the first full path name where the file can be found.

Returns the input file name if the file is found in the current directory, or if it is not found in any of the "path" directories.

include

Open the input file and sets-up the object to read each line in sequence.

The optional second argument is a Asm::Preproc::Line object pointing at the %include line that included the file, to be used in error messages.

An exception is raised if the input file cannot be read, or if a file is included recursively, to avoid an infinite include loop.

include_list

Sets-up the object to read each element of the passed input list one line at a time.

Each element of the list is either a text string or a code reference of an iterator. The iterator may return text strings, or other iterators that will be called recursively. The iterator returns "undef" at the end of input.

The text strings are split by lines, so that each "getline" calls returns one complete line.

As the text lines are scanned for pre-processor directives, the following two lines are equivalent:

  $pp->include('file.asm');
  $pp->include_list('%include <file.asm>');

getline

Returns the next line from the input, after doing all the pre-processing. The line is returned as a Asm::Preproc::Line object containing the actual text, and the file and line number where the text was found.

Returns "undef" at the end of the input.

line_stream

Returns a Iterator::Simple::Lookahead object that will return the result of "getline" on each "next" call.

PREPROCESSING

The following preprocessor-like lines are processed:

  %line N+M FILE

nasm-like line directive, telling that the next input line is line N from file FILE, followed by lines N+M, N+2*M, ... This information is used to generate error messages. Usefull to parse a file preprocessed by nasm.

  #line N "FILE"

cpp-like line directive, telling that the next input line is line N from file FILE, followed by lines N+1, N+2, ... This information is used to generate error messages. Usefull to parse a file preprocessed by cpp.

  %include 'FILE'
  %include "FILE"
  %include <FILE>
  %include  FILE
  #include 'FILE'
  #include "FILE"
  #include <FILE>
  #include  FILE

nasm/cpp-like include directive, asking to insert the contents of the given file in the input stream.

All the other preprocessor-like lines are ignored, i.e. lines starting with '#' or '%'.

AUTHOR

Paulo Custodio, "<pscust at cpan.org>"

BUGS and FEEDBACK

Please report any bugs or feature requests through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Asm-Preproc>.

ACKNOWLEDGEMENTS

Inspired in the Netwide Assembler, <http://www.nasm.us/>

LICENSE and COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.