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 // the arg is amount of bytes to skip (not including the counter itself)
  90 // the following inline data cannot (and shouldn't) be decompiled
  91 #define UFW_WARG_DATASKIP (8u<<8)
  92
  93
  94 typedef void (*ufoNativeCFA) (uint32_t pfa);
  95
  96
  97 // create new vocabulary. return vocid.
  98 uint32_t ufoCreateVoc (const char *wname, uint32_t parentvocid, uint32_t flags);
  99 // set "CURRENT" and "CONTEXT" to this vocavulary.
 100 void ufoVocSetOnlyDefs (uint32_t vocid);
 101
 102 // `flags` is ORed args and flags
 103 // returns CFA of the new word
 104 uint32_t ufoRegisterWord (const char *wname, ufoNativeCFA cfa, uint32_t flags);
 105
 106 void ufoRegisterConstant (const char *wname, uint32_t value, uint32_t flags);
 107 // the following words returs value address
 108 uint32_t ufoRegisterVariable (const char *wname, uint32_t value, uint32_t flags);
 109 uint32_t ufoRegisterValue (const char *wname, uint32_t value, uint32_t flags);
 110 uint32_t ufoRegisterDefer (const char *wname, uint32_t value, uint32_t flags);
 111
 112 // check if we have the corresponding word.
 113 // return CFA suitable for executing, or 0.
 114 uint32_t ufoFindWordInVocabulary (const char *wname, uint32_t vocid);
 115
 116 uint32_t ufoGetIP (void);
 117 void ufoSetIP (uint32_t newip);
 118
 119 // get and set "STATE"
 120 int ufoIsExecuting (void);
 121 int ufoIsCompiling (void);
 122 void ufoSetExecuting (void);
 123 void ufoSetCompiling (void);
 124
 125 uint32_t ufoGetHere ();
 126 uint32_t ufoGetPad ();
 127
 128 uint8_t ufoTIBPeekCh (uint32_t ofs);
 129 uint8_t ufoTIBGetCh (void);
 130 void ufoTIBSkipCh (void);
 131 // returns 0 on EOF
 132 int ufoTIBSRefill (int allowCrossIncludes);
 133
 134 // ( -- addr count TRUE / FALSE )
 135 // does base TIB parsing; never copies anything.
 136 // as our reader is line-based, returns FALSE on EOL.
 137 // EOL is detected after skipping leading delimiters.
 138 // passing -1 as delimiter skips the whole line, and always returns FALSE.
 139 // trailing delimiter is always skipped.
 140 // result is on the data stack.
 141 void ufoCallParseIntr (uint32_t delim, int skipLeading);
 142 // ( -- addr count )
 143 // parse with leading blanks skipping. doesn't copy anything.
 144 // return empty string on EOL.
 145 void ufoCallParseName (void);
 146 // ( delim -- addr count TRUE / FALSE )
 147 // parse without skipping delimiters; never copies anything.
 148 // as our reader is line-based, returns FALSE on EOL.
 149 // passing 0 as delimiter skips the whole line, and always returns FALSE.
 150 // trailing delimiter is always skipped.
 151 void ufoCallParse (uint32_t delim);
 152 // utils
 153 void ufoCallParseSkipBlanks (void);
 154 void ufoCallParseSkipComments (void); // multiline
 155 void ufoCallParseSkipLineComments (void); // will not refill
 156 void ufoCallParseSkipLine (void); // to the end of line; doesn't refill
 157
 158 // convert number from addrl+1
 159 // returns address of the first inconvertible char
 160 // (BASED-NUMBER) ( -- num TRUE / FALSE )
 161 void ufoCallBasedNumber (uint32_t addr, uint32_t count, int allowSign, int base);
 162
 163
 164 uint32_t ufoPeekData (void);
 165 uint32_t ufoPopData (void);
 166 void ufoPushData (uint32_t value);
 167 // WARNING! *ALWAYS* use this to push boolean values!
 168 //          this is because "TRUE" value is not always `1`.
 169 void ufoPushBoolData (int val);
 170
 171 uint32_t ufoPeekRet (void);
 172 uint32_t ufoPopRet (void);
 173 void ufoPushRet (uint32_t value);
 174 // WARNING! *ALWAYS* use this to push boolean values!
 175 //          this is because "TRUE" value is not always `1`.
 176 void ufoPushBoolRet (int val);
 177
 178 uint8_t ufoPeekByte (uint32_t addr);
 179 uint16_t ufoPeekWord (uint32_t addr);
 180 uint32_t ufoPeekCell (uint32_t addr);
 181
 182 void ufoPokeByte (uint32_t addr, uint32_t value);
 183 void ufoPokeWord (uint32_t addr, uint32_t value);
 184 void ufoPokeCell (uint32_t addr, uint32_t value);
 185
 186 // dictionary emitters
 187 void ufoEmitByte (uint32_t value);
 188 void ufoEmitWord (uint32_t value);
 189 void ufoEmitCell (uint32_t value);
 190
 191 // include and interpret the given file.
 192 // cannot be called recursively!
 193 // doesn't reset internal state.
 194 // WARNING! returns when include stack is empty,
 195 //          not when the file ends.
 196 void ufoRunFile (const char *fname);
 197
 198 // run word, return after it returned.
 199 // cannot be called recursively!
 200 // doesn't reset internal state.
 201 // CFA is from `ufoFindWordInVocabulary()`.
 202 void ufoRunWord (uint32_t cfa);
 203
 204 // run default interpret loop.
 205 void ufoRunInterpretLoop (void);
 206
 207 // run word in "MACRO" mode.
 208 // in this mode, includes are ignored, and current line
 209 // will be set with `ufoFileReadLine()`.
 210 // CFA is from `ufoFindWordInVocabulary()`.
 211 void ufoRunMacroWord (uint32_t cfa);
 212
 213 // check if we are currently in "MACRO" mode.
 214 // should be called from registered words.
 215 int ufoIsInMacroMode (void);
 216
 217 // can be called to stop execution started with `ufoRunInterpretLoop()`.
 218 void ufoFinishVM (void);
 219
 220 // check if VM was exited due to `ufoFinishVM()`
 221 int ufoWasVMFinished (void);
 222
 223
 224 #endif