git.gag.com Git - debian/pforth/blob - docs/pfmanual.txt

   1 UNFINISHED\r
   2 \r
   3 Manual for pForth - a Portable Forth\r
   4 \r
   5 The best reference for pForth is an ANSI Forth manual. pForth\r
   6 is built on an ANSI model.  There are, however, some non-standard\r
   7 words which are documented here:\r
   8 \r
   9 {  ( i*x -- , declare local variables )\r
  10         Local variables are only usable within a colon definition.\r
  11         They are taken from the stack as they are defined.\r
  12         They are self fetching.  Use -> to set them.\r
  13         They help you avoid excessive stack dancing. \r
  14         Here is an example:\r
  15 \r
  16         : SUMSQ { aa bb -- }\r
  17                 aa aa *\r
  18                 bb bb * +\r
  19         ;\r
  20         3 4 SUMSQ . ( prints 25 )\r
  21 \r
  22         Here is an example of using a temporary variable:\r
  23 \r
  24         : SUMN { num | sum -- , sum up integers the dumb way }\r
  25             0 -> sum  \ uses -> to set local variable\r
  26             num 0\r
  27             DO  i sum +\r
  28                 -> sum   \ write current TOS to sum\r
  29             LOOP\r
  30             sum\r
  31         ;\r
  32 \r
  33 :STRUCT  ( <name> -- , defines a 'C' like structure )\r
  34         See end of "c_struct.fth" for an example.\r
  35 \r
  36 ANEW  ( <name> -- )\r
  37         Forgets NAME if it is already defined.\r
  38         Then defines NAME.  Put at beginning of file\r
  39         so that file can be INCLUDEd multiple times\r
  40         without redefining the contents.\r
  41 \r
  42 CASE OF ENDOF ENDCASE in the typical fashion. See "case.fth"\r
  43  \r
  44 CHOOSE ( range -- random , pick random number, 0...range-1 )\r
  45 \r
  46 IF ELSE THEN DO LOOP etc. can be used outside colon definitions!\r
  47 \r
  48 IF.FORGOTTEN  ( <name> -- , executes NAME if forgotten )\r
  49         Put this at the end of a file to automatically\r
  50         call your cleanup word if the code is forgotten.\r
  51 \r
  52 INCLUDE   ( <filename> -- , interpret from file )\r
  53         Write your Forth programs in a file then load them\r
  54         using INCLUDE.\r
  55         \r
  56                 INCLUDE   myprog.fth\r
  57                 \r
  58 INCLUDE?   ( <name> <filename> -- , interpret from file if needed )\r
  59         INCLUDE the given file only if the named word is undefined.\r
  60         The name should be of a Forth word defined in the file.\r
  61         See "load_pforth.fth" for an example.\r
  62         \r
  63                 INCLUDE?  DO.MY.PROG   myprog.fth\r
  64                 \r
  65 MAP   ( -- , dumps info about dictionary )\r
  66 \r
  67 Other words\r
  68 \r
  69 FP.INIT\r
  70 FP.TERM\r
  71 F>S\r
  72 S>F\r
  73 EXISTS?\r
  74 STRINGS=     \r
  75 \r
  76 S@\r
  77 S!\r
  78 ;STRUCT\r
  79 :STRUCT  \r
  80 STRUCT\r
  81 ULONG\r
  82 RPTR\r
  83 APTR\r
  84 FLPT\r
  85 USHORT  \r
  86 UBYTE\r
  87 LONG\r
  88 SHORT\r
  89 BYTE\r
  90 BYTES\r
  91 SIZEOF()        \r
  92 OB.STATS?\r
  93 OB.STATS\r
  94 OB.FINDIT       \r
  95 OB.MEMBER\r
  96 }UNION\r
  97 }UNION{\r
  98 UNION{\r
  99 OB.MAKE.MEMBER  \r
 100 MAP\r
 101 .HEX    \r
 102 .DEC\r
 103 .BIN\r
 104 ARRAY\r
 105 WARRAY\r
 106 BARRAY\r
 107 -2SORT  \r
 108 2SORT\r
 109 WCHOOSE\r
 110 CHOOSE\r
 111 RANDOM\r
 112 RAND-SEED       \r
 113 MSEC\r
 114 MSEC-DELAY\r
 115 VALUE\r
 116 ->      \r
 117 TO\r
 118 \r
 119 -- strings --\r
 120 TEXTROM\r
 121 $ROM\r
 122 $APPEND.CHAR\r
 123 INDEX\r
 124 $MATCH?\r
 125 TEXT=?\r
 126 TEXT=   \r
 127 $=\r
 128 COMPARE\r
 129 $ARRAY\r
 130 \r
 131 -- case --\r
 132 ENDCASE ENDOF   RANGEOF (RANGEOF?)      OF      \r
 133 ?OF     CASE    OF-DEPTH        CASE-DEPTH      \r
 134 \r
 135 TOLOWER\r
 136 @EXECUTE\r
 137 >NAME   \r
 138 CLOSEST-XT\r
 139 CLOSEST-NFA\r
 140 TAB     \r
 141 TAB-WIDTH\r
 142 .HX\r
 143 $\r
 144 CR?\r
 145 #COLS\r
 146 ?PAUSE\r
 147 ABORT" \r
 148 WARNING"\r
 149 CELL*\r
 150 <<      \r
 151 >>\r
 152 \r
 153 TASK-MISC1.FTH  .R      .       (.)     \r
 154 (NUMBER?)       \r
 155 ((NUMBER?))     NUM_TYPE_DOUBLE NUM_TYPE_SINGLE \r
 156 NUM_TYPE_BAD    >NUMBER DIGIT\r
 157  \r
 158 ANEW    FORGET  [FORGET]        IF.FORGOTTEN   \r
 159 \r
 160 SAVE-FORTH      \r
 161 INCLUDE?\r
 162 RI\r
 163 INCLUDE     \r
 164 $INCLUDE\r
 165 $APPEND\r
 166 LWORD\r
 167 PARSE\r
 168 PARSE-WORD      \r
 169 PLACE\r
 170 \r
 171 WHAT'S\r
 172 IS\r
 173 DEFER\r
 174 \r
 175 >NEWLINE        \r
 176 0SP\r
 177 SPACES\r
 178 SPACE\r
 179 RECURSE\r
 180 UNLOOP\r
 181 \r
 182 -- user stack --\r
 183 0USP    \r
 184 US@     US>     >US     USTACK  0STACKP STACK@  \r
 185 STACK>  >STACK  :STACK\r
 186 \r
 187 -- address storage and translation --\r
 188 A,      A@      A!      \r
 189 IF.REL->USE     IF.USE->REL\r
 190 X!      X@      \r
 191 >ABS    >REL    REL->USE        USE->REL        \r
 192 BODY>   >BODY   N>LINK  CODE>   >CODE   NAME>   \r
 193 NAMEBASE+       CODEBASE        NAMEBASE        \r
 194 N>NEXTLINK      >NAME\r
 195 PREVNAME        NAME>   \r
 196 \r
 197 \r
 198 ID.     \r
 199 \r
 200 OFF     ON\r
 201 TRACE-STACK\r
 202 TRACE-LEVEL     \r
 203 TRACE-FLAGS\r
 204 \r
 205 HEADERS-BASE    \r
 206 HEADERS-PTR\r
 207 ECHO\r
 208 CODE-BASE       \r
 209 \r
 210 POP-SOURCE-ID\r
 211 PUSH-SOURCE-ID\r
 212 SOURCE-ID       \r
 213 SET-SOURCE\r
 214 SOURCE\r
 215 \r
 216 LOADSYS\r
 217 \r
 218 FLUSHEMIT       \r
 219 FINDNFA\r
 220 BYE\r
 221 BODY_OFFSET\r
 222 BAIL    \r
 223 ARSHIFT\r