NAME

       gasp - a preprocessor for assembly programs

SYNOPSIS

       gasp   [-a|--alternate] [-c CHAR | --commentchar CHAR] [-d|--debug] [-h|--help] [-M|--mri] [-o OUTFILE |
              --output OUTFILE] [-p|--print] [-s|--copysource] [-u|--unreasonable] [-v|--version] INFILE ...

DESCRIPTION

       The primary purpose of the GNU assembler is to assemble the output of other programs--notably  compilers.
       When  you  have  to  hand-code  specialized  routines  in  assembly,  that  means the GNU assembler is an
       unfriendly processor: it has no directives for macros, conditionals, or many other conveniences that  you
       might expect.

       In  some cases you can simply use the C preprocessor, or a generalized preprocessor like M4; but this can
       be awkward, since none of these things are designed with assembly in mind.

       gasp fills this need.  It is expressly designed to  provide  the  facilities  you  need  with  hand-coded
       assembly  code.  Implementing it as a preprocessor, rather than part of the assembler, allows the maximum
       flexibility: you can use it with hand-coded assembly, without paying a penalty of added complexity in the
       assembler you use for compiler output.

       INFILE...  are the files to be preprocessed.

OPTIONS

       The  simplest way to use GASP is to run it as a filter and assemble its output.  In Unix and its ilk, you
       can do this, for example:

            $ gasp prog.asm | as -o prog.o

       Naturally, there are also a few command-line options to allow you to request  variations  on  this  basic
       theme.  Here is the full set of possibilities for the GASP command line.

       -a

       --alternate
              Use  alternative  macro  syntax.  *Note Alternate macro syntax: Alternate, for a discussion of how
              this syntax differs from the default GASP syntax.

       -c CHAR

       --commentchar CHAR
              Use CHAR as the comment character.  The default comment character is `!'.  For example, to  use  a
              semicolon  as  the  comment character, specify `-c ';'' on the GASP command line.  Since assembler
              command characters often have special significance to command shells, it is a good idea  to  quote
              or escape CHAR when you specify a comment character.

              For the sake of simplicity, all examples in this manual use the default comment character `!'.

       -d

       --debug
              Show  debugging  statistics.   In  this version of GASP, this option produces statistics about the
              string buffers that GASP allocates internally.  For each defined  buffersize  S,  GASP  shows  the
              number of strings N that it allocated, with a line like this:

                   strings size S : N

              GASP displays these statistics on the standard error stream, when done preprocessing.

       -h

       --help Display a summary of the GASP command line options.

       -M

       --mri  Use  MRI  compatibility  mode.   Using this option causes GASP to accept the syntax and pseudo-ops
              used by the Microtec Research `ASM68K' assembler.

       -o OUTFILE

       --output OUTFILE
              `-o OUTFILE' `--output OUTFILE' Write the output in a file called OUTFILE.  If you do not use  the
              `-o' option, GASP writes its output on the standard output stream.

       -p

       --print
              Print  line  numbers.  GASP obeys this option _only_ if you also specify `-s' to copy source lines
              to its output.  With  `-s  -p',  GASP  displays  the  line  number  of  each  source  line  copied
              (immediately after the comment character at the beginning of the line).

       -s

       --copysource
              Copy  the source lines to the output file.  Use this option to see the effect of each preprocessor
              line on the GASP output.  GASP places a comment character (`!' by default)  at  the  beginning  of
              each source line it copies, so that you can use this option and still assemble the result.

       -u

       --unreasonable
              Bypass  "unreasonable  expansion"  limit.   Since  you  can  define GASP macros inside other macro
              definitions, the preprocessor normally includes a sanity check.  If  your  program  requires  more
              than  1,000 nested expansions, GASP normally exits with an error message.  Use this option to turn
              off this check, allowing unlimited nested expansions.

       -v

       --version
              Display the GASP version number.

       INFILE ...
              The input file names.  You must specify at least  one  input  file;  if  you  specify  more,  GASP
              preprocesses them all, concatenating the output in the order you list the INFILE arguments.

              Mark the end of each input file with the preprocessor command `.END'.

SEE ALSO

       `gasp' entry in info; The GNU Binary Utilities, Roland H. Pesch (October 1991); gasp(1).