1 \input texinfo @c -*- Texinfo -*-
5 @c This file documents the assembly preprocessor "GASP"
7 @c Copyright (c) 1994 Free Software Foundation, Inc.
9 @c This text may be freely distributed under the terms of the GNU
10 @c General Public License.
15 * gasp:(gasp). The GNU Assembler Preprocessor
23 @setchapternewpage odd
27 @title GASP, an assembly preprocessor
28 @c FIXME! Get a version number, global-replace '??'
29 @subtitle for GASP version ??
31 @subtitle January 1994
36 {\parskip=0pt \hfill Cygnus Support\par
40 @vskip 0pt plus 1filll
41 Copyright @copyright{} 1994 Free Software Foundation, Inc.
43 Permission is granted to make and distribute verbatim copies of
44 this manual provided the copyright notice and this permission notice
45 are preserved on all copies.
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided also that
49 the entire resulting derived work is distributed under the terms of a
50 permission notice identical to this one.
52 Permission is granted to copy and distribute translations of this manual
53 into another language, under the above conditions for modified versions.
57 Copyright @copyright{} 1994 Free Software Foundation, Inc.
59 Permission is granted to make and distribute verbatim copies of
60 this manual provided the copyright notice and this permission notice
61 are preserved on all copies.
64 Permission is granted to process this file through TeX and print the
65 results, provided the printed document carries a copying permission
66 notice identical to this one except for the removal of this paragraph
67 (this paragraph not being relevant to the printed manual).
70 Permission is granted to copy and distribute modified versions of this
71 manual under the conditions for verbatim copying, provided also that
72 the entire resulting derived work is distributed under the terms of a
73 permission notice identical to this one.
75 Permission is granted to copy and distribute translations of this manual
76 into another language, under the above conditions for modified versions.
81 GASP is a preprocessor for assembly programs.
83 This file describes version ?? of GASP.
85 Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
88 * Overview:: What is GASP?
89 * Invoking GASP:: Command line options.
90 * Commands:: Preprocessor commands.
96 @chapter What is GASP?
98 The primary purpose of the @sc{gnu} assembler is to assemble the output of
99 other programs---notably compilers. When you have to hand-code
100 specialized routines in assembly, that means the @sc{gnu} assembler is
101 an unfriendly processor: it has no directives for macros, conditionals,
102 or many other conveniences that you might expect.
104 In some cases you can simply use the C preprocessor, or a generalized
105 preprocessor like @sc{m4}; but this can be awkward, since none of these
106 things are designed with assembly in mind.
108 @sc{gasp} fills this need. It is expressly designed to provide the
109 facilities you need with hand-coded assembly code. Implementing it as a
110 preprocessor, rather than part of the assembler, allows the maximum
111 flexibility: you can use it with hand-coded assembly, without paying a
112 penalty of added complexity in the assembler you use for compiler
115 Here is a small example to give the flavor of @sc{gasp}. This input to
120 .MACRO saveregs from=8 to=14
123 .AWHILE \&count LE \to
125 count .ASSIGNA \&count + 1
133 bar: mov #H'dead+12,r0
134 foo .SDATAC "hello"<12>
140 generates this assembly program:
158 bar: mov #57005+10,r0
159 foo: .byte 6,104,101,108,108,111,10
164 @chapter Command Line Options
166 @c FIXME! Or is there a simpler way, calling from GAS option?
167 The simplest way to use @sc{gasp} is to run it as a filter and assemble
168 its output. In Unix and its ilk, you can do this, for example:
170 @c FIXME! GASP filename suffix convention?
172 $ gasp prog.sp | as -o prog.o
175 Naturally, there are also a few command-line options to allow you to
176 request variations on this basic theme. Here is the full set of
177 possibilities for the @sc{gasp} command line.
180 gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ] @var{infile} @dots{}
183 @c FIXME!! Aren't all GNU programs supposed to have a -V or --version
184 @c option, that reports version info and exits?
187 @item @var{infile} @dots{}
188 @c FIXME! Why not stdin as default infile?
189 The input file names. You must specify at least one input file; if you
190 specify more, @sc{gasp} preprocesses them all, concatenating the output
191 in the order you list the @var{infile} arguments.
193 Mark the end of each input file with the preprocessor command
194 @code{.END}. @xref{Other Commands,, Miscellaneous commands}.
197 @c FIXME! Shouldn't there be an option to set the prefix char so it can
198 @c always be the comment char for whatever assembly version we have?
199 Copy the source lines to the output file. Use this option
200 to see the effect of each preprocessor line on the @sc{gasp} output.
201 @sc{gasp} marks the lines copied from the source file with @samp{!} at
202 the beginning, to help you distinguish them from the rest of the output.
204 @item -o @var{outfile}
205 Write the output in a file called @var{outfile}. If you do not use the
206 @samp{-o} option, @sc{gasp} writes its output on the standard output
210 Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
211 specify @samp{-c} to copy source lines to its output. With @samp{-c
212 -p}, @sc{gasp} displays the line number of each source line copied
213 (immediately after the @samp{!} that marks source lines in the output).
216 Show statistics. In this version of @sc{gasp}, this option produces
217 statistics about the string buffers that @sc{gasp} allocates internally.
218 For each defined buffersize @var{s}, @sc{gasp} shows the number of
219 strings @var{n} that it allocated, with a line like this:
222 strings size @var{s} : @var{n}
226 @sc{gasp} displays these statistics on the standard error stream, when
230 Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
231 macros inside other macro definitions, the preprocessor normally
232 includes a sanity check. If your program requires more than 1,000
233 nested expansions, @sc{gasp} normally exits with an error message. Use
234 this option to turn off this check, allowing unlimited nested
239 @chapter Preprocessor Commands
241 @sc{gasp} commands have a straightforward syntax that fits in well with
242 assembly conventions. In general, a command extends for a line, and may
243 have up to three fields: an optional label, the command itself, and
244 optional arguments to the command. You can write commands in upper or
245 lower case, though this manual shows them in upper case. @xref{Syntax
246 Details,, Details of the GASP syntax}, for more information.
260 @section Conditional assembly
262 The conditional-assembly directives allow you to include or exclude
263 portions of an assembly depending on how a pair of expressions, or a
264 pair of strings, compare.
266 The overall structure of conditionals is familiar from many other
267 contexts. @code{.AIF} marks the start of a conditional, and precedes
268 assembly for the case when the condition is true. An optional
269 @code{.AELSE} precedes assembly for the converse case, and an
270 @code{.AENDI} marks the end of the condition.
272 @c FIXME! Why doesn't -u turn off this check?
273 You may nest conditionals up to a depth of 100; @sc{gasp} rejects
274 nesting beyond that, because it may indicate a bug in your macro
277 @c FIXME! Why isn't there something like cpp's -D option? Conditionals
278 @c would be much more useful if there were.
279 Conditionals are primarily useful inside macro definitions, where you
280 often need different effects depending on argument values.
281 @xref{Macros,, Defining your own directives}, for details about defining
285 @item .AIF @var{expra} @var{cmp} @var{exprb}
286 @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}"
288 The governing condition goes on the same line as the @code{.AIF}
289 preprocessor command. You may compare either two strings, or two
292 When you compare strings, only two conditional @var{cmp} comparison
293 operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
294 are identical), and @samp{NE} (the converse).
296 When you compare two expressions, @emph{both expressions must be
297 absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
298 can use these @var{cmp} comparison operators with expressions:
302 Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and
303 @var{strb} identical?)
306 Are @var{expra} and @var{exprb} different? (For strings, are @var{stra}
307 and @var{strb} different?
310 Is @var{expra} less than @var{exprb}? (Not allowed for strings.)
313 Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.)
316 Is @var{expra} greater than @var{exprb}? (Not allowed for strings.)
319 Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for
324 Marks the start of assembly code to be included if the condition fails.
325 Optional, and only allowed within a conditional (between @code{.AIF} and
329 Marks the end of a conditional assembly.
333 @section Repetitive sections of assembly
335 Two preprocessor directives allow you to repeatedly issue copies of the
336 same block of assembly code.
339 @item .AREPEAT @var{aexp}
341 If you simply need to repeat the same block of assembly over and over a
342 fixed number of times, sandwich one instance of the repeated block
343 between these @code{.AREPEAT} and @code{.AENDR}. Specify the number of
344 copies as @var{aexp} (which must be an absolute expression). For
345 example, this repeats two assembly statements three times in succession:
356 @item .AWHILE @var{expra} @var{cmp} @var{exprb}
358 @itemx .AWHILE @var{stra} @var{cmp} @var{strb}
360 To repeat a block of assembly depending on a conditional test, rather
361 than repeating it for a specific number of times, use @code{.AWHILE}.
362 @code{.AENDW} marks the end of the repeated block. The conditional
363 comparison works exactly the same way as for @code{.AIF}, with the same
364 comparison operators (@pxref{Conditionals,, Conditional assembly}).
366 Since the terms of the comparison must be absolute expression,
367 @code{.AWHILE} is primarily useful within macros. @xref{Macros,,
368 Defining your own directives}.
371 @cindex loops, breaking out of
372 @cindex breaking out of loops
373 You can use the @code{.EXITM} preprocessor directive to break out of
374 loops early (as well as to break out of macros). @xref{Macros,,
375 Defining your own directives}.
378 @section Preprocessor variables
380 You can use variables in @sc{gasp} to represent strings, registers, or
381 the results of expressions.
383 You must distinguish two kinds of variables:
384 @c FIXME! Is this crud true about conditional comparisons vs variables?
387 Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this
388 kind of variable in your assembly output, simply mention its name. For
389 example, these two lines define and use a variable @samp{eg}:
399 @emph{Do not use} this kind of variable in conditional expressions or
400 while loops; @sc{gasp} only evaluates these variables when writing
404 Variables for use during preprocessing. These are defined as macro
405 arguments, or with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
406 kind of variable, write @samp{\&} before the variable name; for example,
420 @item @var{pvar} .EQU @var{expr}
421 @c FIXME! Anything to beware of re GAS directive of same name?
422 Assign preprocessor variable @var{pvar} the value of the expression
423 @var{expr}. There are no restrictions on redefinition; use @samp{.EQU}
424 with the same @var{pvar} as often as you find it convenient.
426 @item @var{pvar} .ASSIGN @var{expr}
427 Almost the same as @code{.EQU}, save that you may not redefine
428 @var{pvar} using @code{.ASSIGN} once it has a value.
429 @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works
432 @item @var{pvar} .ASSIGNA @var{aexpr}
433 Define a variable with a numeric value, for use during preprocessing.
434 @var{aexpr} must be an absolute expression. You can redefine variables
435 with @code{.ASSIGNA} at any time.
437 @item @var{pvar} .ASSIGNC "@var{str}"
438 Define a variable with a string value, for use during preprocessing.
439 You can redefine variables with @code{.ASSIGNC} at any time.
441 @item @var{pvar} .REG (@var{register})
442 Use @code{.REG} to define a variable that represents a register. In
443 particular, @var{register} is @emph{not evaluated} as an expression.
444 You may use @code{.REG} at will to redefine register variables.
447 All these directives accept the variable name in the ``label'' position,
448 that is at the left margin. You may specify a colon after the variable
449 name if you wish; the first example above could have started @samp{eg:}
450 with the same effect.
453 @section Defining your own directives
455 The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
456 that generate assembly output, and that you can use with a syntax
457 similar to built-in @sc{gasp} or assembler directives. For example,
458 this definition specifies a macro @code{SUM} that adds together a range of
459 consecutive registers:
463 .MACRO SUM FROM=0, TO=9
466 COUNT .ASSIGNA \FROM+1
467 .AWHILE \&COUNT LE \TO
469 COUNT .ASSIGNA \&COUNT+1
476 With that definition, @samp{SUM 0,5} generates this assembly output:
491 @item .MACRO @var{macname}
492 @itemx .MACRO @var{macname} @var{macargs} @dots{}
493 Begin the definition of a macro called @var{macname}. If your macro
494 definition requires arguments, specify their names after the macro name,
495 separated by commas or spaces. You can supply a default value for any
496 macro argument by following the name with @samp{=@var{deflt}}. For
497 example, these are all valid @code{.MACRO} statements:
501 Begin the definition of a macro called @code{COMM}, which takes no
504 @item .MACRO PLUS1 P, P1
505 @itemx .MACRO PLUS1 P P1
506 Either statement begins the definition of a macro called @code{PLUS1},
507 which takes two arguments; within the macro definition, these arguments
508 are evaluated as @samp{\&P} and @samp{\&P1}.
510 @item .MACRO RESERVE_STR P1=0 P2
511 Begin the definition of a macro called @code{RESERVE_STR}, with two
512 arguments. The first argument has a default value, but not the second.
513 After the definition is complete, you can call the macro either as
514 @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\&P1} evaluating to
515 @var{a} and @samp{\&P2} evaluating to @var{b}), or as @samp{RESERVE_STR
516 ,@var{b}} (with @samp{\&P1} evaluating as the default, in this case
517 @samp{0}, and @samp{\&P2} evaluating to @var{b}).
520 When you call a macro, the values are assigned by position to each
521 argument name. Macro arguments are preprocessor variables in the same
522 way as variables you define with @samp{.ASSIGNA} or @samp{.ASSIGNC}, and
523 you can therefore use them in conditionals or for loop control.
525 @item @var{name} .MACRO
526 @itemx @var{name} .MACRO ( @var{macargs} @dots{} )
527 @c FIXME check: I think no error _and_ no args recognized if I use form
528 @c NAME .MACRO ARG ARG
529 An alternative form of introducing a macro definition: specify the macro
530 name in the label position, and the arguments (if any) between
531 parentheses after the name. Defaulting rules and usage work the same
532 way as for the alternate macro definition syntax.
535 Mark the end of a macro definition.
538 Exit early from the current macro definition, @code{.AREPEAT} loop, or
541 @cindex number of macros executed
542 @cindex macros, count executed
544 @sc{gasp} maintains a counter of how many macros it has
545 executed in this pseudo-variable; you can copy that number to your
546 output with @samp{\@@}, but @emph{only within a macro definition}.
552 In assembly code, you often need to specify working areas of memory;
553 depending on the application, you may want to initialize such memory or
554 not. @sc{gasp} provides preprocessor directives to help you avoid
555 repetitive coding for both purposes.
557 You can use labels as usual to mark the data areas.
565 @subsection Initialized data
567 These are the @sc{gasp} directives for initialized data, and the standard
568 @sc{gnu} assembler directives they expand to:
571 @item .DATA @var{expr}, @var{expr}, @dots{}
572 @itemx .DATA.B @var{expr}, @var{expr}, @dots{}
573 @itemx .DATA.W @var{expr}, @var{expr}, @dots{}
574 @itemx .DATA.L @var{expr}, @var{expr}, @dots{}
575 Evaluate arithmetic expressions @var{expr}, and emit the corresponding
576 @code{as} directive (labelled with @var{lab}). The unqualified
577 @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte};
578 @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits
581 For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}.
583 @item .DATAB @var{repeat}, @var{expr}
584 @itemx .DATAB.B @var{repeat}, @var{expr}
585 @itemx .DATAB.W @var{repeat}, @var{expr}
586 @itemx .DATAB.L @var{repeat}, @var{expr}
587 @c FIXME! Looks like gasp accepts and ignores args after 2nd.
588 Make @code{as} emit @var{repeat} copies of the value of the expression
589 @var{expr} (using the @code{as} directive @code{.fill}).
590 @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats
591 two-byte values; and @samp{.DATAB.L} repeats four-byte values.
592 @samp{.DATAB} without a suffix repeats four-byte values, just like
595 @c FIXME! Allowing zero might be useful for edge conditions in macros.
596 @var{repeat} must be an absolute expression with a positive value.
598 @item .SDATA "@var{str}" @dots{}
599 String data. Emits a concatenation of bytes, precisely as you specify
600 them (in particular, @emph{nothing is added to mark the end} of the
601 string). @xref{Constants,, String and numeric constants}, for details
602 about how to write strings. @code{.SDATA} concatenates multiple
603 arguments, making it easy to switch between string representations. You
604 can use commas to separate the individual arguments for clarity, if you
607 @item .SDATAB @var{repeat}, "@var{str}" @dots{}
608 Repeated string data. The first argument specifies how many copies of
609 the string to emit; the remaining arguments specify the string, in the
610 same way as the arguments to @code{.SDATA}.
612 @item .SDATAZ "@var{str}" @dots{}
613 Zero-terminated string data. Just like @code{.SDATA}, except that
614 @code{.SDATAZ} writes a zero byte at the end of the string.
616 @item .SDATAC "@var{str}" @dots{}
617 Count-prefixed string data. Just like @code{.SDATA}, except that
618 @sc{gasp} precedes the string with a leading one-byte count. For
619 example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the
620 count field is only one byte, you can only use @code{.SDATAC} for
621 strings less than 256 bytes in length.
625 @subsection Uninitialized data
627 @c FIXME! .space different on some platforms, notably HPPA. Config?
628 Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ}
629 directives to reserve memory and leave it uninitialized. @sc{gasp}
630 resolves these directives to appropriate calls of the @sc{gnu}
631 @code{as} @code{.space} directive.
634 @item .RES @var{count}
635 @itemx .RES.B @var{count}
636 @itemx .RES.W @var{count}
637 @itemx .RES.L @var{count}
638 Reserve room for @var{count} uninitialized elements of data. The
639 suffix specifies the size of each element: @code{.RES.B} reserves
640 @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes,
641 and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a
642 suffix is equivalent to @code{.RES.L}.
644 @item .SRES @var{count}
645 @itemx .SRES.B @var{count}
646 @itemx .SRES.W @var{count}
647 @itemx .SRES.L @var{count}
648 @c FIXME! This is boring. Shouldn't it at least have a different
649 @c default size? (e.g. the "S" suggests "string", for which .B
650 @c would be more appropriate)
651 @code{.SRES} is a synonym for @samp{.RES}.
653 @item .SRESC @var{count}
654 @itemx .SRESC.B @var{count}
655 @itemx .SRESC.W @var{count}
656 @itemx .SRESC.L @var{count}
657 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
659 @item .SRESZ @var{count}
660 @itemx .SRESZ.B @var{count}
661 @itemx .SRESZ.W @var{count}
662 @itemx .SRESZ.L @var{count}
663 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
667 @section Assembly listing control
669 The @sc{gasp} listing-control directives map straightforwardly to
670 related @sc{gnu} @code{as} directives.
675 Print control. This directive emits the @sc{gnu} @code{as} directive
676 @code{.list} or @code{.nolist}, according to its argument. @xref{List,,
677 @code{.list}, as.info, Using as}, for details on how these directives
680 @item .FORM LIN=@var{ln}
681 @itemx .FORM COL=@var{cols}
682 @itemx .FORM LIN=@var{ln} COL=@var{cols}
683 Specify the page size for assembly listings: @var{ln} represents the
684 number of lines, and @var{cols} the number of columns. You may specify
685 either page dimension independently, or both together. If you do not
686 specify the number of lines, @sc{gasp} assumes 60 lines; if you do not
687 specify the number of columns, @sc{gasp} assumes 132 columns.
688 (Any values you may have specified in previous instances of @code{.FORM}
689 do @emph{not} carry over as defaults.) Emits the @code{.psize}
692 @item .HEADING @var{string}
693 Specify @var{string} as the title of your assembly listings. Emits
694 @samp{.title "@var{string}"}.
697 Force a new page in assembly listings. Emits @samp{.eject}.
701 @section Miscellaneous commands
705 @c FIXME! This is very strange, since _GAS_ understands .org
706 This command is recognized, but not yet implemented. @sc{gasp}
707 generates an error message for programs that use @code{.ORG}.
710 @c FIXME no test cases in testsuite/gasp
711 @sc{gasp} understands numbers in any of base two, eight, ten, or
712 sixteen. You can encode the base explicitly in any numeric constant
713 (@pxref{Constants,, String and numeric constants}). If you write
714 numbers without an explicit indication of the base, the most recent
715 @samp{.RADIX @var{s}} command determines how they are interpreted.
716 @var{s} is a single letter, one of the following:
726 Base 10. This is the original default radix.
732 You may specify the argument @var{s} in lower case (any of @samp{bqdh})
733 with the same effects.
735 @item .EXPORT @var{name}
736 @itemx .GLOBAL @var{name}
737 @c FIXME! No test cases in testsuite/gasp
738 Declare @var{name} global (emits @samp{.global @var{name}}). The two
739 directives are synonymous.
742 No effect: @sc{gasp} accepts this directive, and silently ignores it.
745 Mark end of each preprocessor file. @sc{gasp} issues a warning if it
746 reaches end of file without seeing this command.
748 @item .INCLUDE "@var{str}"
749 Preprocess the file named by @var{str}, as if its contents appeared
750 where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum
751 limit of 30 stacked include files, as a sanity check.
752 @c FIXME! Why is include depth not affected by -u?
754 @item .ALIGN @var{size}
755 @c FIXME! Why is this not utterly pointless?
756 Evaluate the absolute expression @var{size}, and emit the assembly
757 instruction @samp{.align @var{size}} using the result.
761 @section Details of the GASP syntax
763 Since @sc{gasp} is meant to work with assembly code, its statement
764 syntax has no surprises for the assembly programmer.
767 @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially
768 significant, in that it delimits up to three fields in a line. The
769 amount of whitespace does not matter; you may line up fields in separate
770 lines if you wish, but @sc{gasp} does not require that.
772 @cindex fields of @sc{gasp} source line
774 The @emph{first field}, an optional @dfn{label}, must be flush left in a
775 line (with no leading whitespace) if it appears at all. You may use a
776 colon after the label if you wish; @sc{gasp} neither requires the colon
777 nor objects to it (but will not include it as part of the label name).
779 @cindex directive field
780 The @emph{second field}, which must appear after some whitespace,
781 contains a @sc{gasp} or assembly @dfn{directive}.
783 @cindex argument fields
784 Any @emph{further fields} on a line are @dfn{arguments} to the
785 directive; you can separate them from one another using either commas or
797 @subsection Special syntactic markers
799 @sc{gasp} recognizes a few special markers: to delimit comments, to
800 continue a statement on the next line, to separate symbols from other
801 characters, and to copy text to the output literally. (One other
802 special marker, @samp{\@@}, works only within macro definitions;
803 @pxref{Macros,, Defining your own directives}.)
806 The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
807 A comment begins with the first unquoted @samp{;} or @samp{\;}, and
808 extends to the end of a line. The two kinds of comment markers lead to
809 slightly different treatment:
813 Generate an assembly comment in the @sc{gasp} output. @sc{gasp} evaluates any
814 preprocessor variables (macro arguments, or variables defined with
815 @code{.ASSIGNA} or @code{.ASSIGNC}) present. For example, a macro that
819 .MACRO SUM FROM=0, TO=9
824 issues as the first line of output a comment that records the
825 values you used to call the macro.
828 This marks a @sc{gasp} source comment. @sc{gasp} does not copy such
829 comments to the assembly output.
832 @cindex continuation character
834 To @emph{continue a statement} on the next line of the file, begin the
835 second line with the character @samp{+}.
837 @cindex literal copy to output
838 @cindex copying literally to output
839 @cindex preprocessing, avoiding
840 @cindex avoiding preprocessing
841 Occasionally you may want to prevent @sc{gasp} from preprocessing some
842 particular bit of text. To @emph{copy literally} from the @sc{gasp}
843 source to its output, place @samp{\(} before the string to copy, and
844 @samp{)} at the end. For example, write @samp{\(\;)} if you need the
845 characters @samp{\;} in your assembly output.
847 @cindex symbol separator
848 @cindex text, separating from symbols
849 @cindex symbols, separating from text
850 To @emph{separate a preprocessor variable} from text to appear
851 immediately after its value, write a single quote (@code{'}). For
852 example, @samp{.SDATA "\P'1"} writes a string built by concatenating the
853 value of @code{P} and the digit @samp{1}. (You cannot achieve this by
854 writing just @samp{\P1}, since @samp{P1} is itself a valid name for a
855 preprocessor variable.)
858 @subsection String and numeric constants
860 There are two ways of writing @dfn{string constants} in @sc{gasp}: as
861 literal text, and by numeric byte value. Specify a string literal
862 between double quotes (@code{"@var{str}"}). Specify an individual
863 numeric byte value as an absolute expression between angle brackets
864 (@code{<@var{expr}>}. Directives that output strings allow you to
865 specify any number of either kind of value, in whatever order is
866 convenient, and concatenate the result.
868 @c Details of numeric notation, e.g. base prefixes
869 You can write @dfn{numeric constants} either in a specific base, or in
870 whatever base is currently selected (either 10, or selected by the most
871 recent @code{.RADIX}).
873 To write a number in a @emph{specific base}, use the pattern
874 @code{'@var{s}@var{ddd}}: a single quote, followed by a base specifier
875 character @var{s}, followed by digits @var{ddd}. The base specifier
876 character matches those you can specify with @code{.RADIX}: @samp{B} for
877 base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
878 16. (You can write this character in lower case if you prefer.)
880 @c FIXME! What are rules for recognizing number in deflt base? Whatever
881 @c is left over after parsing other things??
886 @sc{gasp} recognizes symbol names that start with any alphabetic character,
887 @samp{_}, or @samp{$}, and continue with any of the same characters or
888 with digits. Label names follow the same rules.
891 @subsection Arithmetic expressions in GASP
893 @cindex absolute expressions
894 @cindex relocatable expressions
895 There are two kinds of expressions, depending on their result:
896 @dfn{absolute} expressions, which resolve to a constant (that is, they
897 do not involve any values unknown to @sc{gasp}), and @dfn{relocatable}
898 expressions, which must reduce to the form
901 @var{addsym}+@var{const}-@var{subsym}
905 where @var{addsym} and @var{subsym} are assembly symbols of unknown
906 value, and @var{const} is a constant.
908 Arithmetic for @sc{gasp} expressions follows very similar rules to C.
909 You can use parentheses to change precedence; otherwise, arithmetic
910 primitives have decreasing precedence in the order of the following
915 Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or
916 @code{~} (bitwise negation). @emph{The argument must be an absolute
920 @code{*} (multiplication) and @code{/} (division). @emph{Both arguments
921 must be absolute expressions.}
924 @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument
926 @c FIXME! Actually, subtraction doesn't check for this.
929 @code{&} (bitwise and). @emph{Both arguments must be absolute.}
932 @c FIXME! I agree ~ is a better notation than ^ for xor, but is the
933 @c improvement worth differing from C?
934 @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in
935 C). @emph{Both arguments must be absolute.}
938 @node String Builtins
939 @subsection String primitives
941 You can use these primitives to manipulate strings (in the argument
942 field of @sc{gasp} statements):
945 @item .LEN("@var{str}")
946 Calculate the length of string @code{"@var{str}"}, as an absolute
947 expression. For example, @samp{.RES.B .LEN("sample")} reserves six
950 @item .INSTR("@var{string}", "@var{seg}", @var{ix})
951 Search for the first occurrence of @var{seg} after position @var{ix} of
952 @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates
953 to the absolute result @code{2}.
955 The result is @code{-1} if @var{seg} does not occur in @var{string}
956 after position @var{ix}.
958 @item .SUBSTR("@var{string}",@var{start},@var{len})
959 The substring of @var{string} beginning at byte number @var{start} and
960 extending for @var{len} bytes.