@title GASP, an assembly preprocessor
@subtitle for GASP version 1
@sp 1
-@subtitle January 1994
+@subtitle March 1994
@author Roland Pesch
@page
@example
.MACRO saveregs from=8 to=14
count .ASSIGNA \from
- ; save r\from..r\to
+ ! save r\from..r\to
.AWHILE \&count LE \to
mov r\&count,@@-sp
count .ASSIGNA \&count + 1
@cartouche
@example
- ; save r12..r14
+ ! save r12..r14
mov r12,@@-sp
mov r13,@@-sp
mov r14,@@-sp
possibilities for the @sc{gasp} command line.
@example
-gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ]
+gasp [ -a | --alternate ]
+ [ -c @var{char} | --commentchar @var{char} ]
+ [ -d | --debug ] [ -h | --help ]
+ [ -o @var{outfile} | --output @var{outfile} ]
+ [ -p | --print ] [ -s | --copysource ]
+ [ -u | --unreasonable ] [ -v | --version ]
@var{infile} @dots{}
@end example
-@c FIXME!! Aren't all GNU programs supposed to have a -V or --version
-@c option, that reports version info and exits?
-
@ftable @code
@item @var{infile} @dots{}
@c FIXME! Why not stdin as default infile?
Mark the end of each input file with the preprocessor command
@code{.END}. @xref{Other Commands,, Miscellaneous commands}.
-@item -c
-@c FIXME! Shouldn't there be an option to set the prefix char so it can
-@c always be the comment char for whatever assembly version we have?
-Copy the source lines to the output file. Use this option
-to see the effect of each preprocessor line on the @sc{gasp} output.
-@sc{gasp} marks the lines copied from the source file with @samp{!} at
-the beginning, to help you distinguish them from the rest of the output.
+@item -a
+@itemx --alternate
+Use alternative macro syntax. @xref{Alternate,, Alternate macro
+syntax}, for a discussion of how this syntax differs from the default
+@sc{gasp} syntax.
+
+@cindex comment character, changing
+@cindex semicolon, as comment
+@cindex exclamation mark, as comment
+@cindex shriek, as comment
+@cindex bang, as comment
+@cindex @code{!} default comment char
+@cindex @code{;} as comment char
+@item -c '@var{char}'
+@itemx --commentchar '@var{char}'
+Use @var{char} as the comment character. The default comment character
+is @samp{!}. For example, to use a semicolon as the comment character,
+specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since
+assembler command characters often have special significance to command
+shells, it is a good idea to quote or escape @var{char} when you specify
+a comment character.
+
+For the sake of simplicity, all examples in this manual use the default
+comment character @samp{!}.
+
+@item -d
+@itemx --debug
+Show debugging statistics. In this version of @sc{gasp}, this option
+produces statistics about the string buffers that @sc{gasp} allocates
+internally. For each defined buffersize @var{s}, @sc{gasp} shows the
+number of strings @var{n} that it allocated, with a line like this:
+
+@example
+strings size @var{s} : @var{n}
+@end example
+
+@noindent
+@sc{gasp} displays these statistics on the standard error stream, when
+done preprocessing.
+
+@item -h
+@itemx --help
+Display a summary of the @sc{gasp} command line options.
@item -o @var{outfile}
+@itemx --output @var{outfile}
Write the output in a file called @var{outfile}. If you do not use the
@samp{-o} option, @sc{gasp} writes its output on the standard output
stream.
@item -p
+@itemx --print
Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
-specify @samp{-c} to copy source lines to its output. With @samp{-c
+specify @samp{-s} to copy source lines to its output. With @samp{-s
-p}, @sc{gasp} displays the line number of each source line copied
-(immediately after the @samp{!} that marks source lines in the output).
+(immediately after the comment character at the beginning of the line).
@item -s
-Show statistics. In this version of @sc{gasp}, this option produces
-statistics about the string buffers that @sc{gasp} allocates internally.
-For each defined buffersize @var{s}, @sc{gasp} shows the number of
-strings @var{n} that it allocated, with a line like this:
-
-@example
-strings size @var{s} : @var{n}
-@end example
-
-@noindent
-@sc{gasp} displays these statistics on the standard error stream, when
-done preprocessing.
+@itemx --copysource
+Copy the source lines to the output file. Use this option
+to see the effect of each preprocessor line on the @sc{gasp} output.
+@sc{gasp} places a comment character (@samp{!} by default) at
+the beginning of each source line it copies, so that you can use this
+option and still assemble the result.
@item -u
+@itemx --unreasonable
Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
macros inside other macro definitions, the preprocessor normally
includes a sanity check. If your program requires more than 1,000
nested expansions, @sc{gasp} normally exits with an error message. Use
this option to turn off this check, allowing unlimited nested
expansions.
+
+@item -v
+@itemx --version
+Display the @sc{gasp} version number.
@end ftable
@node Commands
* Listings::
* Other Commands::
* Syntax Details::
+* Alternate::
@end menu
@node Conditionals
@cartouche
@example
.MACRO SUM FROM=0, TO=9
- ; \FROM \TO
+ ! \FROM \TO
mov r\FROM,r10
COUNT .ASSIGNA \FROM+1
.AWHILE \&COUNT LE \TO
@cartouche
@example
- ; 0 5
+ ! 0 5
mov r0,r10
add r1,r10
add r2,r10
An alternative form of introducing a macro definition: specify the macro
name in the label position, and the arguments (if any) between
parentheses after the name. Defaulting rules and usage work the same
-way as for the alternate macro definition syntax.
+way as for the other macro definition syntax.
@item .ENDM
Mark the end of a macro definition.
@sc{gasp} maintains a counter of how many macros it has
executed in this pseudo-variable; you can copy that number to your
output with @samp{\@@}, but @emph{only within a macro definition}.
+
+@item LOCAL @var{name} [ , @dots{} ]
+@emph{Warning: @code{LOCAL} is only available if you select ``alternate
+macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
+Alternate macro syntax}.
+
+Generate a string replacement for each of the @var{name} arguments, and
+replace any instances of @var{name} in each macro expansion. The
+replacement string is unique in the assembly, and different for each
+separate macro expansion. @code{LOCAL} allows you to write macros that
+define symbols, without fear of conflict between separate macro expansions.
@end ftable
@node Data
@section Miscellaneous commands
@ftable @code
+@item .ALTERNATE
+Use the alternate macro syntax henceforth in the assembly.
+@xref{Alternate,, Alternate macro syntax}.
+
@item .ORG
@c FIXME! This is very strange, since _GAS_ understands .org
This command is recognized, but not yet implemented. @sc{gasp}
@cindex comments
The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
-A comment begins with the first unquoted @samp{;} or @samp{\;}, and
-extends to the end of a line. The two kinds of comment markers lead to
-slightly different treatment:
+A comment begins with the first unquoted comment character (@samp{!} by
+default), or an escaped or doubled comment character (@samp{\!} or
+@samp{!!} by default), and extends to the end of a line. You can
+specify what comment character to use with the @samp{-c} option
+(@pxref{Invoking GASP,, Command Line Options}). The two kinds of
+comment markers lead to slightly different treatment:
@table @code
-@item ;
-Generate an assembly comment in the @sc{gasp} output. @sc{gasp} evaluates any
-preprocessor variables (macro arguments, or variables defined with
-@code{.ASSIGNA} or @code{.ASSIGNC}) present. For example, a macro that
-begins like this
+@item !
+A single, un-escaped comment character generates an assembly comment in
+the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables
+(macro arguments, or variables defined with @code{.ASSIGNA} or
+@code{.ASSIGNC}) present. For example, a macro that begins like this
@example
.MACRO SUM FROM=0, TO=9
- ; \FROM \TO
+ ! \FROM \TO
@end example
@noindent
issues as the first line of output a comment that records the
values you used to call the macro.
-@item \;
-This marks a @sc{gasp} source comment. @sc{gasp} does not copy such
-comments to the assembly output.
+@c comments, preprocessor-only
+@c preprocessor-only comments
+@c GASP-only comments
+@item \!
+@itemx !!
+Either an escaped comment character, or a double comment character,
+marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments
+to the assembly output.
@end table
@cindex continuation character
Occasionally you may want to prevent @sc{gasp} from preprocessing some
particular bit of text. To @emph{copy literally} from the @sc{gasp}
source to its output, place @samp{\(} before the string to copy, and
-@samp{)} at the end. For example, write @samp{\(\;)} if you need the
-characters @samp{\;} in your assembly output.
+@samp{)} at the end. For example, write @samp{\(\!)} if you need the
+characters @samp{\!} in your assembly output.
@cindex symbol separator
@cindex text, separating from symbols
numeric byte value as an absolute expression between angle brackets
(@code{<@var{expr}>}. Directives that output strings allow you to
specify any number of either kind of value, in whatever order is
-convenient, and concatenate the result.
+convenient, and concatenate the result. (Alternate syntax mode
+introduces a number of alternative string notations; @pxref{Alternate,,
+Alternate macro syntax}.)
@c Details of numeric notation, e.g. base prefixes
You can write @dfn{numeric constants} either in a specific base, or in
extending for @var{len} bytes.
@end ftable
+@node Alternate
+@section Alternate macro syntax
+
+If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command
+line, the preprocessor uses somewhat different syntax. This syntax is
+reminiscent of the syntax of Phar Lap macro assembler, but it
+is @emph{not} meant to be a full emulation of Phar Lap or similar
+assemblers. In particular, @sc{gasp} does not support directives such
+as @code{DB} and @code{IRP}, even in alternate syntax mode.
+
+In particular, @samp{-a} (or @samp{--alternate}) elicits these
+differences:
+
+@table @emph
+@item Preprocessor directives
+You can use @sc{gasp} preprocessor directives without a leading @samp{.}
+dot. For example, you can write @samp{SDATA} with the same effect as
+@samp{.SDATA}.
+
+@item LOCAL
+One additional directive, @code{LOCAL}, is available. @xref{Macros,,
+Defining your own directives}, for an explanation of how to use
+@code{LOCAL}.
+
+@item String delimiters
+You can write strings delimited in two other ways besides
+@code{"@var{string}"}:
+
+@table @code
+@item '@var{string}'
+You can delimit strings with single-quote charaters.
+
+@item <@var{string}>
+You can delimit strings with matching angle brackets.
+
+@item single-character string escape
+To include any single character literally in a string (even if the
+character would otherwise have some special meaning), you can prefix the
+character with @samp{!} (an exclamation mark). For example, you can
+write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}.
+@end table
+
+@item Expression results as strings
+You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
+and use the result as a string.
+@end table
+
@node Index
@unnumbered Index
projects / binutils-gdb.git / commitdiff