home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / gnumans.zip / gasp.inf (.txt) < prev    next >
OS/2 Help File  |  1997-07-02  |  31KB  |  661 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Title page ΓòÉΓòÉΓòÉ
  3.  
  4.                                   DRAFT EDITION
  5.  
  6.                          GASP, an assembly preprocessor
  7.  
  8.                                for GASP version 1
  9.  
  10.                                    March 1994
  11.  
  12.                                    Roland Pesch
  13.  
  14. Copyright (C) 1994 Free Software Foundation, Inc. 
  15.  
  16. Permission is granted to make and distribute verbatim copies of this manual 
  17. provided the copyright notice and this permission notice are preserved on all 
  18. copies. 
  19.  
  20. Permission is granted to copy and distribute modified versions of this manual 
  21. under the conditions for verbatim copying, provided also that the entire 
  22. resulting derived work is distributed under the terms of a permission notice 
  23. identical to this one. 
  24.  
  25. Permission is granted to copy and distribute translations of this manual into 
  26. another language, under the above conditions for modified versions. 
  27.  
  28.  
  29. ΓòÉΓòÉΓòÉ 2. Top node: "GASP" ΓòÉΓòÉΓòÉ
  30.  
  31. GASP is a preprocessor for assembly programs. 
  32.  
  33. This file describes version 1 of GASP. 
  34.  
  35. Steve Chamberlain wrote GASP; Roland Pesch wrote this manual. 
  36.  
  37.  Overview                                What is GASP? 
  38.  Invoking GASP                           Command line options. 
  39.  Commands                                Preprocessor commands. 
  40.  Index                                   Index. 
  41.  
  42.  
  43. ΓòÉΓòÉΓòÉ 3. What is GASP? ΓòÉΓòÉΓòÉ
  44.  
  45. The primary purpose of the gnu assembler is to assemble the output of other 
  46. programs---notably compilers.  When you have to hand-code specialized routines 
  47. in assembly, that means the gnu assembler is an unfriendly processor: it has no 
  48. directives for macros, conditionals, or many other conveniences that you might 
  49. expect. 
  50.  
  51. In some cases you can simply use the C preprocessor, or a generalized 
  52. preprocessor like m4; but this can be awkward, since none of these things are 
  53. designed with assembly in mind. 
  54.  
  55. gasp fills this need.  It is expressly designed to provide the facilities you 
  56. need with hand-coded assembly code.  Implementing it as a preprocessor, rather 
  57. than part of the assembler, allows the maximum flexibility: you can use it with 
  58. hand-coded assembly, without paying a penalty of added complexity in the 
  59. assembler you use for compiler output. 
  60.  
  61. Here is a small example to give the flavor of gasp.  This input to gasp 
  62.  
  63.         .MACRO  saveregs from=8 to=14
  64. count   .ASSIGNA \from
  65.         ! save r\from..r\to
  66.         .AWHILE  \&count LE \to
  67.         mov     r\&count,@-sp
  68. count   .ASSIGNA  \&count + 1
  69.         .AENDW
  70.         .ENDM
  71.  
  72.         saveregs from=12
  73.  
  74. bar:    mov     #H'dead+10,r0
  75. foo     .SDATAC "hello"<10>
  76.         .END
  77.  
  78. generates this assembly program: 
  79.  
  80.         ! save r12..r14
  81.         mov     r12,@-sp
  82.         mov     r13,@-sp
  83.         mov     r14,@-sp
  84.  
  85. bar:    mov     #57005+10,r0
  86. foo:    .byte   6,104,101,108,108,111,10
  87.  
  88.  
  89. ΓòÉΓòÉΓòÉ 4. Command Line Options ΓòÉΓòÉΓòÉ
  90.  
  91. The simplest way to use gasp is to run it as a filter and assemble its output. 
  92. In Unix and its ilk, you can do this, for example: 
  93.  
  94. $ gasp prog.asm | as -o prog.o
  95.  
  96. Naturally, there are also a few command-line options to allow you to request 
  97. variations on this basic theme.  Here is the full set of possibilities for the 
  98. gasp command line. 
  99.  
  100. gasp  [ -a | --alternate ]
  101.       [ -c char | --commentchar char ]
  102.       [ -d | --debug ]  [ -h | --help ]
  103.       [ -o outfile | --output outfile ]
  104.       [ -p | --print ]  [ -s | --copysource ]
  105.       [ -u | --unreasonable ]  [ -v | --version ]
  106.       infile ...
  107. infile ... The input file names.  You must specify at least one input file; if 
  108. you specify more, gasp preprocesses them all, concatenating the output in the 
  109. order you list the infile arguments. 
  110.  
  111. Mark the end of each input file with the preprocessor command .END.  See 
  112. Miscellaneous commands. -a --alternate Use alternative macro syntax. See 
  113. Alternate macro syntax, for a discussion of how this syntax differs from the 
  114. default gasp syntax. -c 'char' --commentchar 'char' Use char as the comment 
  115. character.  The default comment character is `!'.  For example, to use a 
  116. semicolon as the comment character, specify `-c ';'' on the gasp command line. 
  117. Since assembler command characters often have special significance to command 
  118. shells, it is a good idea to quote or escape char when you specify a comment 
  119. character. 
  120.  
  121. For the sake of simplicity, all examples in this manual use the default comment 
  122. character `!'. -d --debug Show debugging statistics.  In this version of gasp, 
  123. this option produces statistics about the string buffers that gasp allocates 
  124. internally.  For each defined buffersize s, gasp shows the number of strings n 
  125. that it allocated, with a line like this: 
  126.  
  127. strings size s : n
  128.  
  129. gasp displays these statistics on the standard error stream, when done 
  130. preprocessing. -h --help Display a summary of the gasp command line options. -o 
  131. outfile --output outfile Write the output in a file called outfile.  If you do 
  132. not use the `-o' option, gasp writes its output on the standard output stream. 
  133. -p --print Print line numbers.  gasp obeys this option only if you also specify 
  134. `-s' to copy source lines to its output.  With `-s -p', gasp displays the line 
  135. number of each source line copied (immediately after the comment character at 
  136. the beginning of the line). -s --copysource Copy the source lines to the output 
  137. file.  Use this option to see the effect of each preprocessor line on the gasp 
  138. output. gasp places a comment character (`!' by default) at the beginning of 
  139. each source line it copies, so that you can use this option and still assemble 
  140. the result. -u --unreasonable Bypass ``unreasonable expansion'' limit.  Since 
  141. you can define gasp macros inside other macro definitions, the preprocessor 
  142. normally includes a sanity check.  If your program requires more than 1,000 
  143. nested expansions, gasp normally exits with an error message.  Use this option 
  144. to turn off this check, allowing unlimited nested expansions. -v --version 
  145. Display the gasp version number. 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ 5. Preprocessor Commands ΓòÉΓòÉΓòÉ
  149.  
  150. gasp commands have a straightforward syntax that fits in well with assembly 
  151. conventions.  In general, a command extends for a line, and may have up to 
  152. three fields: an optional label, the command itself, and optional arguments to 
  153. the command.  You can write commands in upper or lower case, though this manual 
  154. shows them in upper case. See Details of the GASP syntax, for more information. 
  155.  
  156.  Conditionals 
  157.  Loops 
  158.  Variables 
  159.  Macros 
  160.  Data 
  161.  Listings 
  162.  Other Commands 
  163.  Syntax Details 
  164.  Alternate 
  165.  
  166.  
  167. ΓòÉΓòÉΓòÉ 5.1. Conditional assembly ΓòÉΓòÉΓòÉ
  168.  
  169. The conditional-assembly directives allow you to include or exclude portions of 
  170. an assembly depending on how a pair of expressions, or a pair of strings, 
  171. compare. 
  172.  
  173. The overall structure of conditionals is familiar from many other contexts. 
  174. .AIF marks the start of a conditional, and precedes assembly for the case when 
  175. the condition is true.  An optional .AELSE precedes assembly for the converse 
  176. case, and an .AENDI marks the end of the condition. 
  177.  
  178. You may nest conditionals up to a depth of 100; gasp rejects nesting beyond 
  179. that, because it may indicate a bug in your macro structure. 
  180.  
  181. Conditionals are primarily useful inside macro definitions, where you often 
  182. need different effects depending on argument values. See Defining your own 
  183. directives, for details about defining macros. .AIF expra cmp exprb .AIF "stra" 
  184. cmp "strb" 
  185.  
  186. The governing condition goes on the same line as the .AIF preprocessor command. 
  187. You may compare either two strings, or two expressions. 
  188.  
  189. When you compare strings, only two conditional cmp comparison operators are 
  190. available: `EQ' (true if stra and strb are identical), and `NE' (the converse). 
  191.  
  192. When you compare two expressions, both expressions must be absolute (see 
  193. Arithmetic expressions in GASP).  You can use these cmp comparison operators 
  194. with expressions: EQ Are expra and exprb equal?  (For strings, are stra and 
  195. strb identical?) NE Are expra and exprb different?  (For strings, are stra and 
  196. strb different? LT Is expra less than exprb?  (Not allowed for strings.) LE Is 
  197. expra less than or equal to exprb?  (Not allowed for strings.) GT Is expra 
  198. greater than exprb?  (Not allowed for strings.) GE Is expra greater than or 
  199. equal to exprb?  (Not allowed for strings.) .AELSE Marks the start of assembly 
  200.            code to be included if the condition fails. Optional, and only 
  201.            allowed within a conditional (between .AIF and .AENDI). .AENDI Marks 
  202.            the end of a conditional assembly. 
  203.  
  204.  
  205. ΓòÉΓòÉΓòÉ 5.2. Repetitive sections of assembly ΓòÉΓòÉΓòÉ
  206.  
  207. Two preprocessor directives allow you to repeatedly issue copies of the same 
  208. block of assembly code. .AREPEAT aexp .AENDR If you simply need to repeat the 
  209. same block of assembly over and over a fixed number of times, sandwich one 
  210. instance of the repeated block between .AREPEAT and .AENDR.  Specify the number 
  211. of copies as aexp (which must be an absolute expression).  For example, this 
  212. repeats two assembly statements three times in succession: 
  213.  
  214.         .AREPEAT        3
  215.         rotcl   r2
  216.         div1    r0,r1
  217.         .AENDR
  218. .AWHILE expra cmp exprb .AENDW .AWHILE stra cmp strb .AENDW To repeat a block 
  219. of assembly depending on a conditional test, rather than repeating it for a 
  220. specific number of times, use .AWHILE. .AENDW marks the end of the repeated 
  221. block.  The conditional comparison works exactly the same way as for .AIF, with 
  222. the same comparison operators (see Conditional assembly). 
  223.  
  224. Since the terms of the comparison must be absolute expression, .AWHILE is 
  225. primarily useful within macros. See Defining your own directives. 
  226.  
  227.  You can use the .EXITM preprocessor directive to break out of loops early (as 
  228.  well as to break out of macros). See Defining your own directives. 
  229.  
  230.  
  231. ΓòÉΓòÉΓòÉ 5.3. Preprocessor variables ΓòÉΓòÉΓòÉ
  232.  
  233. You can use variables in gasp to represent strings, registers, or the results 
  234. of expressions. 
  235.  
  236. You must distinguish two kinds of variables: 
  237.  
  238.    1. Variables defined with .EQU or .ASSIGN.  To evaluate this kind of 
  239.       variable in your assembly output, simply mention its name.  For example, 
  240.       these two lines define and use a variable `eg': 
  241.  
  242.             eg     .EQU   FLIP-64
  243.                    ...
  244.                    mov.l  eg,r0
  245.  
  246.       Do not use this kind of variable in conditional expressions or while 
  247.       loops; gasp only evaluates these variables when writing assembly output. 
  248.  
  249.    2. Variables for use during preprocessing.  You can define these with 
  250.       .ASSIGNC or .ASSIGNA.  To evaluate this kind of variable, write `\&' 
  251.       before the variable name; for example, 
  252.  
  253.             opcit  .ASSIGNA  47
  254.                    ...
  255.                    .AWHILE  \&opcit GT 0
  256.                    ...
  257.                    .AENDW
  258.  
  259.       gasp treats macro arguments almost the same way, but to evaluate them you 
  260.       use the prefix `\' rather than `\&'. See Defining your own directives. 
  261.  pvar .EQU expr Assign preprocessor variable pvar the value of the expression 
  262.  expr.  There are no restrictions on redefinition; use `.EQU' with the same 
  263.  pvar as often as you find it convenient. pvar .ASSIGN expr Almost the same as 
  264.  .EQU, save that you may not redefine pvar using .ASSIGN once it has a value. 
  265.  pvar .ASSIGNA aexpr Define a variable with a numeric value, for use during 
  266.  preprocessing. aexpr must be an absolute expression.  You can redefine 
  267.  variables with .ASSIGNA at any time. pvar .ASSIGNC "str" Define a variable 
  268.  with a string value, for use during preprocessing. You can redefine variables 
  269.  with .ASSIGNC at any time. pvar .REG (register) Use .REG to define a variable 
  270.  that represents a register.  In particular, register is not evaluated as an 
  271.  expression. You may use .REG at will to redefine register variables. 
  272.  
  273.  All these directives accept the variable name in the ``label'' position, that 
  274.  is at the left margin.  You may specify a colon after the variable name if you 
  275.  wish; the first example above could have started `eg:' with the same effect. 
  276.  
  277.  
  278. ΓòÉΓòÉΓòÉ 5.4. Defining your own directives ΓòÉΓòÉΓòÉ
  279.  
  280. The commands .MACRO and .ENDM allow you to define macros that generate assembly 
  281. output.  You can use these macros with a syntax similar to built-in gasp or 
  282. assembler directives.  For example, this definition specifies a macro SUM that 
  283. adds together a range of consecutive registers: 
  284.  
  285.         .MACRO  SUM FROM=0, TO=9
  286.         ! \FROM \TO
  287.         mov     r\FROM,r10
  288. COUNT   .ASSIGNA        \FROM+1
  289.         .AWHILE \&COUNT LE \TO
  290.         add     r\&COUNT,r10
  291. COUNT   .ASSIGNA        \&COUNT+1
  292.         .AENDW
  293.         .ENDM
  294.  
  295. With that definition, `SUM 0,5' generates this assembly output: 
  296.  
  297.         ! 0 5
  298.         mov     r0,r10
  299.         add     r1,r10
  300.         add     r2,r10
  301.         add     r3,r10
  302.         add     r4,r10
  303.         add     r5,r10
  304. .MACRO macname .MACRO macname macargs ... Begin the definition of a macro 
  305. called macname.  If your macro definition requires arguments, specify their 
  306. names after the macro name, separated by commas or spaces.  You can supply a 
  307. default value for any macro argument by following the name with `=deflt'.  For 
  308. example, these are all valid .MACRO statements: 
  309.  
  310.            .MACRO COMM 
  311.                           Begin the definition of a macro called COMM, which 
  312.                           takes no arguments. 
  313.  
  314.            .MACRO PLUS1 P, P1 
  315.            .MACRO PLUS1 P P1 
  316.                           Either statement begins the definition of a macro 
  317.                           called PLUS1, which takes two arguments; within the 
  318.                           macro definition, write `\P' or `\P1' to evaluate the 
  319.                           arguments. 
  320.  
  321.            .MACRO RESERVE_STR P1=0 P2 
  322.                           Begin the definition of a macro called RESERVE_STR, 
  323.                           with two arguments.  The first argument has a default 
  324.                           value, but not the second. After the definition is 
  325.                           complete, you can call the macro either as 
  326.                           `RESERVE_STR a,b' (with `\P1' evaluating to a and 
  327.                           `\P2' evaluating to b), or as `RESERVE_STR ,b' (with 
  328.                           `\P1' evaluating as the default, in this case `0', 
  329.                           and `\P2' evaluating to b). 
  330.  
  331.            When you call a macro, you can specify the argument values either by 
  332.            position, or by keyword.  For example, `SUM 9,17' is equivalent to 
  333.            `SUM TO=17, FROM=9'.  Macro arguments are preprocessor variables 
  334.            similar to the variables you define with `.ASSIGNA' or `.ASSIGNC'; 
  335.            in particular, you can use them in conditionals or for loop control. 
  336.            (The only difference is the prefix you write to evaluate the 
  337.            variable: for a macro argument, write `\argname', but for a 
  338.            preprocessor variable, write `\&varname'.) name .MACRO name .MACRO ( 
  339.            macargs ... ) An alternative form of introducing a macro definition: 
  340.            specify the macro name in the label position, and the arguments (if 
  341.            any) between parentheses after the name.  Defaulting rules and usage 
  342.            work the same way as for the other macro definition syntax. .ENDM 
  343.            Mark the end of a macro definition. .EXITM Exit early from the 
  344.            current macro definition, .AREPEAT loop, or .AWHILE loop. \@ gasp 
  345.            maintains a counter of how many macros it has executed in this 
  346.            pseudo-variable; you can copy that number to your output with `\@', 
  347.            but only within a macro definition. LOCAL name [ , ... ] Warning: 
  348.            LOCAL is only available if you select ``alternate macro syntax'' 
  349.            with `-a' or `--alternate'. See Alternate macro syntax. 
  350.  
  351.            Generate a string replacement for each of the name arguments, and 
  352.            replace any instances of name in each macro expansion.  The 
  353.            replacement string is unique in the assembly, and different for each 
  354.            separate macro expansion.  LOCAL allows you to write macros that 
  355.            define symbols, without fear of conflict between separate macro 
  356.            expansions. 
  357.  
  358.  
  359. ΓòÉΓòÉΓòÉ 5.5. Data output ΓòÉΓòÉΓòÉ
  360.  
  361. In assembly code, you often need to specify working areas of memory; depending 
  362. on the application, you may want to initialize such memory or not.  gasp 
  363. provides preprocessor directives to help you avoid repetitive coding for both 
  364. purposes. 
  365.  
  366. You can use labels as usual to mark the data areas. 
  367.  
  368.  Initialized 
  369.  Uninitialized 
  370.  
  371.  
  372. ΓòÉΓòÉΓòÉ 5.5.1. Initialized data ΓòÉΓòÉΓòÉ
  373.  
  374. These are the gasp directives for initialized data, and the standard gnu 
  375. assembler directives they expand to: .DATA expr, expr, ... .DATA.B expr, expr, 
  376. ... .DATA.W expr, expr, ... .DATA.L expr, expr, ... Evaluate arithmetic 
  377. expressions expr, and emit the corresponding as directive (labelled with lab). 
  378. The unqualified .DATA emits `.long'; .DATA.B emits `.byte'; .DATA.W emits 
  379. `.short'; and .DATA.L emits `.long'. 
  380.  
  381. For example, `foo .DATA 1,2,3' emits `foo: .long 1,2,3'. .DATAB repeat, expr 
  382. .DATAB.B repeat, expr .DATAB.W repeat, expr .DATAB.L repeat, expr Make as emit 
  383. repeat copies of the value of the expression expr (using the as directive 
  384. .fill). `.DATAB.B' repeats one-byte values; `.DATAB.W' repeats two-byte values; 
  385. and `.DATAB.L' repeats four-byte values. `.DATAB' without a suffix repeats 
  386. four-byte values, just like `.DATAB.L'. 
  387.  
  388. repeat must be an absolute expression with a positive value. .SDATA "str" ... 
  389. String data.  Emits a concatenation of bytes, precisely as you specify them (in 
  390. particular, nothing is added to mark the end of the string).  See String and 
  391. numeric constants, for details about how to write strings.  .SDATA concatenates 
  392. multiple arguments, making it easy to switch between string representations. 
  393. You can use commas to separate the individual arguments for clarity, if you 
  394. choose. .SDATAB repeat, "str" ... Repeated string data.  The first argument 
  395. specifies how many copies of the string to emit; the remaining arguments 
  396. specify the string, in the same way as the arguments to .SDATA. .SDATAZ "str" 
  397. ... Zero-terminated string data.  Just like .SDATA, except that .SDATAZ writes 
  398. a zero byte at the end of the string. .SDATAC "str" ... Count-prefixed string 
  399. data.  Just like .SDATA, except that gasp precedes the string with a leading 
  400. one-byte count.  For example, `.SDATAC "HI"' generates `.byte 2,72,73'.  Since 
  401. the count field is only one byte, you can only use .SDATAC for strings less 
  402. than 256 bytes in length. 
  403.  
  404.  
  405. ΓòÉΓòÉΓòÉ 5.5.2. Uninitialized data ΓòÉΓòÉΓòÉ
  406.  
  407. Use the .RES, .SRES, .SRESC, and .SRESZ directives to reserve memory and leave 
  408. it uninitialized.  gasp resolves these directives to appropriate calls of the 
  409. gnu as .space directive. .RES count .RES.B count .RES.W count .RES.L count 
  410. Reserve room for count uninitialized elements of data.  The suffix specifies 
  411. the size of each element: .RES.B reserves count bytes, .RES.W reserves count 
  412. pairs of bytes, and .RES.L reserves count quartets.  .RES without a suffix is 
  413. equivalent to .RES.L. .SRES count .SRES.B count .SRES.W count .SRES.L count 
  414. .SRES is a synonym for `.RES'. .SRESC count .SRESC.B count .SRESC.W count 
  415. .SRESC.L count Like .SRES, but reserves space for count+1 elements. .SRESZ 
  416. count .SRESZ.B count .SRESZ.W count .SRESZ.L count Like .SRES, but reserves 
  417. space for count+1 elements. 
  418.  
  419.  
  420. ΓòÉΓòÉΓòÉ 5.6. Assembly listing control ΓòÉΓòÉΓòÉ
  421.  
  422. The gasp listing-control directives map straightforwardly to related gnu as 
  423. directives. .PRINT LIST .PRINT NOLIST Print control.  This directive emits the 
  424. gnu as directive .list or .nolist, according to its argument. See .list, for 
  425. details on how these directives interact. .FORM LIN=ln .FORM COL=cols .FORM 
  426. LIN=ln COL=cols Specify the page size for assembly listings: ln represents the 
  427. number of lines, and cols the number of columns.  You may specify either page 
  428. dimension independently, or both together.  If you do not specify the number of 
  429. lines, gasp assumes 60 lines; if you do not specify the number of columns, gasp 
  430. assumes 132 columns. (Any values you may have specified in previous instances 
  431. of .FORM do not carry over as defaults.)  Emits the .psize assembler directive. 
  432. .HEADING string Specify string as the title of your assembly listings.  Emits 
  433. `.title "string"'. .PAGE Force a new page in assembly listings.  Emits 
  434. `.eject'. 
  435.  
  436.  
  437. ΓòÉΓòÉΓòÉ 5.7. Miscellaneous commands ΓòÉΓòÉΓòÉ
  438.  
  439. .ALTERNATE Use the alternate macro syntax henceforth in the assembly. See 
  440. Alternate macro syntax. .ORG This command is recognized, but not yet 
  441. implemented.  gasp generates an error message for programs that use .ORG. 
  442. .RADIX s gasp understands numbers in any of base two, eight, ten, or sixteen. 
  443. You can encode the base explicitly in any numeric constant (see String and 
  444. numeric constants).  If you write numbers without an explicit indication of the 
  445. base, the most recent `.RADIX s' command determines how they are interpreted. s 
  446. is a single letter, one of the following: 
  447.  
  448.            .RADIX B 
  449.                           Base 2. 
  450.  
  451.            .RADIX Q 
  452.                           Base 8. 
  453.  
  454.            .RADIX D 
  455.                           Base 10.  This is the original default radix. 
  456.  
  457.            .RADIX H 
  458.                           Base 16. 
  459.  
  460.            You may specify the argument s in lower case (any of `bqdh') with 
  461.            the same effects. .EXPORT name .GLOBAL name Declare name global 
  462.            (emits `.global name').  The two directives are synonymous. .PROGRAM 
  463.            No effect: gasp accepts this directive, and silently ignores it. 
  464.            .END Mark end of each preprocessor file.  gasp issues a warning if 
  465.            it reaches end of file without seeing this command. .INCLUDE "str" 
  466.            Preprocess the file named by str, as if its contents appeared where 
  467.            the .INCLUDE directive does.  gasp imposes a maximum limit of 30 
  468.            stacked include files, as a sanity check. .ALIGN size Evaluate the 
  469.            absolute expression size, and emit the assembly instruction `.align 
  470.            size' using the result. 
  471.  
  472.  
  473. ΓòÉΓòÉΓòÉ 5.8. Details of the GASP syntax ΓòÉΓòÉΓòÉ
  474.  
  475. Since gasp is meant to work with assembly code, its statement syntax has no 
  476. surprises for the assembly programmer. 
  477.  
  478. Whitespace (blanks or tabs; not newline) is partially significant, in that it 
  479. delimits up to three fields in a line.  The amount of whitespace does not 
  480. matter; you may line up fields in separate lines if you wish, but gasp does not 
  481. require that. 
  482.  
  483. The first field, an optional label, must be flush left in a line (with no 
  484. leading whitespace) if it appears at all.  You may use a colon after the label 
  485. if you wish; gasp neither requires the colon nor objects to it (but will not 
  486. include it as part of the label name). 
  487.  
  488. The second field, which must appear after some whitespace, contains a gasp or 
  489. assembly directive. 
  490.  
  491. Any further fields on a line are arguments to the directive; you can separate 
  492. them from one another using either commas or whitespace. 
  493.  
  494.  Markers 
  495.  Constants 
  496.  Symbols 
  497.  Expressions 
  498.  String Builtins 
  499.  
  500.  
  501. ΓòÉΓòÉΓòÉ 5.8.1. Special syntactic markers ΓòÉΓòÉΓòÉ
  502.  
  503. gasp recognizes a few special markers: to delimit comments, to continue a 
  504. statement on the next line, to separate symbols from other characters, and to 
  505. copy text to the output literally.  (One other special marker, `\@', works only 
  506. within macro definitions; see Defining your own directives.) 
  507.  
  508. The trailing part of any gasp source line may be a comment. A comment begins 
  509. with the first unquoted comment character (`!' by default), or an escaped or 
  510. doubled comment character (`\!' or `!!' by default), and extends to the end of 
  511. a line.  You can specify what comment character to use with the `-c' option 
  512. (see Command Line Options).  The two kinds of comment markers lead to slightly 
  513. different treatment: 
  514.  
  515.  ! 
  516.            A single, un-escaped comment character generates an assembly comment 
  517.            in the gasp output.  gasp evaluates any preprocessor variables 
  518.            (macro arguments, or variables defined with .ASSIGNA or .ASSIGNC) 
  519.            present.  For example, a macro that begins like this 
  520.  
  521.                               .MACRO  SUM FROM=0, TO=9
  522.                               ! \FROM \TO
  523.  
  524.            issues as the first line of output a comment that records the values 
  525.            you used to call the macro. 
  526.  
  527.  \! 
  528.  !! 
  529.            Either an escaped comment character, or a double comment character, 
  530.            marks a gasp source comment.  gasp does not copy such comments to 
  531.            the assembly output. 
  532.  
  533.  To continue a statement on the next line of the file, begin the second line 
  534.  with the character `+'. 
  535.  
  536.  Occasionally you may want to prevent gasp from preprocessing some particular 
  537.  bit of text.  To copy literally from the gasp source to its output, place `\(' 
  538.  before the string to copy, and `)' at the end.  For example, write `\(\!)' if 
  539.  you need the characters `\!' in your assembly output. 
  540.  
  541.  To separate a preprocessor variable from text to appear immediately after its 
  542.  value, write a single quote (').  For example, `.SDATA "\P'1"' writes a string 
  543.  built by concatenating the value of P and the digit `1'.  (You cannot achieve 
  544.  this by writing just `\P1', since `P1' is itself a valid name for a 
  545.  preprocessor variable.) 
  546.  
  547.  
  548. ΓòÉΓòÉΓòÉ 5.8.2. String and numeric constants ΓòÉΓòÉΓòÉ
  549.  
  550. There are two ways of writing string constants in gasp: as literal text, and by 
  551. numeric byte value.  Specify a string literal between double quotes ("str"). 
  552. Specify an individual numeric byte value as an absolute expression between 
  553. angle brackets (<expr>.  Directives that output strings allow you to specify 
  554. any number of either kind of value, in whatever order is convenient, and 
  555. concatenate the result.  (Alternate syntax mode introduces a number of 
  556. alternative string notations; see Alternate macro syntax.) 
  557.  
  558. You can write numeric constants either in a specific base, or in whatever base 
  559. is currently selected (either 10, or selected by the most recent .RADIX). 
  560.  
  561. To write a number in a specific base, use the pattern s'ddd: a base specifier 
  562. character s, followed by a single quote followed by digits ddd.  The base 
  563. specifier character matches those you can specify with .RADIX: `B' for base 2, 
  564. `Q' for base 8, `D' for base 10, and `H' for base 16.  (You can write this 
  565. character in lower case if you prefer.) 
  566.  
  567.  
  568. ΓòÉΓòÉΓòÉ 5.8.3. Symbols ΓòÉΓòÉΓòÉ
  569.  
  570. gasp recognizes symbol names that start with any alphabetic character, `_', or 
  571. `$', and continue with any of the same characters or with digits.  Label names 
  572. follow the same rules. 
  573.  
  574.  
  575. ΓòÉΓòÉΓòÉ 5.8.4. Arithmetic expressions in GASP ΓòÉΓòÉΓòÉ
  576.  
  577. There are two kinds of expressions, depending on their result: absolute 
  578. expressions, which resolve to a constant (that is, they do not involve any 
  579. values unknown to gasp), and relocatable expressions, which must reduce to the 
  580. form 
  581.  
  582. addsym+const-subsym
  583.  
  584. where addsym and subsym are assembly symbols of unknown value, and const is a 
  585. constant. 
  586.  
  587. Arithmetic for gasp expressions follows very similar rules to C. You can use 
  588. parentheses to change precedence; otherwise, arithmetic primitives have 
  589. decreasing precedence in the order of the following list. 
  590.  
  591.    1. Single-argument + (identity), - (arithmetic opposite), or ~ (bitwise 
  592.       negation).  The argument must be an absolute expression. 
  593.  
  594.    2. * (multiplication) and / (division).  Both arguments must be absolute 
  595.       expressions. 
  596.  
  597.    3. + (addition) and - (subtraction).  At least one argument must be 
  598.       absolute. 
  599.  
  600.    4. & (bitwise and).  Both arguments must be absolute. 
  601.  
  602.    5. | (bitwise or) and ~ (bitwise exclusive or; ^ in C).  Both arguments must 
  603.       be absolute. 
  604.  
  605.  
  606. ΓòÉΓòÉΓòÉ 5.8.5. String primitives ΓòÉΓòÉΓòÉ
  607.  
  608. You can use these primitives to manipulate strings (in the argument field of 
  609. gasp statements): .LEN("str") Calculate the length of string "str", as an 
  610. absolute expression.  For example, `.RES.B .LEN("sample")' reserves six bytes 
  611. of memory. .INSTR("string", "seg", ix) Search for the first occurrence of seg 
  612. after position ix of string.  For example, `.INSTR("ABCDEFG", "CDE", 0)' 
  613. evaluates to the absolute result 2. 
  614.  
  615. The result is -1 if seg does not occur in string after position ix. 
  616. .SUBSTR("string",start,len) The substring of string beginning at byte number 
  617. start and extending for len bytes. 
  618.  
  619.  
  620. ΓòÉΓòÉΓòÉ 5.9. Alternate macro syntax ΓòÉΓòÉΓòÉ
  621.  
  622. If you specify `-a' or `--alternate' on the gasp command line, the preprocessor 
  623. uses somewhat different syntax.  This syntax is reminiscent of the syntax of 
  624. Phar Lap macro assembler, but it is not meant to be a full emulation of Phar 
  625. Lap or similar assemblers.  In particular, gasp does not support directives 
  626. such as DB and IRP, even in alternate syntax mode. 
  627.  
  628. In particular, `-a' (or `--alternate') elicits these differences: 
  629.  
  630.  Preprocessor directives 
  631.            You can use gasp preprocessor directives without a leading `.' dot. 
  632.            For example, you can write `SDATA' with the same effect as `.SDATA'. 
  633.  
  634.  LOCAL 
  635.            One additional directive, LOCAL, is available. See Defining your own 
  636.            directives, for an explanation of how to use LOCAL. 
  637.  
  638.  String delimiters 
  639.            You can write strings delimited in these other ways besides 
  640.            "string": 
  641.  
  642.            'string' 
  643.                           You can delimit strings with single-quote charaters. 
  644.  
  645.            <string> 
  646.                           You can delimit strings with matching angle brackets. 
  647.  
  648.  single-character string escape 
  649.            To include any single character literally in a string (even if the 
  650.            character would otherwise have some special meaning), you can prefix 
  651.            the character with `!' (an exclamation mark).  For example, you can 
  652.            write `<4.3 !> 5.4!!>' to get the literal text `4.3 > 5.4!'. 
  653.  
  654.  Expression results as strings 
  655.            You can write `%expr' to evaluate the expression expr and use the 
  656.            result as a string. 
  657.  
  658.  
  659. ΓòÉΓòÉΓòÉ 6. Index ΓòÉΓòÉΓòÉ
  660.  
  661. Sorry, no cp index