home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / lambda / soundpot / p / preprss.lbr / BSLP.DZC / BSLP.DOC
Encoding:
Text File  |  1993-10-25  |  13.4 KB  |  478 lines
  1.    BSLP Version 1.0B                                                Page 1.0
  2.  
  3.    Table of Contents
  4.  
  5.         BSLP: Basic Structured Language Preprocessor......... 1.1
  6.               Functions...................................... 1.1
  7.               Invocation..................................... 1.1
  8.               Defaults....................................... 1.1
  9.               Option (/)..................................... 1.1
  10.               Structure Keywords............................. 1.1
  11.                    PROG / PEND............................... 1.2
  12.                    PROC / ENDP............................... 1.2
  13.                    REPEAT / UNTIL............................ 1.3
  14.                    LOOP / ENDL............................... 1.3
  15.                    WHEN / ELSE / ENDW........................ 1.4
  16.                    UNLESS / ENDU............................. 1.4
  17.                    SWITCH / CASE / BREAK / ENDC.............. 1.5
  18.               Error Messages................................. 2.1
  19.                    Structure Related Error Handling.......... 2.1
  20.                    Structure Related Error Messages.......... 2.1
  21.               Included Files (+-)............................ 3.1
  22.  
  23.       Notice:
  24.              Delimiter conventions used in this documentation
  25.              are:
  26.                  <> denotes required information
  27.                  [] denotes optional information
  28.  
  29.  
  30.                                                               
  31.  
  32.  
  33.  
  34.    BSLP Version 1.0B                                                Page 1.1
  35.  
  36.    BSLP - Basic Structured Language Preprocessor
  37.  
  38.  
  39.  
  40.     Function:
  41.  
  42.         BSLP   translates   source  text  written  in  BSLP  structure
  43.         language to standard BASIC code.  BSLP  is  a  BASIC  language
  44.         version  of  the PPE structure translater. It is slow but very
  45.         usable,  and  has  served  well  as  a  tool   for   prototype
  46.         extensions  to the structure language. BSLP is written in BSLP
  47.         structure language and should be a useful learning tool.
  48.  
  49.  
  50.     Invocation:
  51.  
  52.         Entering 'BSLP' at the DOS prompt  will  envoke  the  compiled
  53.         version  (.EXE)  of  BSLP.  The (.BAS) version will have to be
  54.         run using the interpreter by entering  'BASICA  BSLP'  at  the
  55.         DOS  prompt. BSLP will then prompt for the input file name and
  56.         the  output  file  name.  The  default  for  the  input   file
  57.         extension  is  '.P',  and  the  default  for  the  output file
  58.         extension is '.BAS'. The slash (/) following  the  input  file
  59.         name  will cause all non-referenced line numbers to be deleted
  60.         from the output file (.BAS). This allows  a  smaller  compiled
  61.         (.EXE) program.
  62.  
  63.  
  64.     Hints and Restrictions:
  65.  
  66.         Structure  keywords  are  not  case or position sensitive, and
  67.         they must (except for spaces and tabs) be the first  words  on
  68.         a  line.  Do  NOT use comments on the same line with keywords.
  69.         The vertical bar (|) may be use to provide line  continuation.
  70.         Continued  lines  will  be  appended,  separating  them with a
  71.         colon (:).
  72.  
  73.  
  74.     Structure Keywords:
  75.  
  76.         PROG / PEND
  77.  
  78.         PROC <label> / ENDP
  79.  
  80.         REPEAT / UNTIL <condition>
  81.  
  82.         LOOP [<when/unless> <condition>] / ENDL [<when/unless> <condition>]
  83.  
  84.         WHEN <condition> / ELSE [<when/unless> <condition>] / ENDW
  85.  
  86.         UNLESS <condition> / ENDU
  87.  
  88.         SWITCH <left operand> / CASE <right operand> / BREAK / ENDC
  89.  
  90.  
  91.  
  92.  
  93.  
  94.    BSLP - Basic Structured Language Preprocessor                    Page 1.1
  95.  
  96.  
  97.  
  98.    BSLP Version 1.0B                                                Page 1.2
  99.  
  100.     Structure Keyword Definitions and Usage:
  101.  
  102.     PROG / PEND
  103.  
  104.         'PROG'  identifies  the  main  controlling  procedure   in   a
  105.         program.  'PEND'  identifies the end of the main procedure and
  106.         causes an "END" BASIC keyword to be generated.
  107.  
  108.     Usage:
  109.  
  110.            PROG Calculate               <----------+
  111.                gosub process_one                   | Main
  112.                gosub process_two                   | Procedure
  113.            PEND                         <----------+
  114.  
  115.  
  116.     PROC <label> / ENDP
  117.  
  118.         'PROC' defines the beginning of a procedure  subroutine  using
  119.         a  label  that  may be referenced by name (e.g. 'GOSUB label')
  120.         from any other procedure in the same  program.  'ENDP'  closes
  121.         the  matching  'PROC'  and  terminates  the  procedure  with a
  122.         "RETURN" BASIC keyword. Procedures can not be nested.
  123.  
  124.     Usage:
  125.  
  126.            PROC Test_Out                <----------+
  127.                when status = test                  | Subroutine
  128.                    gosub test_it                   | Procedure
  129.                endw                                |
  130.            ENDP                         <----------+
  131.  
  132.     *Note:
  133.         A label-name immediately followed by a colon (:) may  be  used
  134.         to identify a label without a procedure statement:
  135.  
  136.            e.g...  ERRORTRAP:
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.    Structure Keyword Definitions and Usage                          Page 1.2
  159.  
  160.  
  161.  
  162.    BSLP Version 1.0B                                                Page 1.3
  163.  
  164.     REPEAT / UNTIL <condition>
  165.  
  166.         'REPEAT'  defines the top of a conditional loop structure. The
  167.         matching 'UNTIL' defines the bottom  of  the  loop  where  the
  168.         terminating  condition  is tested. The loop is terminated when
  169.         the condition evaluates true.
  170.  
  171.     Usage:
  172.  
  173.            REPEAT                       <----------+
  174.                index = index + 1                   | Loop
  175.                gosub Index_task                    | Structure
  176.            UNTIL index = task.count     <condition-+
  177.  
  178.  
  179.     LOOP [<when/unless> <condition>] / ENDL [<when/unless> <condition>]
  180.  
  181.         'LOOP' defines the top of a loop structure that will  allow  a
  182.         condition  to  be  tested  at  the  top  and  or at the bottom
  183.         matching 'ENDL'. At  the  top  'WHEN'  evaluates  for  a  true
  184.         condition  to  continue  into the loop structure, and 'UNLESS'
  185.         evaluates for a true condition to branch around the  loop.  At
  186.         the  bottom  'WHEN' evaluates for a true condition to exit the
  187.         loop, and 'UNLESS' evaluates for a true condition to  continue
  188.         the  loop. One condition (top or bottom) is required, but both
  189.         may be use.
  190.  
  191.     Usage:
  192.  
  193.            LOOP                         <----------+
  194.                index = index + 1                   | Loop
  195.                gosub Index_task                    | Structure
  196.            ENDL unless index < task     <condition-+
  197.  
  198.            LOOP when index < task       <condition-+
  199.                index = index + 1                   | Loop
  200.                gosub Index_task                    | Structure
  201.            ENDL                         <----------+
  202.  
  203.            LOOP unless index >= task    <condition-+
  204.                index = index + 1                   | Loop
  205.                gosub Index_task                    | Structure
  206.            ENDL when index >= task      <condition-+
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.    Structure Keyword Definitions and Usage                          Page 1.3
  223.  
  224.  
  225.  
  226.    BSLP Version 1.0B                                                Page 1.4
  227.  
  228.     WHEN <condition> / ELSE [<when/unless> <condition>] / ENDW
  229.  
  230.         'WHEN-ELSE-ENDW'  provides  for  multiple   line   conditional
  231.         constructs,  with  no limit on the range or depth of level and
  232.         no limit on the number of 'ELSE' statements used. 'ELSE  WHEN'
  233.         defines  the  "ELSE-IF"  construct,  and 'ELSE UNLESS' defines
  234.         the  "ELSE-IF-NOT"  construct.  'ENDW'  closes  the   matching
  235.         'WHEN' and terminates to the next outer level of processing.
  236.  
  237.     Usage:
  238.  
  239.            WHEN method = manual          IF
  240.                goSub Keyboard                THEN
  241.            ELSE WHEN method = auto       ELSE IF
  242.                goSub Process                 THEN
  243.            ELSE UNLESS method = null     ELSE IF NOT
  244.                goSub Process_End             THEN
  245.            ELSE                          ELSE
  246.                goSub End_Process             THEN
  247.            ENDW
  248.  
  249.  
  250.     UNLESS <condition> / ENDU
  251.  
  252.         'UNLESS'  defines  a  "DO  WHEN NOT TRUE" construct and 'ENDU'
  253.         closes the matching 'UNLESS' and terminates to the next  outer
  254.         level of processing.
  255.  
  256.     Usage:
  257.  
  258.            UNLESS abort = true           IF NOT
  259.                gosub Continue                THEN
  260.            ENDU
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.    Structure Keyword Definitions and Usage                          Page 1.4
  287.  
  288.  
  289.  
  290.    BSLP Version 1.0B                                                Page 1.5
  291.  
  292.     SWITCH <left operand> / CASE <right operand> / BREAK / ENDC
  293.  
  294.         'SWITCH-CASE-ENDC'   provides   an   "ON   CONDITION  PROCESS"
  295.         construct. 'SWITCH' defines the operand on the  left  side  of
  296.         the  equal  sign  and  'CASE' defines the operand on the right
  297.         side. There is no limit on the  number  of  'CASE'  statements
  298.         within   a  procedure.  When  a  'SWITCH=CASE'  is  true,  the
  299.         instructions following that 'CASE' are processed,  and  unless
  300.         a  'BREAK' statement is used, processing will continue through
  301.         to the next  'CASE'  statement.  The  'BREAK'  statement  will
  302.         cause  a branch to the next 'ENDC' statement. The 'BREAK' will
  303.         be  processed  only  if  a  'SWITCH=CASE'  is  true.  When   a
  304.         'SWITCH=CASE'  evaluates  false, processing is branched to the
  305.         next 'CASE' statement. 'SWITCH' statements can  be  nested  to
  306.         ten  (10)  levels.  'ENDC'  closes  the  matching 'SWITCH' and
  307.         terminates to the next outer level of processing.
  308.  
  309.     Usage:
  310.  
  311.            SWITCH method$(method)
  312.            CASE "+"
  313.                answer = answer + number
  314.                BREAK
  315.            CASE "-"
  316.                answer = answer - number
  317.                BREAK
  318.            CASE "*"
  319.                answer = answer * number
  320.                BREAK
  321.            CASE "/"
  322.                when number <> 0
  323.                    answer = answer / number
  324.                else
  325.                    answer = 0
  326.                endw
  327.            ENDC
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.    Structure Keyword Definitions and Usage                          Page 1.5
  351.  
  352.  
  353.  
  354.    BSLP Version 1.0B                                                Page 2.1
  355.  
  356.     Structure Related Error Handling:
  357.  
  358.         When   a   structure   error   is    encountered,    a    file
  359.         (<program-name>.E)  is  generated,  showing the exact location
  360.         of the error. All structure errors are resolved at the end  of
  361.         each  procedure,  or 'ENDP'. When there are errors immediately
  362.         following an 'ENDP' statement,  the  procedure  preceding  the
  363.         'ENDP' statement will be the source of the errors.
  364.  
  365.     Structure Related Error Messages:
  366.  
  367.         Structure  related  error messages are displayed with a 'ERR#'
  368.         and the error count. These errors  will  be  recorded  in  the
  369.         error file (<program-name>.E).
  370.  
  371.         Structure  related  error  messages  are self explanatory, the
  372.         following are some typical examples:
  373.  
  374.            ERR#1 MISSING (endl) PROC <BEGIN>
  375.                      (A 'LOOP' structure not closed in procedure BEGIN)
  376.            ERR#1 MISSING (switch) PROC <Select>
  377.                      (A 'CASE' or 'BREAK' or 'ENDC' without an  opening
  378.                       'SWITCH' in procedure Select.)
  379.            ERR#1 MISSING (endc) PROC <>
  380.                      (A 'CASE' structure not closed in main procedure.)
  381.            ERR#1 MISSING (include 'filename')
  382.                      (Unable to find an included file.)
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.    Errors                                                           Page 2.1
  415.  
  416.  
  417.  
  418.    BSLP Version 1.0B                                                Page 3.1
  419.  
  420.     Included Files:
  421.  
  422.         There are two methods  to  include  additional  files  into  a
  423.         program source file for processing:
  424.  
  425.     Immediate:
  426.                +filename.ext
  427.  
  428.         The  leading  plus  (+)  will  cause  a  file  to  be included
  429.         immediately into the program source file  and  processed.  The
  430.         same  file  or  any  number  of  files  may  be  included  and
  431.         processed.
  432.  
  433.     Stacked:
  434.                -filename.ext
  435.  
  436.         The leading dash (-) will cause a file name to be  stored  and
  437.         the  file  will  be  included  only one time at the end of the
  438.         main  program  source  file.  The  same  file  name   may   be
  439.         referenced  many  times,  with  the  file  included  into  the
  440.         program source file only one time and processed. The  internal
  441.         file name storage will hold up to fifty (50) file names.
  442.  
  443.     *Note:
  444.  
  445.         Nested  includes  may be processed up to five (5) levels deep.
  446.         Nesting is limited by the number of files that can be open  at
  447.         the same time. No line numbered include files allowed.
  448.  
  449.  
  450.  
  451.     WARNING:
  452.  
  453.         A  recursive include will blow the internal stack. No check is
  454.         made for recursive includes.
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.    Including Files                                                  Page 3.1
  479.