Instructions for MS-DOS program "RPLCOMP"

       *****************************************************************

                                     NOTICE

       Hewlett-Packard is making RPLCOMP.EXE available to customers free
       of charge to help them in HP 48SX application development, under
       the following conditions:


       *  The program RPLCOMP.EXE and the documentation file RPLCOMP.MAN
          are provided "as is," and are subject to change without notice.
          Hewlett-Packard Company make no warranty of any kind with
          regard to the software or documentation, including, but not
          limited to, the implied warranties of merchantability and
          fitness for a particular purpose.  Hewlett-Packard Company
          shall not be liable for any error or for incidental or
          consequential damages in connection with the furnishing,
          performance, or use of this software and documentation.


       *  The program and documentation are copyrighted by Hewlett-
          Packard.  Sale of this material is prohibited without prior
          written permission of Hewlett-Packard Company.


       *  The HP Customer Support department does not support RPLCOMP.
          Questions, comments, defect reports, etc. should be directed to
          the Library Development conference on the HP Calculator
          Bulletin Board System.  All responses from Hewlett-Packard will
          normally be provided through that conference.


       *  Software generated by RPLCOMP.EXE should be tested and
          qualified in its final form.

       Revised versions of the software and documentation will be posted
       on the Bulletin Board as they become available.















                                   -1-











       1.  RPLCOMP - RPL Compiler

       Rplcomp is an RPL compiler or, more precisely, a preprocessor.
       From RPL source files, it produces sasm source files ready for
       assembly.

       The compiler is invoked as follows:

         rplcomp [ -C ] [ <inputfile> [ <outputfile> [ <extfile> ] ] ]

       Rplcomp accepts up to 3 arguments:

       <inputfile>    Specifies the RPL source.  If omitted or specified
                      as ``-'', it defaults to stdin. RPL source file
                      names by convention use the ``.s'' extension.

       <outputfile>   Specifies where the output will go, defaulting to
                      stdout.  Since the output is usually fed to sasm,
                      RPL output file names by convention use the ``.a''
                      extension.

       <extfile>      Specifies the file containing information for the
                      hash table, so named because the customary
                      extension is ``.ext''.  If this parameter is
                      omitted, this information is not output.  If this
                      paramater is specified as ``-'', the information is
                      output to stdout.

       The -C option copies the RPL source as comments in the output
       code.  This allows a post-processor to edit the assembly listings
       in a more readable format.


       1.1  Object Definition


       When rplcomp is compiling a file, it recognizes certain words
       (detailed below) and generates appropriate code for them.  All
       other words are assumed to be the labels of objects in the
       runstream, and are emitted simply as 5-nibble constants, possibly
       with substitution as per DEFINE below.  After assembly, the SLOAD
       program will be used to fill in the addresses of the objects in
       the runstream based on the provided list of entry points called
       ENTRIES.O.

       The following sections describes the words recognized by rplcomp,
       and their corresponding actions.

       The following words define objects:





                                   -2-











       LAM <lamid>
          Defines a DOLAM object whose name is specified by <lamid>.  The
          non-ASCII escape sequences listed under $ below are allowed.
          <_l_a_m_i_d> may be a DEFINED value (See DEFINE below).

       ID <id>
          Defines a DOIDNT object whose name is specified by <id>.  <_i_d>
          may be a DEFINED value (See DEFINE below).

       TAG <tagid> <object>
          Defines a DOTAG object whose tag is specified by <tagid> and
          whose object is given by <object>.  <object> may be either an
          object definition or a label.  < tagid > may be a DEFINED value
          (See DEFINE below).

       $ "string"
       "string"
          Defines a DOCSTR object with the contents contained between the
          quotes.  Two consecutive quotes within the string are
          interpreted as a single quote (e.g., ``""""'' becomes the
          string ``f(CW"'').  Non-ASCII characters may be input as \xx
          where xx is the hex value of the character.  Also, \n, \r, \f,
          \t are the ASCII newline, return, form-feed, and tab
          characters.

       CHR <char>
       CHR ^<char>
       CHR "<char>"
       CHR "^<char>"
          Defines a DOCHAR object with the specified character.  The
          second and fourth forms generate control characters.  For
          example, ``CHR A'' generates an ``A'', ``CHR ^A'' generates a
          control-A.  The double-quote character can be generated by
          specifying ``CHR "'' or ``CHR """''.  Also, the \-escaped
          characters described under $ above can be used.

       CODE
       ...(assembly language code)...
       ENDCODE
          For insertion of assembly-language code in a DOCODE object.
          The word CODE generates a DOCODE and a link field, the word
          ENDCODE terminates assembly-language input and generates a
          label to be used by the link field.  When encountered in the
          assembly-language code, the word LOOP results in generation of
          RPL main loop code.  The words LOOP and ENDCODE are recognized
          by rplcomp if they are either 1) the first word on the line, or
          2) the second word preceded by a label.







                                   -3-











       # <hex number>
       #<hex number>
       <dec number>
          Defines a DOBINT object whose body is the number specified in
          hex or in decimal.  Rplcomp recognizes lower-case hex digits;
          compiler does not.

       <real number>
       % <real number>
          Defines a DOREAL object with the specified floating-point
          number.  To be recognized as a real number in the first form,
          the number must contain a decimal point and/or ``E''.  The
          second form is more forgiving, and will recognize an integer as
          a real number.

       %% <extended real number>
          Defines a DOEREL object with the specified floating-point
          number.

       C% <real number> <real number>
          Defines a DOCMP object with the specified floating-point
          numbers.

       C%% <extended real number> <extended real number>
          Defines a DOECMP object with the specified floating-point
          numbers.

       PTR <label>
          Forces the <label> to be entered as a runstream object.

       ROMPTR <hex #> <hex #>
       ROMPTR <label>
          Defines a DOROMP object with the two 3-digit (maximum) hex
          numbers.  If <label> is present, forms a DOROMP object for that
          label (resolved by the linker).

       ARRY [ obj ... ]
       ARRY dim ... [ obj ... ]
       LNKARRY [ obj ... ]
       LNKARRY dim ... [ obj ... ]
          Defines a DOARRY or DOLNKARRY object with the following
          characteristics: If dim ... is present, the array will be set
          up with the given dimensionality.  If no dimensions are
          present, a linear array will be constructed to contain the list
          of objects.

          At least one object must always be specified because the
          element type is determined from the object.  The list of
          objects will occupy element positions in order.  For an ARRY,
          every object position must have an object; in LNKARRYs, object
          positions may be left blank by using _ as a placeholder, and by



                                   -4-











          dimensioning the array larger than the object list.

          Array objects must be object definitions; pointers to objects
          are not supported by RPL.

       HXS <length in hex> <string>
       HXS 0
       GROB <length in hex> <string>
       GROB 0
          Defines a DOHSTR or DOGROB object with the specified hex
          string.  If the string contains fewer nibbles than specified by
          the length, the hex string will be padded with leading zeroes.
          (This is a departure from compiler, which padded with trailing
          zeroes.)

          If the length is zero, HXS does not take a second argument.

       CONTROL STRUCTURES

       The following words generate RPL control words.  In addition,
       rplcomp tracks, on an internal stack, the use of these words to
       ensure that all opening control words (such as ``::'') are matched
       by closing control words (such as ``;'').

       When non-structured programming techniques are being used, or
       unrecognized control words are used, this behavior can be defeated
       in two ways:  1) If the control word is surrounded by parentheses,
       rplcomp performs the appropriate internal stack operations but
       does not emit any code; 2) If the control word is surrounded by
       square brackets, the control word label is compiled, and rplcomp
       does not perform the associated internal stack operations.

       Examples:
       1)
          -1 The sequence ``DO [LOOP] LOOP'' will emit DO, LOOP, and
         LOOP, but will not consider the second ``LOOP'' to be unmatched.
       2)
          -1 The sequence ``ONE_DO (DO) LOOP'' will emit ONE_DO and LOOP,
         and will not consider the ``LOOP'' to be unmatched.

       This feature, an enhancement over compiler, can be applied to all
       control words except FCN.

       The RPL control words recognized by rplcomp are:

       :: ...(RPLcode)...  ;
          The word ``::'' generates DOCOL, the word ``;'' generates SEMI.







                                   -5-











       BEGIN ...(RPLcode)... AGAIN
       BEGIN ...(RPLcode)... UNTIL
       BEGIN ...(RPLcode)... WHILE ...(RPLcode)... REPEAT
          These words generate the appropriate RPL words.  The RPL code
          between WHILE and REPEAT is sandwiched between a DOCOL and a
          SEMI.

       DO ...(RPLcode)... LOOP
       DO ...(RPLcode)... +LOOP
          These words generate the appropriate RPL words.

       IF ...(THENclause)... THEN
       IF ...(THENclause)... ELSE ...(ELSEclause)... THEN
          These words generate the appropriate combinations of quotes,
          DOCOLs, SEMIs, RPITs, and RPITEs to emulate the corresponding
          FORTH words.

       FCN { ...(list of LAM ids)... } ...(RPLcode)... ENDFCN
          Generates a list of LAMs, BIND, and ABND for writing an RPL
          function.  The sequence:
           .5 FCN { A B C } ...(RPLcode)... ENDFCN
           .5 is equivalent to:
           .5 { LAM A LAM B LAM C } BIND ...(RPLcode)... ABND

       { ...(RPLcode)... }
          The words ``{'' and ``}'' delimit a list, generating the words
          DOLIST and SEMI (respectively).



























                                   -6-











       1.2  Miscellaneous RPL Operations


       The following words are recognized by rplcomp:

       ASSEMBLE
       ...(assembly language code)...
       RPL
          For insertion of assembly-language code.  When encountered in
          the assembly-language code, the word LOOP results in generation
          of RPL main loop code.  The words LOOP and RPL are recognized
          by rplcomp if they are either 1) the first word on the line, or
          2) the second word preceded by a label.

       ( ...(comments)... )
       * ...(comment text)...
          A left-parenthesis token begins a comment.  The comment is
          terminated immediately when a right-parenthesis is encountered
          - the right-parenthesis need not be surrounded by white space
          (this peculiar behavior is to provide compatibility with
          compiler).  This form of comment cannot occur within a multi-
          token sequence (e.g., HXS ( this is a hex string ) 5 12345 is
          unacceptable).  Lines beginning with an asterisk in the first
          column are output untouched as comment lines.

       ROMID <internal hexROMid>
       xROMID <external hexROMid>
       NAME <label>
       NULLNAME <label>
       xNAME <label>
       sNAME <label> <string>
       tNAME <label> <string>
          These directives generate labels and information needed for
          parsing and decompiling of keywords.  ROMID specifies a ROM ID
          to be used for the name directives.  xROMID specifies a ROM ID
          and indicates that any objects defined in this file should be
          referenced by DOROMP objects.

          The various name directives generate global labels, code, and
          information for the .ext file needed for parsing and
          decompiling.  The differences lie in the creation of the hash
          entry (the name by which the user identifies the object) and
          the label (the name by which the assembler and linker know the
          object):
              NAME - the global label and hash name are the same.
              xNAME - the global label is the hash name with 'x'
          prefixed.
              sNAME - the global label and hash entry are independently
          specified.
              tNAME - specifies that an additional hash name belongs to
          the given label.



                                   -7-











              NULLNAME - no hash entry is provided.

          These words also allow the rompart generator to produce the
          appropriate values for use in ROMPTRs, etc.

          If the xROMID has been given, references to the labels will
          produce DOROMP objects instead of ROM pointers.

       NAMELESS <label>
       LABEL <label>
       LOCALNAME <label>
       LOCALLABEL <label>
          NAMELESS and LABEL simply generate global labels.  LOCALNAME
          and LOCALLABEL generate local labels.

       EXTERNAL <label>
       LOCAL <label>
          These words declare characteristics of the following label:
          EXTERNAL will cause all future references to its label to
          generate DOROMP objects; LOCAL will cause future references to
          its label to be local, not global.

       DEFINE <label1> <label2>
          This allows the substitution of one object label for another.
          It may also be used in LAMs to allow a long identifier in the
          source code, while using a short identifier in the compiled
          output.

       INCLUDE <filename>
          This allows the text of <filename> to be interpolated into the
          source at this line.  After compiling the included file,
          compilation will resume at the start of the next line.
          INCLUDEs may be nested.

       TITLE ...(title text)...
       STITLE ...(subtitle text)...
       EJECT
          These directives generate TITLE, STITLE, and EJECT commands for
          the assembler.  The text for TITLE and STITLE is comprised of
          the remainder of the line.














                                   -8-