src/liburforth/urforth.h

   1 // and now for something completely different...
   2 // UrAsm built-in Forth Engine!
   3 // GPLv3 ONLY
   4 #ifndef URFORTH_HEADER
   5 #define URFORTH_HEADER
   6
   7 #include <stddef.h>
   8 #include <stdint.h>
   9
  10
  11 // should abort; defined by the main app
  12 extern void ufoFatalError (void) __attribute__((noreturn));
  13
  14 // returns malloced string
  15 extern char *ufoCreateIncludeName (const char *fname, int assystem, const char *lastIncPath);
  16
  17 // required for UrAsm
  18 void ufoClearIncludePath (void);
  19
  20 // can be called by the main app
  21 void ufoFatal (const char *fmt, ...) __attribute__((noreturn)) __attribute__((format(printf, 1, 2)));
  22
  23 // called after main initialisation.
  24 void ufoSetUserPostInit (void (*cb) (void));
  25
  26 // will be called automatically if necessary.
  27 // it is safe to call it several times.
  28 void ufoInit (void);
  29
  30 int ufoIsInited (void);
  31
  32 // this will NOT be called automatically!
  33 // WARNING! reiniting after calling this may, or may not work.
  34 void ufoDeinit (void);
  35
  36 // call this, and VM will abort soon.
  37 // used for Ctrl+C handler.
  38 void ufoSetUserAbort (void);
  39
  40
  41 // ////////////////////////////////////////////////////////////////////////// //
  42 // conditional defines (case-insensitive)
  43 //
  44
  45 int ufoHasCondDefine (const char *name);
  46 void ufoCondDefine (const char *name);
  47 void ufoCondUndef (const char *name);
  48
  49
  50 // ////////////////////////////////////////////////////////////////////////// //
  51 // extension API
  52 //
  53
  54 // if set, this will be used when we are out of include files. intended for UrAsm.
  55 // return 0 if there is no more lines, otherwise the string should be copied
  56 // to buffer, `*fname` and `*fline` should be properly set.
  57 // max line length is 510 bytes for now.
  58 extern int (*ufoFileReadLine) (void *buf, size_t bufsize, const char **fname, int *fline);
  59
  60 // get "FORTH" vocid.
  61 uint32_t ufoGetForthVocId (void);
  62
  63
  64 // ////////////////////////////////////////////////////////////////////////// //
  65 // register new word
  66 //
  67
  68 // possible word flags
  69 #define UFW_FLAG_IMMEDIATE  (1u<<16)
  70 #define UFW_FLAG_SMUDGE     (1u<<17)
  71 #define UFW_FLAG_NORETURN   (1u<<18)
  72 #define UFW_FLAG_HIDDEN     (1u<<19)
  73 #define UFW_FLAG_CBLOCK     (1u<<20)
  74 #define UFW_FLAG_VOCAB      (1u<<21)
  75 #define UFW_FLAG_SCOLON     (1u<<22)
  76 #define UFW_FLAG_PROTECTED  (1u<<23)
  77
  78 #define UFW_WARG_MASK    ((uint32_t)0xff00U)
  79
  80 // possible word arg types
  81 #define UFW_WARG_NONE    (0u<<8)
  82 #define UFW_WARG_BRANCH  (1u<<8)
  83 #define UFW_WARG_LIT     (2u<<8)
  84 #define UFW_WARG_C4STRZ  (3u<<8)
  85 #define UFW_WARG_CFA     (4u<<8)
  86 #define UFW_WARG_CBLOCK  (5u<<8)
  87 #define UFW_WARG_VOCID   (6u<<8)
  88 #define UFW_WARG_C1STRZ  (7u<<8)
  89
  90 typedef void (*ufoNativeCFA) (uint32_t pfa);
  91
  92
  93 // create new vocabulary. return vocid.
  94 uint32_t ufoCreateVoc (const char *wname, uint32_t parentvocid, uint32_t flags);
  95 // set "CURRENT" and "CONTEXT" to this vocavulary.
  96 void ufoVocSetOnlyDefs (uint32_t vocid);
  97
  98 // `flags` is ORed args and flags
  99 // returns CFA of the new word
 100 uint32_t ufoRegisterWord (const char *wname, ufoNativeCFA cfa, uint32_t flags);
 101
 102 void ufoRegisterConstant (const char *wname, uint32_t value, uint32_t flags);
 103 // the following words returs value address
 104 uint32_t ufoRegisterVariable (const char *wname, uint32_t value, uint32_t flags);
 105 uint32_t ufoRegisterValue (const char *wname, uint32_t value, uint32_t flags);
 106 uint32_t ufoRegisterDefer (const char *wname, uint32_t value, uint32_t flags);
 107
 108 // check if we have the corresponding word.
 109 // return CFA suitable for executing, or 0.
 110 uint32_t ufoFindWordInVocabulary (const char *wname, uint32_t vocid);
 111
 112 uint32_t ufoGetIP (void);
 113 void ufoSetIP (uint32_t newip);
 114
 115 // get and set "STATE"
 116 int ufoIsExecuting (void);
 117 int ufoIsCompiling (void);
 118 void ufoSetExecuting (void);
 119 void ufoSetCompiling (void);
 120
 121 uint32_t ufoGetHere ();
 122 uint32_t ufoGetPad ();
 123
 124 uint8_t ufoTIBPeekCh (uint32_t ofs);
 125 uint8_t ufoTIBGetCh (void);
 126 void ufoTIBSkipCh (void);
 127 // returns 0 on EOF
 128 int ufoTIBSRefill (int allowCrossIncludes);
 129
 130 // ( -- addr count TRUE / FALSE )
 131 // does base TIB parsing; never copies anything.
 132 // as our reader is line-based, returns FALSE on EOL.
 133 // EOL is detected after skipping leading delimiters.
 134 // passing -1 as delimiter skips the whole line, and always returns FALSE.
 135 // trailing delimiter is always skipped.
 136 // result is on the data stack.
 137 void ufoCallParseIntr (uint32_t delim, int skipLeading);
 138 // ( -- addr count )
 139 // parse with leading blanks skipping. doesn't copy anything.
 140 // return empty string on EOL.
 141 void ufoCallParseName (void);
 142 // ( delim -- addr count TRUE / FALSE )
 143 // parse without skipping delimiters; never copies anything.
 144 // as our reader is line-based, returns FALSE on EOL.
 145 // passing 0 as delimiter skips the whole line, and always returns FALSE.
 146 // trailing delimiter is always skipped.
 147 void ufoCallParse (uint32_t delim);
 148 // utils
 149 void ufoCallParseSkipBlanks (void);
 150 void ufoCallParseSkipComments (void); // multiline
 151 void ufoCallParseSkipLineComments (void); // will not refill
 152 void ufoCallParseSkipLine (void); // to the end of line; doesn't refill
 153
 154 // convert number from addrl+1
 155 // returns address of the first inconvertible char
 156 // (BASED-NUMBER) ( -- num TRUE / FALSE )
 157 void ufoCallBasedNumber (uint32_t addr, uint32_t count, int allowSign, int base);
 158
 159
 160 uint32_t ufoPeekData (void);
 161 uint32_t ufoPopData (void);
 162 void ufoPushData (uint32_t value);
 163 // WARNING! *ALWAYS* use this to push boolean values!
 164 //          this is because "TRUE" value is not always `1`.
 165 void ufoPushBoolData (int val);
 166
 167 uint32_t ufoPeekRet (void);
 168 uint32_t ufoPopRet (void);
 169 void ufoPushRet (uint32_t value);
 170 // WARNING! *ALWAYS* use this to push boolean values!
 171 //          this is because "TRUE" value is not always `1`.
 172 void ufoPushBoolRet (int val);
 173
 174 uint8_t ufoPeekByte (uint32_t addr);
 175 uint16_t ufoPeekWord (uint32_t addr);
 176 uint32_t ufoPeekCell (uint32_t addr);
 177
 178 void ufoPokeByte (uint32_t addr, uint32_t value);
 179 void ufoPokeWord (uint32_t addr, uint32_t value);
 180 void ufoPokeCell (uint32_t addr, uint32_t value);
 181
 182 // dictionary emitters
 183 void ufoEmitByte (uint32_t value);
 184 void ufoEmitWord (uint32_t value);
 185 void ufoEmitCell (uint32_t value);
 186
 187 // include and interpret the given file.
 188 // cannot be called recursively!
 189 // doesn't reset internal state.
 190 // WARNING! returns when include stack is empty,
 191 //          not when the file ends.
 192 void ufoRunFile (const char *fname);
 193
 194 // run word, return after it returned.
 195 // cannot be called recursively!
 196 // doesn't reset internal state.
 197 // CFA is from `ufoFindWordInVocabulary()`.
 198 void ufoRunWord (uint32_t cfa);
 199
 200 // run default interpret loop.
 201 void ufoRunInterpretLoop (void);
 202
 203 // run word in "MACRO" mode.
 204 // in this mode, includes are ignored, and current line
 205 // will be set with `ufoFileReadLine()`.
 206 // CFA is from `ufoFindWordInVocabulary()`.
 207 void ufoRunMacroWord (uint32_t cfa);
 208
 209 // check if we are currently in "MACRO" mode.
 210 // should be called from registered words.
 211 int ufoIsInMacroMode (void);
 212
 213 // can be called to stop execution started with `ufoRunInterpretLoop()`.
 214 void ufoFinishVM (void);
 215
 216 // check if VM was exited due to `ufoFinishVM()`
 217 int ufoWasVMFinished (void);
 218
 219
 220 #endif