1FTH(1) General Commands Manual FTH(1) 2 3NNAAMMEE 4 fftthh - Forth script and extension language 5 6SSYYNNOOPPSSIISS 7 fftthh [--DDddQQqqrrvv] [--CC _s_o_-_l_i_b_-_p_a_t_h] [--EEee _p_a_t_t_e_r_n] [--FF _f_s] [--ff _i_n_i_t_-_f_i_l_e] 8 [--II _f_s_-_p_a_t_h] [--SS "_l_i_b _i_n_i_t"] [--ss _f_i_l_e] [_f_i_l_e _._._.] 9 fftthh [--aall] [--ii [_s_u_f_f_i_x]] [--nn | --pp] --ee _p_a_t_t_e_r_n [_f_i_l_e | _-] 10 fftthh [--VV] 11 12DDEESSCCRRIIPPTTIIOONN 13 This is the manual page for the interactive and script processing Forth 14 interpreter fftthh. It is based on _F_i_c_l. This manual page provides 15 information for running fftthh in a UNIX command line environment. See 16 libfth(3) for Forth as an extension language. 17 18 AArrgguummeenntt lliisstt pprroocceessssiinngg 19 --aa Split every line to array *farray* before evaluation. The split 20 string is field separator *fs*. Used with --nn or --pp option. 21 --CC _p_a_t_h 22 Prepend _p_a_t_h to *load-lib-path*, multiple calls possible. 23 --DD Show backtrace and exit with return code 1 if an exception was found 24 evaluating the initialization file, running a script, loading 25 additional source files, or evaluating strings from the command 26 line. 27 --dd Set global variable *fth-debug* to #t. 28 --EE _p_a_t_t_e_r_n 29 --ee _p_a_t_t_e_r_n 30 Evaluate _p_a_t_t_e_r_n. After evaluation, if options --ee was specified, 31 exit, if option --EE was specified, start read-eval-print-loop. 32 Multiple calls possible. If --DD was given and evaluation was not 33 successful, show backtrace and exit with return code 1, otherwise 34 exit with return code 0. The last or only --ee _p_a_t_t_e_r_n can be 35 considered between 36 lambda: <{}> pattern ; 37 and is in compile state! If multiple --ee _p_a_t_t_e_r_n appear, all but the 38 last are in interpret state. 39 --FF _f_s 40 Set global variable *fs* to field separator _f_s. 41 --ff _f_i_l_e 42 Take initialization file _f_i_l_e instead of _~_/_._f_t_h_r_c. Use --QQ to 43 prevent loading initialization files. 44 --II _p_a_t_h 45 Prepend _p_a_t_h to *load-path*, multiple calls possible. 46 --ii [_s_u_f_f_i_x] 47 The --ee _p_a_t_t_e_r_n will be applied to files or stdin. If _s_u_f_f_i_x is 48 specified, a backup file will be created with that suffix. 49 --ll Remove line ending \n when used with --nn or --pp option. 50 --nn Suppress output of current *line*. If not in-place --ii, start an 51 implicit loop. 52 --pp Print current *line* to stdout. If not in-place --ii, start an 53 implicit loop. 54 --QQ Neither load the system wide nor the local initialization file. 55 --qq Do not print banner and set global variable *fth-verbose* to #f. 56 --rr Start a conventional Forth-like session with data stack left 57 untouched after pressing <Return>. Normally the data stack is 58 printed and cleared but --rr changes this behavior to something like a 59 _r_e_a_d_-_e_v_a_l_-_l_o_o_p instead of a _r_e_a_d_-_e_v_a_l_-_p_r_i_n_t_-_l_o_o_p. If --DD was given 60 and evaluation was not successful, show backtrace and exit with 61 return code 1, otherwise exit with return code 0. 62 --SS "_l_i_b _i_n_i_t" 63 Load C extension library _l_i_b and call the initialization function 64 _i_n_i_t. _l_i_b and _i_n_i_t must be enclosed in quotations 65 -S "dbm Init_dbm" 66 Multiple calls possible. 67 --ss _f_i_l_e 68 Evaluate _f_i_l_e as a Forth script and exit. It doesn't read the 69 initialization file. The global Forth variables *argc* and *argv* 70 are set and filled with the count and command line options appearing 71 after --ss _f_i_l_e. This must be the last option given to the fftthh 72 interpreter. Options after that are taken as script options. If --DD 73 was given and evaluation was not successful, show a backtrace and 74 exit with return code 1, otherwise exit with return code 0. 75 --VV Display version info and exit. 76 --vv Set global variable *fth-verbose* to #t (default). 77 78 FFoorrtthh vvaarriiaabblleess 79 *0* Entire current input line, read-only. 80 *1* ... *9* 81 Corresponding single element of *farray*, read-only. 82 .*0* 83 Print entire current input line. 84 .*1* ... .*9* 85 Print corresponding single element of *farray* with *ofs* attached, 86 normally a single space. 87 *argc* 88 Number of arguments in *argv*. 89 *argv* 90 Array of command line arguments. Return array of all exceptions. 91 *farray* 92 Auto-splitted array of strings of current line. 93 *features* 94 Return array of all features. 95 *filename* 96 Current filename. 97 *fname* 98 Current in-place filename. 99 *fnr* 100 Input record number in current file. 101 *fs* 102 Input field separator, default one space. 103 *fth-debug* 104 If #t, show more diagnostic output. 105 *fth-verbose* 106 If #t, show more output. 107 *key* 108 Hold current value in a map--end-map loop. 109 *last-exception* 110 Hold last raised exception. 111 *line* 112 Current in-place processing line. 113 *lineno* 114 Current line number. 115 *load-lib-path* 116 Array of directories where fftthh searchs for _*_._s_o C-library files. 117 *load-path* 118 Array of directories where fftthh searchs for _*_._f_s script files. 119 *loaded-files* 120 Array of already loaded files. 121 *nr* 122 Input record number over all files. 123 *ofs* 124 Output field separator, default one space. 125 *re* 126 Array with last regexp match. 127 *re-syntax-options* 128 Regexp syntax option, default REG_EXTENDED. 129 *re0* 130 Last entire match of regexp search, read-only. 131 *re1* ... *re9* 132 Last subexpression match of regexp search, read-only. 133 optarg 134 Getopt variable with current option argument string, default #f. 135 opterr 136 If #t, getopt print error message for wrong or missing arguments; 137 default #t. 138 optind 139 Getopt variable with index of next element in *argv* array, default 140 1. 141 optopt 142 Getopt variable with last known option, default #f. 143 144 HHooookk vvaarriiaabblleess 145 fftthh calls five hooks if they are not empty: before and after loading 146 source files and in interactive mode before starting and after ending the 147 repl as well as every time before showing the prompt. 148 bbeeffoorree--llooaadd--hhooookk ( filename -- f ) 149 Called before loading _f_i_l_e_n_a_m_e. If hook returns #f, _f_i_l_e_n_a_m_e won't 150 be loaded. 151 before-load-hook lambda: <{ fname -- f }> 152 "\\ loading %s\n" #( fname ) fth-print 153 #t 154 ; add-hook! 155 aafftteerr--llooaadd--hhooookk ( filename -- ) 156 Called after loading _f_i_l_e_n_a_m_e and updating global variable 157 *loaded-files*. 158 after-load-hook lambda: <{ fname -- }> 159 "\\ %s loaded\n" #( fname ) fth-print 160 ; add-hook! 161 bbeeffoorree--rreeppll--hhooookk ( -- ) 162 Called after initializing the tecla(7) command-line editing library 163 but before starting the repl. A predefined hook showing some help 164 lines can be replaced by your own message. 165 before-repl-hook reset-hook! 166 before-repl-hook lambda: <{ -- }> 167 ." \" cr 168 ." \ Starting FTH on " date .string ." !" cr 169 ." \" cr 170 ; add-hook! 171 aafftteerr--rreeppll--hhooookk ( history-file -- ) 172 Called after leaving the repl and writing the history file but 173 before leaving the program. Its only argument is the history 174 filename. You may manipulate the history data entries. One history 175 entry consists of two lines: a time stamp preceded by a Forth 176 comment backslash and the actual history line. 177 after-repl-hook lambda: <{ history -- }> 178 \ Remove duplicates from history file. 179 history readlines array-reverse! { hary } 180 #() "" "" { nhary hline tline } 181 hary array-length 0 ?do 182 hary i array-ref to hline 183 hary i 1+ array-ref to tline 184 nhary hline array-member? unless 185 nhary hline array-unshift 186 tline array-unshift drop 187 then 188 2 +loop 189 history nhary writelines 190 ; add-hook! 191 bbeeffoorree--pprroommpptt--hhooookk ( prompt pos -- new-prompt ) 192 Called before printing a new prompt to customize the output of it. 193 _p_r_o_m_p_t is the old prompt and _p_o_s the current history position. The 194 return value, preferable a string, is the _p_r_o_m_p_t argument for the 195 next hook procedure if any. 196 before-prompt-hook lambda: <{ prompt pos -- new-prompt }> 197 "fth (%d) ok " #( pos ) string-format 198 ; add-hook! 199 Or with standout and bold mode, see gl_prompt_style(3) and 200 _*_p_r_o_m_p_t_s_t_y_l_e_* below: 201 #t to *promptstyle* 202 before-prompt-hook lambda: <{ prompt pos -- new-prompt }> 203 "%%Sfth (%d)%%s %%Bok%%b " #( pos ) string-format 204 ; add-hook! 205 206 TThhee ccoommmmaanndd--lliinnee eeddiittoorr 207 Command-line editing similar to tcsh(1) is handled by the tecla(7) 208 library if installed. Predefined key bindings exist for those similar to 209 vi(1) and emacs(1). The default editing mode is emacs-mode. You can 210 switch from emacs-mode to vi-mode via MM--^^VV and from vi-mode to emacs-mode 211 via MM--^^EE. To start in vi-mode, put a line like 212 edit-mode vi 213 in your _~_/_._t_e_c_l_a_r_c file. A history of the last command-lines can be 214 listed with ^^XXhh, the last 10 history entries can be listed with MM--1100^^XXhh. 215 The Tab-key or ^^II initiates word completion. If the Forth dictionary has 216 more than one entry starting with characters before the cursor, show all, 217 if only one definition exists, complete it and add a space after the 218 completed word. If the Forth dictionary has no entries starting with the 219 characters before the cursor, try filename completion. For complete key 220 listings and function descriptions, see tecla(7). 221 222 If the first character of the command-line is an exclamation point !!, try 223 history expansion similar to csh(1). 224 225 !123 repeat event 123 226 !-123 repeat 123rd last event 227 !! repeat last event (same as !-1) 228 !?str(?) 229 repeat last event containing _s_t_r_; the last ?? is optional 230 !str repeat last event starting with _s_t_r 231 232 If the first character of the command-line is a caret ^^, try history 233 substitution similar to csh(1). 234 235 ^search^replace(^) 236 repeat last event containing _s_e_a_r_c_h and replace this string with 237 _r_e_p_l_a_c_e; the last ^^ is optional 238 239 TTeeccllaa vvaarriiaabblleess 240 *histdup* 241 If set to ggll--aallll, only unique history events are entered in the 242 history list. If set to ggll--pprreevv and the last history event is the 243 same as the current, the current command is not entered. If not 244 defined (undef, the default), all history events are entered. 245 *histfile* 246 Can be set to the pathname where history is going to be saved and 247 restored. If not set, use $FTH_HISTORY or _~_/_._f_t_h_-_h_i_s_t_o_r_y. Default 248 is undef. 249 *history* 250 Can be given a numeric value to control the size of the history 251 list. If not set, use $FTH_HISTORY_LENGTH or 100. Default is 252 undef. 253 *savehist* 254 If true, save history events, otherwise not. Default is #t. 255 *promptstyle* 256 If true, enable special formatting directives within the prompt, see 257 gl_prompt_style(3). Default is #f. 258 259 TTeeccllaa wwoorrddss 260 bbiinnddkkeeyy ( :optional key action -- ) 261 Key bindings and others can be set in _~_/_._f_t_h_r_c to control libtecla 262 and getline. 263 no argument 264 Show user-defined key-bindings set for example in _~_/_._f_t_h_r_c. 265 one argument 266 If _k_e_y is a string, take it as configure string. If _k_e_y is 267 a predefined constant, set specific value as configure 268 string. Valid constants: 269 gl-vi edit-mode vi 270 gl-emacs 271 edit-mode emacs 272 gl-none 273 edit-mode none 274 gl-nobeep 275 nobeep 276 "edit-mode vi \n nobeep" bindkey 277 gl-vi bindkey 278 two arguments 279 If _k_e_y and _a_c_t_i_o_n are strings, bind _a_c_t_i_o_n to _k_e_y. If _k_e_y 280 is a string and _a_c_t_i_o_n is anything else, unbind _k_e_y from 281 last bind. See tecla(7) for key-bindings and actions. 282 "^G" "user-interrupt" bindkey 283 "^G" #f bindkey 284 hhiissttoorryy ( :optional action arg -- ) 285 History events can be displayed, loaded, saved, and cleared where 286 _a_c_t_i_o_n can be one of 287 gl-show 288 show _a_r_g or all history events 289 gl-load 290 load history events from _a_r_g or *histfile* 291 gl-save 292 save history events to _a_r_g or *histfile* 293 gl-clear 294 clear all history events 295 history => show entire history 296 gl-show history => same as above 297 10 history => show 10 last history events 298 gl-show 10 history => same as above 299 gl-load history => load from *histfile* 300 gl-load nil history => same as above 301 gl-load file history => load from file 302 gl-save history => save to *histfile* 303 gl-save nil history => same as above 304 gl-save file history => save to file 305 gl-clear history => clear all history events 306 307 LLooooppss 308 Forth has loop constructs for compile state and interpret state. In 309 addition to the usual do--loop, fftthh provides each--end-each and map--end- 310 map loops for objects. 311 ddoo ( limit start -- ) compile-only 312 ??ddoo ( limit start -- ) compile-only 313 lloooopp ( -- ) compile-only 314 Run loop from _s_t_a_r_t up to but not including _l_i_m_i_t. ??ddoo starts only 315 if _l_i_m_i_t is greater than _s_t_a_r_t. 316 3 0 do i . loop => 0 1 2 317 eeaacchh ( obj -- val ) compile-only 318 eenndd--eeaacchh ( -- ) compile-only 319 Push each element of _o_b_j in order on stack and repeat execution of 320 body. 321 #( 0 1 2 ) each . end-each => 0 1 2 322 mmaapp ( obj -- ) compile-only 323 mmaapp!! ( obj -- ) compile-only 324 eenndd--mmaapp ( -- obj ) compile-only 325 Set each element of _o_b_j in order to global variable *key* and repeat 326 execution of body. The current element of _o_b_j with mmaapp!! or a copy 327 of _o_b_j with mmaapp is set to top of stack before eenndd--mmaapp. 328 #( 0 1 2 ) value a1 329 a1 map i *key* + end-map => #( 0 2 4 ) \ a copy of a1 330 a1 .$ => #( 0 1 2 ) 331 a1 map! i *key* + end-map => #( 0 2 4 ) \ a1 has changed 332 a1 .$ => #( 0 2 4 ) 333 Interpret state loops for use outside word definitions in scripts or in 334 the repl work like their compile state cousins above. The body of the 335 following [do]--[loop], [each]--[end-each] and [map]--[end-map] is in 336 compile state, loop indexes ii, jj, kk and lleeaavvee etc can be used like in 337 colon definitions. 338 [[ddoo]] ( limit start -- ) 339 [[lloooopp]] ( -- ) 340 3 0 [do] i . [loop] => 0 1 2 341 [[eeaacchh]] ( obj -- val ) 342 [[eenndd--eeaacchh]] ( -- ) 343 #( 0 1 2 ) [each] . [end-each] => 0 1 2 344 [[mmaapp]] ( obj -- ) 345 [[mmaapp!!]] ( obj -- ) 346 [[eenndd--mmaapp]] ( -- obj ) 347 #( 0 1 2 ) value a1 348 a1 [map] i *key* + [end-map] => #( 0 2 4 ) \ a copy of a1 349 a1 .$ => #( 0 1 2 ) 350 a1 [map!] i *key* + [end-map] => #( 0 2 4 ) \ a1 has changed 351 a1 .$ => #( 0 2 4 ) 352 353 AArrrraayyss aanndd LLiissttss 354 Arrays: 355 ##(()) ( -- ary ) 356 Return array of length 0 for array-append, array-push etc. 357 ..aarrrraayy ( ary -- ) 358 Print array object _a_r_y to current output. 359 >>aarrrraayy ( vals len -- ary ) 360 Return array object with _l_e_n objects found on parameter stack. 361 Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0. 362 aarrrraayy-->>aarrrraayy ( ary1 -- ary2 ) 363 Return copy of _a_r_y_1 only with references of each element in contrary 364 to _a_r_r_a_y_-_c_o_p_y. If _a_r_y_1 is not an array, return #( ary1 ). 365 #( 0 #{ 'foo 10 } 2 ) value ary1 366 ary1 array->array value ary2 367 ary1 1 array-ref 'foo 30 hash-set! 368 ary1 => #( 0 #{ 'foo 30 } 2 ) 369 ary2 => #( 0 #{ 'foo 30 } 2 ) 370 aarrrraayy-->>lliisstt ( ary -- lst ) 371 Return copy of _a_r_y as list only with references of each elements in 372 contrary to _a_r_r_a_y_-_c_o_p_y. If _a_r_y is not an array, return '( ary ). 373 #( 0 #{ 'foo 10 } 2 ) value ary 374 ary array->list value lst 375 ary 1 array-ref 'foo 30 hash-set! 376 lst => '( 0 #{ 'foo 30 } 2 ) 377 ary => #( 0 #{ 'foo 30 } 2 ) 378 aarrrraayy--aappppeenndd ( ary1 ary2 -- ary1+ary2 ) 379 Append two arrays and return new one. If _a_r_y_2 is not an array, 380 append it as a single element. 381 #( 0 1 2 ) #( 3 4 ) array-append => #( 0 1 2 3 4 ) 382 #( 0 1 2 ) 10 array-append => #( 0 1 2 10 ) 383 aarrrraayy--cclleeaarr ( ary -- ) 384 Clear array and set all elements to #f. 385 aarrrraayy--ccoommppaacctt ( ary1 prc args -- ary2 ) 386 Return new array object with nil elements removed. 387 aarrrraayy--ccoommppaacctt!! ( ary prc args -- ary' ) 388 Remove all nil elements from _a_r_y and return changed array object. 389 aarrrraayy--ccoonnccaatt ( vals len -- ary ) alias for _>_a_r_r_a_y 390 aarrrraayy--ccooppyy ( ary1 -- ary2 ) 391 Return copy of _a_r_y_1 with all elements new created in contrary to 392 _a_r_r_a_y_-_>_a_r_r_a_y. 393 #( 0 #{ 'foo 10 } 2 ) value ary1 394 ary1 array-copy value ary2 395 ary1 1 array-ref 'foo 30 hash-set! 396 ary1 => #( 0 #{ 'foo 30 } 2 ) 397 ary2 => #( 0 #{ 'foo 10 } 2 ) 398 aarrrraayy--ddeelleettee!! ( ary idx -- val ) 399 Delete and return one element from _a_r_y at position _i_d_x. Negative 400 index counts from backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x 401 is not in _a_r_y_'_s range. 402 aarrrraayy--ddeelleettee--kkeeyy ( ary key -- val ) 403 Delete and return _k_e_y from _a_r_y if found, otherwise return #f. 404 aarrrraayy--ffiillll ( ary val -- ) 405 Set all elements of _a_r_y to _v_a_l. 406 aarrrraayy--ffiinndd ( ary key -- key ) 407 Return key if _k_e_y exists in _a_r_y, otherwise #f. 408 aarrrraayy--iinnddeexx ( ary key -- idx ) 409 Return index of _k_e_y in _a_r_y or -1 if not found. 410 aarrrraayy--iinnsseerrtt ( ary1 idx val -- ary2 ) 411 Insert _v_a_l to _a_r_y_1 at position _i_d_x and return new array. _v_a_l can be 412 an array or any other object. Negative _i_d_x counts from backward. 413 Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _a_r_y_1_'_s range. 414 aarrrraayy--iinnsseerrtt!! ( ary idx val -- ary' ) 415 Insert _v_a_l to _a_r_y at position _i_d_x and return changed array. _v_a_l can 416 be a single object or an array. Negative _i_d_x counts from backward. 417 Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _a_r_y_'_s range. 418 aarrrraayy--jjooiinn ( ary sep -- str ) 419 Return string with all elements of _a_r_y converted to their string 420 representation and joined together separated by the string _s_e_p. If 421 _s_e_p is not a string, a space will be used as separator. 422 #( 0 1 2 ) "--" array-join => "0--1--2" 423 #( 0 1 2 ) nil array-join => "0 1 2" 424 aarrrraayy--lleennggtthh ( obj -- len ) 425 If _o_b_j is an array object, return its length, otherwise -1. 426 aarrrraayy--mmeemmbbeerr?? ( ary key -- f ) 427 Return #t if _k_e_y exists in _a_r_y, otherwise #f. 428 aarrrraayy--ppoopp ( ary -- val ) 429 Remove and return last element from _a_r_y. If _a_r_y is empty, return 430 #f. 431 aarrrraayy--ppuusshh ( ary val -- ary' ) 432 Append _v_a_l to _a_r_y. 433 #( 0 1 2 ) 10 array-push => #( 0 1 2 10 ) 434 aarrrraayy--rreeff ( ary idx -- val ) 435 Return value at position _i_d_x. Negative index counts from backward. 436 Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in _a_r_y_'_s range. 437 aarrrraayy--rreejjeecctt ( ary1 prc args -- ary2 ) 438 _p_r_c will be called with _a_r_g_s, an array of zero or more proc 439 arguments, and the current array element set as first arg in _a_r_g_s 440 array. The length of _a_r_g_s + 1 is the required arity of _p_r_c. If _p_r_c 441 returns neither #f nor nil nor 0, this element will be pushed in a 442 new array object. The new array object will be returned. In the 443 example n1 corresponds to the current array element and n2 comes 444 from args, here 2. 445 #( 0 1 2 ) lambda: <{ n1 n2 -- f }> 446 n1 n2 > 447 ; #( 2 ) array-reject => #( 0 1 ) 448 The same a bit shorter: 449 #( 0 1 2 ) <'> > #( 2 ) array-reject => #( 0 1 ) 450 aarrrraayy--rreejjeecctt!! ( ary prc args -- ary' ) 451 _p_r_c will be called with _a_r_g_s, an array of zero or more proc 452 arguments, and the current array element set as first arg in _a_r_g_s 453 array. The length of _a_r_g_s + 1 is the required arity of _p_r_c. If _p_r_c 454 returns neither #f nor nil nor 0, the element will be removed. In 455 the example n1 corresponds to the current array element and n2 comes 456 from args, here 2. 457 aarrrraayy--rreevveerrssee ( ary1 -- ary2 ) 458 Return new array with elements reversed. 459 aarrrraayy--rreevveerrssee!! ( ary -- ary' ) 460 Return _a_r_y with elements reversed. 461 aarrrraayy--sseett!! ( ary idx val -- ) 462 Store _v_a_l at position _i_d_x. Negative index counts from backward. 463 Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in _a_r_y_'_s range. 464 aarrrraayy--sshhiifftt ( ary -- val ) 465 Remove and return first element from _a_r_y. If _a_r_y is empty, return 466 #f. 467 aarrrraayy--ssoorrtt ( ary1 prc -- ary2 ) 468 Return new sorted array. _p_r_c compares two elements A and B and 469 should return a negative integer if A < B, 0 if A == B, and a 470 positive integer if A > B. Raise a _b_a_d_-_a_r_i_t_y exception if _p_r_c 471 doesn't take two arguments. 472 #( 2 1 0 ) lambda: <{ a b -- f }> 473 a b < if 474 -1 475 else 476 a b > if 477 1 478 else 479 0 480 then 481 then 482 ; array-sort => #( 0 1 2 ) 483 aarrrraayy--ssoorrtt!! ( ary prc -- ary' ) 484 Return the sorted _a_r_y. _p_r_c compares two elements A and B and should 485 return a negative integer if A < B, 0 if A == B, and a positive 486 integer if A > B. Raise a _b_a_d_-_a_r_i_t_y exception if _p_r_c doesn't take 487 two arguments. 488 aarrrraayy--ssuubbaarrrraayy ( ary start end -- subary ) 489 Return array built from _a_r_y beginning with index _s_t_a_r_t up to but 490 excluding index _e_n_d. If _e_n_d is nil, up to end of array will be 491 returned. Negative index counts from backward. Raise an 492 _o_u_t_-_o_f_-_r_a_n_g_e exception if _s_t_a_r_t is not in _a_r_y_'_s range. 493 #( 0 1 2 3 4 ) 2 4 array-subarray => #( 2 3 ) 494 #( 0 1 2 3 4 ) -3 -1 array-subarray => #( 2 3 4 ) 495 #( 0 1 2 3 4 ) -3 nil array-subarray => #( 2 3 4 ) 496 aarrrraayy--uunniiqq ( ary1 -- ary2 ) 497 Return new array without duplicated elements of _a_r_y_1. 498 aarrrraayy--uunniiqq!! ( ary -- ary' ) 499 Return _a_r_y without duplicated elements. 500 aarrrraayy--uunnsshhiifftt ( ary val -- ary' ) 501 Prepend _v_a_l to _a_r_y. 502 #( 0 1 2 ) 10 array-unshift => #( 10 0 1 2 ) 503 aarrrraayy== ( ary1 ary2 -- f ) 504 Return #t if _a_r_y_1 and _a_r_y_2 are array objects of same length and 505 content, otherwise #f. 506 aarrrraayy?? ( obj -- f ) 507 Return #t if _o_b_j is an array object, otherwise #f. 508 mmaakkee--aarrrraayy ( len :key initial-element -- ary ) 509 Return array of length _l_e_n filled with keyword INITIAL-ELEMENT 510 values. _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t defaults to nil if not specified. Raise an 511 _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0. 512 513 Assoc arrays: 514 >>aassssoocc ( vals len -- ary ) 515 Return assoc array object with _l_e_n / 2 key-value pairs found on 516 parameter stack. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0 or not 517 even. 518 aarrrraayy--aassssoocc ( ass key -- ret ) 519 If _k_e_y matches, return corresponding key-value pair, otherwise #f. 520 aarrrraayy--aassssoocc--rreeff ( ass key -- val ) 521 If _k_e_y matches, return corresponding value, otherwise #f. 522 aarrrraayy--aassssoocc--rreemmoovvee!! ( ass key -- 'ass ) 523 If _k_e_y matches, remove key-value pair from _a_s_s. 524 aarrrraayy--aassssoocc--sseett!! ( ass key val -- 'ass ) 525 If _k_e_y matches, set key-value pair, otherwise add new pair. 526 aassssoocc ( ass key val -- 'ass ) 527 Build sorted assoc array. _a_s_s must be an assoc array or an empty 528 array #(). 529 #() value ass 530 ass 'a 10 assoc => #a( '( 'a . 10 ) ) 531 ass 'b 20 assoc => #a( '( 'a . 10 ) '( 'b . 20 ) ) 532 aassssoocc?? ( obj -- f ) 533 Return #t if _o_b_j is an assoc array object, otherwise #f. 534 535 Lists: 536 ''(()) ( -- lst ) 537 Return empty list. 538 ..lliisstt ( lst -- ) 539 Print list object _l_s_t to current output. 540 >>lliisstt ( vals len -- lst ) 541 Return list object with _l_e_n objects found on parameter stack. Raise 542 an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0. 543 ccaaddddddrr ( lst -- val ) 544 Return fourth entry, the cadddr, of _l_i_s_t or nil. 545 ccaaddddrr ( lst -- val ) 546 Return third entry, the caddr, of _l_i_s_t or nil. 547 ccaaddrr ( lst -- val ) 548 Return second entry, the cadr, of _l_i_s_t or nil. 549 ccaarr ( lst -- val ) 550 Return first entry, the car, of _l_i_s_t or nil. 551 ccddddrr ( lst -- val ) 552 Return rest, the cddr, of _l_i_s_t without its first and second entries. 553 ccddrr ( lst -- val ) 554 Return rest, the cdr, of _l_i_s_t without its first entry. 555 ccoonnss ( val lst1 -- lst2 ) 556 Return Lisp-like cons pointer with _v_a_l as car and _l_i_s_t as cdr. 557 ccoonnss22 ( val1 val2 lst1 -- lst2 ) 558 Return Lisp-like cons pointer with _v_a_l_1 as car, _v_a_l_2 as cadr and 559 _l_i_s_t as cddr. 560 ccoonnss?? ( obj -- f ) 561 Return #t if _o_b_j is a cons pointer, otherwise #f. 562 llaasstt--ppaaiirr ( lst -- lp ) 563 Return last pair of _l_s_t. 564 '( 0 1 2 3 ) last-pair => '( 3 ) 565 lliisstt-->>aarrrraayy ( lst -- ary ) 566 Return copy of _l_s_t as array only with references of each element in 567 contrary to _l_i_s_t_-_c_o_p_y. _l_s_t is not a cons pointer, return #( lst ). 568 '( 0 #{ 'foo 10 } 2 ) value lst1 569 lst1 list->array value ary2 570 lst1 1 list-ref 'foo 30 hash-set! 571 lst1 => '( 0 #{ 'foo 30 } 2 ) 572 ary2 => #( 0 #{ 'foo 30 } 2 ) 573 lliisstt--aappppeenndd ( arg0 arg1 ... argn n -- lst ) 574 Return list object with _n objects found on parameter stack. Raise 575 an _o_u_t_-_o_f_-_r_a_n_g_e exception if _n < 0. 576 lliisstt--ccooppyy ( lst1 -- ary2 ) 577 Return copy of _l_s_t_1 with all elements new created in contrary to 578 _l_i_s_t_-_>_a_r_r_a_y. 579 '( 0 #{ 'foo 10 } 2 ) value lst1 580 lst1 list-copy value lst2 581 lst1 1 list-ref 'foo 30 hash-set! 582 lst1 => '( 0 #{ 'foo 30 } 2 ) 583 lst2 => '( 0 #{ 'foo 10 } 2 ) 584 lliisstt--ddeelleettee ( lst1 key -- lst2 ) 585 Return new list without all elements equal _k_e_y. 586 lliisstt--ddeelleettee!! ( lst key -- lst' ) 587 Return _l_s_t without all elements equal _k_e_y. 588 lliisstt--ffiillll ( lst val -- lst' ) 589 Set all elements of _l_s_t to _v_a_l. 590 lliisstt--hheeaadd ( lst1 idx -- lst2 ) 591 Return first _i_d_x entries of _l_s_t_1 in a new list or nil. 592 lliisstt--iinnddeexx ( lst key -- idx ) 593 Return index of _k_e_y in _l_s_t or -1 if not found. 594 lliisstt--iinnsseerrtt ( lst1 idx val -- lst2 ) 595 Insert _v_a_l to _l_s_t_1 at position _i_d_x and return new list. _v_a_l can be 596 a list or any other object. Negative _i_d_x counts from backward. 597 Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_1_'_s range. 598 lliisstt--lleennggtthh ( obj -- len ) 599 If _o_b_j is a list (or array), return length of list, if _o_b_j is nil, 600 return 0 otherwise -1. 601 lliisstt--mmeemmbbeerr?? ( lst key -- f ) 602 Return #t if _k_e_y exists in _l_s_t, otherwise #f. 603 lliisstt--rreeff ( lst idx -- val ) 604 Return value at position _i_d_x of _l_s_t. Negative _i_d_x counts from 605 backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_'_s 606 range. 607 lliisstt--rreevveerrssee ( lst1 -- ary2 ) 608 Return new list with elements reversed. 609 lliisstt--sseett!! ( lst idx val -- ) 610 Store element _v_a_l at position _i_d_x in _l_s_t. Negative _i_d_x counts from 611 backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_'_s 612 range. 613 lliisstt--sslliiccee ( lst1 idx :key count 1 -- lst2 ) 614 Return new list without _c_o_u_n_t elements from _i_d_x on. Raise an 615 _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_1_'_s range. 616 #( 0 1 1 2 ) 1 :count 2 list-slice => #( 0 2 ) 617 lliisstt--sslliiccee!! ( lst idx :key count 1 -- lst' ) 618 Return _l_s_t without _c_o_u_n_t elements from _i_d_x on. Raise an 619 _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_'_s range. 620 lliisstt--ttaaiill ( lst1 idx -- lst2 ) 621 Return _i_d_x_'_t_h cdr of _l_s_t_1 up to the last entry in a new list or nil. 622 lliisstt== ( lst1 lst2 -- f ) 623 Return #t if _l_s_t_1 and _l_s_t_2 are list objects of same length and 624 content, otherwise #f. 625 lliisstt?? ( obj -- f ) 626 Return #t if _o_b_j is a list (nil or a cons pointer), otherwise #f. 627 mmaakkee--lliisstt ( len :key initial-element nil -- lst ) 628 Return list of length _l_e_n filled with keyword _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t 629 values. _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t defaults to nil if not specified. Raise an 630 _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0. 631 nniill?? ( obj -- f ) 632 Return #t if _o_b_j is nil, otherwise #f. 633 nnuullll?? ( obj --f ) alias for _n_i_l_? 634 ppaaiirr?? ( obj -- f ) 635 Return #t if _o_b_j is a pair (a cons pointer), otherwise #f. 636 sseett--ccaarr!! ( lst val -- lst' ) 637 Set _v_a_l to car of _l_s_t. 638 sseett--ccddrr!! ( lst val -- lst' ) 639 Set _v_a_l to cdr of _l_s_t. 640 641 Assoc lists: 642 >>aalliisstt ( vals len -- alst ) 643 Return assoc list object with _l_e_n / 2 key-value pairs found on 644 parameter stack. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0 or not 645 even. 646 aaccoonnss ( key val alst1 -- alst2 ) 647 Return new Lisp-like associated list from _k_e_y_-_v_a_l pair and _a_l_s_t_1. 648 lliisstt--aassssoocc ( alst key -- ret ) 649 If _k_e_y matches, return corresponding key-value pair, otherwise #f. 650 lliisstt--aassssoocc--rreeff ( alst key -- val ) 651 If _k_e_y matches, return corresponding value, otherwise #f. 652 lliisstt--aassssoocc--rreemmoovvee!! ( alst key -- alst' ) 653 If _k_e_y matches, remove key-value pair from _a_l_s_t. Return current 654 assoc-list. 655 lliisstt--aassssoocc--sseett!! ( alst key val -- alst' ) 656 If _k_e_y matches, set key-value pair, otherwise add new pair to _a_l_s_t. 657 Return current assoc-list. 658 659 FFiillee FFuunnccttiioonnss 660 General functions: 661 cchhddiirr ( path -- ) alias for _f_i_l_e_-_c_h_d_i_r 662 cclloossee--ppiippee ( fp -- ior ) 663 Forth-like word. 664 256 constant max-line 665 create line-buffer max-line 2 + allot 666 s" pwd" r/o open-pipe throw value FP 667 line-buffer max-line FP read-line throw drop 668 line-buffer swap type 669 FP close-pipe throw 670 ffiillee--aattiimmee ( name -- time ) 671 If _n_a_m_e is a file, return its last access time, otherwise #f. One 672 can convert the number in a readable string with ttiimmee-->>ssttrriinngg. 673 ffiillee--bbaasseennaammee ( name ext -- base ) 674 Return basename of file _n_a_m_e depending on _e_x_t. _e_x_t may be #f, 675 nil/undef, a string or a regexp. If _e_x_t is #f, return filename 676 without pathname. If _e_x_t is nil or undef, discard the part from the 677 last dot to the end of basename _n_a_m_e. If _e_x_t is a string or a 678 regexp, discard found _e_x_t from basename _n_a_m_e. 679 "/home/mike/cage.snd" #f file-basename => "cage.snd" 680 "/home/mike/cage.snd" nil file-basename => "cage" 681 "/home/mike/cage.snd" "nd" file-basename => "cage.s" 682 "/home/mike/cage.snd" /\.(snd|wave)$/ file-basename => "cage" 683 ffiillee--cchhddiirr ( path -- ) 684 Change working directory to _p_a_t_h and, if in a repl, print result to 685 current standard output. If _p_a_t_h is nil, change working directory 686 to $HOME. _p_a_t_h may contain `~' as an abbreviation for home 687 directory. 688 ffiillee--cchhmmoodd ( name mode -- ) 689 Change access mode of file _n_a_m_e to _m_o_d_e. You can write _m_o_d_e with 690 octal numbers: prepend the number with `0o', this is number zero `0' 691 and lower letter `o', similar to `0x' for hexadecimal numbers. 692 ffiillee--cchhrroooott ( path -- ) 693 Change root directory to _p_a_t_h and, if in a repl, print result to 694 current standard output. This function is restricted to the super- 695 user. 696 ffiillee--ccooppyy ( src dst -- ) 697 Copy file _s_r_c to _d_s_t. If _d_s_t is a directory, copy _s_r_c to _D_S_T_/_S_R_C. 698 Raise a _s_y_s_t_e_m_-_e_r_r_o_r exception if fopen(3) fails on any of the two 699 files. 700 ffiillee--ccttiimmee ( name -- time ) 701 If _n_a_m_e is a file, return its status change time, otherwise #f. One 702 can convert the number in a readable string with ttiimmee-->>ssttrriinngg. 703 ffiillee--ddeelleettee ( name -- ) 704 If file _n_a_m_e exist, delete it, otherwise do nothing. 705 ffiillee--ddiirr ( dir -- files-ary ) 706 Return an array of all filenames found in _d_i_r. 707 ffiillee--ddiirrnnaammee ( name -- path ) 708 Return directory part of file _n_a_m_e. 709 "/home/mike/cage.snd" file-dirname => "/home/mike" 710 ffiillee--eevvaall ( name -- ) 711 Load and eval content of file _n_a_m_e and add _n_a_m_e to *loaded-files* if 712 it wasn't there. It's similar to iinncclluuddee except that _n_a_m_e must be 713 on stack (include is a parse word). With ffiillee--eevvaall one can load 714 files from within word definitions. Raise a _l_o_a_d_-_e_r_r_o_r exception if 715 ffiillee--eevvaall fails. 716 ffiillee--ffuullllppaatthh ( name -- path ) 717 Return current working directory prepended to file _n_a_m_e. If name 718 starts with a slash, return _n_a_m_e unchanged. 719 ffiillee--iinnssttaallll ( src dst mode -- f ) 720 Install _s_r_c to _d_s_t with access mode _m_o_d_e if _d_s_t doesn't exist or if 721 modification time of _s_r_c is greater than _d_s_t_'_s. If _d_s_t is a 722 directory, install _s_r_c to _d_s_t_/_s_r_c. Return #t if _s_r_c could be 723 installed, otherwise #f. You can write _m_o_d_e with octal numbers: 724 prepend the number with `0o', this is number zero `0' and lower 725 letter `o', similar to `0x' for hexadecimal numbers. 726 : install-lib { src dst mode -- } 727 src dst mode file-install if 728 "%s --> %04o %s" '( src mode dst ) 729 else 730 "%s is up-to-date" '( dst ) 731 then fth-print cr 732 ; 733 "libsndlib.so" "/usr/opt/lib/s7" 0o755 install-lib 734 ffiillee--lleennggtthh ( name -- len ) 735 If _n_a_m_e is a file, return its length in bytes, otherwise #f. 736 ffiillee--mmaattcchh--ddiirr ( dir reg -- files-ary ) 737 Return an array of filenames in _d_i_r matching regexp _r_e_g. 738 ffiillee--mmkkddiirr ( name mode -- ) 739 Create directory named _n_a_m_e with access mode _m_o_d_e. You can write 740 _m_o_d_e with octal numbers: prepend the number with `0o', this is 741 number zero `0' and lower letter `o', similar to `0x' for 742 hexadecimal numbers. 743 ffiillee--mmkkffiiffoo ( name mode -- ) 744 Create fifo named _n_a_m_e with access mode _m_o_d_e. You can write _m_o_d_e 745 with octal numbers: prepend the number with `0o', this is number 746 zero `0' and lower letter `o', similar to `0x' for hexadecimal 747 numbers. 748 ffiillee--mmttiimmee ( name -- time ) 749 If _n_a_m_e is a file, return its last modification time, otherwise #f. 750 One can convert the number in a readable string with ttiimmee-->>ssttrriinngg. 751 ffiillee--ppwwdd ( -- path ) 752 Return current working directory. 753 ffiillee--rreeaallppaatthh ( name -- path ) 754 If _n_a_m_e starts with `~', replace it with content of environment 755 variable $HOME. If realpath(3) function exists, return resolved 756 path, otherwise return _n_a_m_e with `~' replacement. 757 "~" file-realpath => "/home/mike" 758 "/usr/local" file-chdir => "/usr/local" 759 file-pwd => "/usr/local" 760 "../bin" file-realpath => "/usr/bin" 761 ffiillee--rreennaammee ( src dst -- ) 762 Rename _s_r_c to _d_s_t. 763 ffiillee--rrmmddiirr ( name -- ) 764 Remove empty directory _n_a_m_e. 765 ffiillee--sshheellll ( cmd -- str ) 766 Open pipe for reading, feed it with _c_m_d and collect string output as 767 long as pipe is open. Afterwards close pipe, set read-only variable 768 exit-status and return collected string (with trailing cr). 769 ffiillee--sspplliitt ( name -- ary ) 770 Split file _n_a_m_e in dirname and basename and return result in array 771 of two strings. 772 "/home/mike/cage.snd" file-split 773 => #( "/home/mike" "cage.snd" ) 774 ffiillee--ssyymmlliinnkk ( src dst -- ) 775 Create symlink from _s_r_c named _d_s_t. 776 ffiillee--ssyysstteemm ( cmd -- f ) 777 Execute _c_m_d as a shell command. Set read-only variable exit-status 778 and return #t for success, #f otherwise. In the latter case you can 779 check exit-status. 780 ffiillee--ttoouucchh ( name time -- ) 781 Change modification time of _n_a_m_e to _t_i_m_e. If _t_i_m_e is nil, use 782 current time. 783 ffiillee--ttrruunnccaattee ( name size -- ) 784 Truncate or extend file _n_a_m_e to _s_i_z_e bytes. 785 ooppeenn--ppiippee ( addr u fam -- fp ior ) 786 Forth-like word. 787 256 constant max-line 788 create line-buffer max-line 2 + allot 789 s" pwd" r/o open-pipe throw value FP 790 line-buffer max-line FP read-line throw drop 791 line-buffer swap type 792 FP close-pipe throw 793 sshheellll ( cmd -- str ) alias for _f_i_l_e_-_s_h_e_l_l 794 795 File test functions: 796 ffiillee--bblloocckk?? ( name -- f ) 797 Return #t if _n_a_m_e is a block special file, otherwise #f. 798 ffiillee--cchhaarraacctteerr?? ( name -- f ) 799 Return #t if _n_a_m_e is a character special file, otherwise #f. 800 ffiillee--ddiirreeccttoorryy?? ( name -- f ) 801 Return #t if _n_a_m_e is a directory, otherwise #f. 802 ffiillee--eexxeeccuuttaabbllee?? ( name -- f ) 803 Return #t if _n_a_m_e is an executable file, otherwise #f. 804 ffiillee--eexxiissttss?? ( name -- f ) 805 Return #t if _n_a_m_e is an existing file, otherwise #f. 806 ffiillee--ffiiffoo?? ( name -- f ) 807 Return #t if _n_a_m_e is a named pipe, otherwise #f. 808 ffiillee--ggrrppoowwnneedd?? ( name -- f ) 809 Return #t if _n_a_m_e matches effective gid, otherwise #f. 810 ffiillee--oowwnneedd?? ( name -- f ) 811 Return #t if _n_a_m_e matches effective uid, otherwise #f. 812 ffiillee--rreeaaddaabbllee?? ( name -- f ) 813 Return #t if _n_a_m_e is a readable file, otherwise #f. 814 ffiillee--sseettggiidd?? ( name -- f ) 815 Return #t if _n_a_m_e has set gid bit, otherwise #f. 816 ffiillee--sseettuuiidd?? ( name -- f ) 817 Return #t if _n_a_m_e has set uid bit, otherwise #f. 818 ffiillee--ssoocckkeett?? ( name -- f ) 819 Return #t if _n_a_m_e is a socket, otherwise #f. 820 ffiillee--ssttiicckkyy?? ( name -- f ) 821 Return #t if _n_a_m_e has set sticky bit, otherwise #f. 822 ffiillee--ssyymmlliinnkk?? ( name -- f ) 823 Return #t if _n_a_m_e is a symbolic link, otherwise #f. 824 ffiillee--wwrriittaabbllee?? ( name -- f ) 825 Return #t if _n_a_m_e is a writable file, otherwise #f. 826 ffiillee--zzeerroo?? ( name -- f ) 827 Return #t if _n_a_m_e length is zero, otherwise #f. 828 829 HHaasshhss 830 ##{{}} ( -- hash ) alias for _m_a_k_e_-_h_a_s_h 831 ..hhaasshh ( hash -- ) 832 Print _h_a_s_h object to current output. 833 >>hhaasshh ( vals len -- hash ) 834 Take _l_e_n / 2 key-value pairs from parameter stack and return hash 835 object. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0 or _l_e_n is not 836 even. 837 'foo 0 'bar 1 4 >hash => #{ 'foo => 0 'bar => 1 } 838 hhaasshh-->>aarrrraayy ( hash -- ass ) 839 Return array with #( key value ) pairs of _h_a_s_h_'_s content. 840 #{ 'foo 0 'bar 1 } hash->array 841 => #( #( 'foo 0 ) #( 'bar 1 ) ) 842 hhaasshh--cclleeaarr ( hash -- ) 843 Remove all entries from _h_a_s_h, _h_a_s_h_'_s length is zero. 844 hhaasshh--ccooppyy ( hash1 -- hash2 ) 845 Return copy of _h_a_s_h_1 using object-copy for all elements. 846 hhaasshh--ddeelleettee!! ( hash key -- ary ) 847 Delete key-value pair associated with _k_e_y and return key-value array 848 or #f if not found. 849 hhaasshh--eeaacchh ( hash proc -- ) 850 Run _p_r_o_c for each key-value pair. _p_r_o_c_'_s stack effect must be ( key 851 value -- ). 852 #{ 'foo 0 'bar 1 } lambda: <{ key value -- }> 853 "%s=%s\n" #( key value ) fth-print 854 ; hash-each 855 hhaasshh--ffiinndd ( hash key -- ary ) 856 Return key-value array if _k_e_y exist or #f if not found. 857 hhaasshh--kkeeyyss ( hash -- keys ) 858 Return array of keys. 859 hhaasshh--mmaapp ( hash1 proc -- hash2 ) 860 Run _p_r_o_c for each key-value pair. _p_r_o_c_'_s stack effect must be ( key 861 value -- val ) where val is the new value for key. 862 #{ 'foo 0 'bar 1 } lambda: <{ key val -- val }> 863 val 10 + 864 ; hash-map => #{ 'foo => 10 'bar => 11 } 865 hhaasshh--mmeemmbbeerr?? ( hash key -- f ) 866 Return #t if _k_e_y exists, otherwise #f. 867 hhaasshh--rreeff ( hash key -- value ) 868 Return associated value or #f if not found. 869 hhaasshh--sseett!! ( hash key value -- ) 870 Set _k_e_y_-_v_a_l_u_e pair of _h_a_s_h. If key exists, overwrite existing 871 value, otherwise create new key-value entry. 872 hhaasshh--vvaalluueess ( hash -- values ) 873 Return array of values. 874 hhaasshh== ( obj1 obj2 -- f ) 875 Return #t if _o_b_j_1 and _o_b_j_2 are hash objects with same length and 876 content, otherwise #f. 877 hhaasshh?? ( obj -- f ) 878 Return #t if _o_b_j is a hash object, otherwise #f. 879 mmaakkee--hhaasshh ( -- hash ) 880 Return empty hash object. 881 mmaakkee--hhaasshh--wwiitthh--lleenn ( size -- hash ) 882 Return hash object with _s_i_z_e key-value pairs. Keys are 0, 1, 2, ... 883 and values are nil. 884 885 Property functions: 886 oobbjjeecctt--pprrooppeerrttiieess ( obj -- props ) 887 Return _o_b_j_'_s properties or #f if empty. 888 oobbjjeecctt--pprrooppeerrttyy--rreeff ( obj key -- val ) 889 Return _o_b_j_'_s property val associated with _k_e_y or #f if not found. 890 oobbjjeecctt--pprrooppeerrttyy--sseett!! ( obj key val -- ) 891 Set _k_e_y_-_v_a_l_u_e pair to _o_b_j_'_s property object. 892 pprrooppeerrttiieess ( obj -- props ) 893 Return _o_b_j_'_s global properties or #f if empty. If _o_b_j is #f, return 894 entire global property object. 895 pprrooppeerrttyy--rreeff ( obj key -- val ) 896 Return _o_b_j_'_s global property val associated with _k_e_y or #f if not 897 found. 898 pprrooppeerrttyy--sseett!! ( obj key val -- ) 899 Set _k_e_y_-_v_a_l_u_e pair to _o_b_j_'_s global property object. 900 wwoorrdd--pprrooppeerrttiieess ( xt -- props ) 901 Return _x_t_'_s properties or #f if empty. 902 wwoorrdd--pprrooppeerrttyy--rreeff ( xt key -- val ) 903 Return _x_t_'_s property val associated with _k_e_y or #f if not found. 904 wwoorrdd--pprrooppeerrttyy--sseett!! ( xt key val -- ) 905 Set _k_e_y_-_v_a_l_u_e pair to _x_t_'_s property object. 906 907 HHooookkss 908 ..hhooookk ( hook -- ) 909 Print hook object _h_o_o_k to current output. 910 aadddd--hhooookk!! ( hook prc -- ) alias for _h_o_o_k_-_a_d_d 911 ccrreeaattee--hhooookk ( arity help "name" -- ) 912 Create hook variable _n_a_m_e with _a_r_i_t_y and documentation _h_e_l_p. _a_r_i_t_y 913 can be an integer or an array of length 3, #( req opt rest ). 914 2 "A simple hook." create-hook my-new-hook 915 #( 2 0 #f ) "A simple hook." create-hook my-new-hook 916 hhooookk-->>aarrrraayy ( hook -- ary ) 917 Return array of all _h_o_o_k procedures. 918 hhooookk-->>lliisstt ( hook -- proc-list ) alias for _h_o_o_k_-_>_a_r_r_a_y 919 hhooookk--aadddd ( hook prc -- ) 920 Add hook procedure _p_r_c to _h_o_o_k. Raise a _b_a_d_-_a_r_i_t_y exception if 921 _p_r_c_'_s arity doesn't match _h_o_o_k_'_s arity. 922 hhooookk--aappppllyy ( hook args -- value-list ) 923 Run all hook procedures with _a_r_g_s, an array of arguments. _a_r_g_s can 924 be an array of arguments or a single argument. Raise a _b_a_d_-_a_r_i_t_y 925 exception if _a_r_g_s_'_s length doesn't match _h_o_o_k_'_s arity. 926 2 make-hook value hk1 927 hk1 <'> + 2 make-proc add-hook! 928 hk1 #( 1 2 ) run-hook => #( 3 ) 929 hhooookk--aarriittyy ( hook -- arity ) 930 Return arity array of _h_o_o_k, #( req opt rest ). 931 2 make-hook hook-arity => #( 2 0 #f ) 932 hhooookk--cclleeaarr ( hook -- ) 933 Remove all hook procedures from _h_o_o_k. 934 hhooookk--ddeelleettee ( hook prc-or-name -- prc ) 935 Remove hook procedure _p_r_c_-_o_r_-_n_a_m_e from _h_o_o_k and return it. 936 _p_r_c_-_o_r_-_n_a_m_e can be a string, an xt or a proc. 937 hhooookk--eemmppttyy?? ( hook -- f ) 938 Return #t if no hook procedure exist in _h_o_o_k, otherwise #f. 939 hhooookk--mmeemmbbeerr?? ( hook prc-or-name -- f ) 940 Return #t if procedure _p_r_c_-_o_r_-_n_a_m_e exist in _h_o_o_k, otherwise #f. 941 _p_r_c_-_o_r_-_n_a_m_e can be a string, an xt or a proc. 942 hhooookk--nnaammee ( hook -- name ) 943 Return name of _h_o_o_k as string if hook object, otherwise #f. 944 hhooookk--nnaammeess ( hook -- name-list ) 945 Return array of hook procedure names (strings). 946 hhooookk--pprrooccss ( hook -- proc-list ) alias for _h_o_o_k_-_>_a_r_r_a_y 947 hhooookk== ( obj1 obj2 -- f ) 948 Return #t if _o_b_j_1 and _o_b_j_2 are hook objects of same arity and 949 procedures, otherwise #f. 950 hhooookk?? ( obj -- f ) 951 Return #t if _o_b_j is a hook object, otherwise #f. 952 mmaakkee--hhooookk ( arity -- hook ) 953 Return hook object for procs accepting _a_r_i_t_y arguments. _a_r_i_t_y can 954 be an integer or an array of length 3, #( req opt rest ). 955 2 make-hook value my-new-hook 956 #( 2 0 #f ) make-hook value my-new-hook 957 rreemmoovvee--hhooookk!! ( hook prc-or-name -- prc ) alias for _h_o_o_k_-_d_e_l_e_t_e 958 rreesseett--hhooookk!! ( hook -- ) alias for _h_o_o_k_-_c_l_e_a_r 959 rruunn--hhooookk ( hook args -- value-list ) alias for _h_o_o_k_-_a_p_p_l_y 960 961 IIOO FFuunnccttiioonnss 962 Global variables: 963 *stderr* 964 Return current standard error output IO object. 965 *stdin* 966 Return current standard input IO object. 967 *stdout* 968 Return current standard output IO object. 969 sseett--**ssttddeerrrr** ( io -- old ) 970 Set _i_o to current standard error and return old IO object. 971 sseett--**ssttddiinn** ( io -- old ) 972 Set _i_o to current standard input and return old IO object. 973 sseett--**ssttddoouutt** ( io -- old ) 974 Set _i_o to current standard output and return old IO object. 975 sseett--vveerrssiioonn--ccoonnttrrooll ( val -- ) 976 Set current version control style. Accepted values: 977 #t numbered backups 978 nil numbered/simple backups 979 #f simple backups 980 undef no backups 981 vveerrssiioonn--ccoonnttrrooll ( -- val ) 982 Return current version control style. 983 984 General IO functions: 985 ..iioo ( io -- ) 986 Print _i_o object to current output. 987 eexxiitt--ssttaattuuss ( -- n ) alias for _i_o_-_e_x_i_t_-_s_t_a_t_u_s 988 iioo-->>ssttrriinngg ( io -- str ) 989 Return content of _i_o object as string if possible. 990 iioo--cclloossee ( io -- ) 991 If necessary, flush _i_o, close _i_o object and set closed? to #t. 992 iioo--cclloosseedd?? ( io -- f ) 993 Return #t if _i_o object is closed, otherwise #f. 994 iioo--eeooff?? ( io -- f ) 995 Return #t if EOF is reached, otherwise #f. 996 iioo--eexxiitt--ssttaattuuss ( -- n ) 997 Return exit status of last extern process called via file-shell, 998 file-system, etc. 999 iioo--ffddooppeenn ( fd :key fam r/o -- io ) 1000 Connect file descriptor _f_d to new IO object. If keyword _f_a_m was not 1001 given, open file read-only, otherwise use _f_a_m. See _i_o_-_o_p_e_n for fam. 1002 2 :fam w/o io-fdopen value err-io 1003 err-io "our error log" io-write 1004 err-io io-flush => "our error log" (on stderr) 1005 iioo--ffiilleennaammee ( io -- fname ) 1006 Return filename of _i_o object or #f if filename is not available. 1007 iioo--ffiilleennoo ( io -- fd ) 1008 Return file descriptor of _i_o. 1009 iioo--fflluusshh ( io -- ) 1010 Flushe _i_o object if possible. 1011 iioo--ggeettcc ( io -- c ) 1012 Return next character from _i_o object or #f if EOF. 1013 iioo--iinnppuutt?? ( obj -- f ) 1014 Return #t if _o_b_j is an input IO object, otherwise #f. 1015 iioo--mmooddee ( io -- mode ) 1016 Return access mode of _i_o object. 1017 iioo--ooppeenn ( name :key fam r/o if-exists overwrite -- io ) 1018 Open file _n_a_m_e and return new IO object. If keyword _f_a_m was not 1019 specified, open file read-only, otherwise take _f_a_m. Possible _f_a_m 1020 values: 1021 aa//oo apend "a" 1022 rr//aa read/write-append "a+" 1023 rr//oo read-only "r" 1024 rr//ww read/write "w+" 1025 ww//oo write-only "w" 1026 If keyword iiff--eexxiissttss was not specified, overwrite possible existing 1027 file before open it for writing or appending. Possible iiff--eexxiissttss 1028 values: 1029 ::eerrrroorr 1030 raise an _i_o_-_e_r_r_o_r exception if _n_a_m_e already exist 1031 ::oovveerrwwrriittee 1032 overwrite existing file (default) 1033 ::rreennaammee 1034 depends on environment variable $VERSION_CONTROL and 1035 global Fth variable version-control (see there) 1036 "in-test" io-open value rd-io1 1037 "in-test" :fam r/o io-open value rd-io2 1038 "out-test" :fam w/o io-open value ow-io1 1039 "out-test" :fam w/o :if-exists :overwrite io-open value ow-io2 1040 "out-test" :fam r/w :if-exists :error io-open value rw-io1 1041 "out-test" :fam r/w :if-exists :rename io-open value rn-io1 1042 iioo--ooppeenn--rreeaadd ( name -- io ) 1043 Open file _n_a_m_e for reading and return new IO object. 1044 iioo--ooppeenn--wwrriittee ( name :key if-exists overwrite -- io ) 1045 Open file _n_a_m_e for writing and return new IO object. For keyword 1046 if-exists see _i_o_-_o_p_e_n. 1047 iioo--oouuttppuutt?? ( obj -- f ) 1048 Return #t if _o_b_j is an output IO object, otherwise #f. 1049 iioo--ppooss--rreeff ( io -- pos ) 1050 Return current _i_o object position. 1051 iioo--ppooss--sseett!! ( io pos -- ) 1052 Set _i_o object position to _p_o_s. 1053 iioo--ppuuttcc ( io c -- ) 1054 Write character _c to _i_o object. 1055 iioo--rreeaadd ( io -- line ) 1056 Return next line from _i_o object or #f if EOF. 1057 iioo--rreeaaddlliinneess ( io -- array-of-lines ) 1058 Return the entire _i_o object content as an array of strings, line by 1059 line. 1060 iioo--rreeooppeenn ( io1 name :key fam io1-fam -- io2 ) 1061 Return new IO object as copy of _i_o_1 and close _i_o_1. If _n_a_m_e is not a 1062 string, for example #f or nil, use filename from _i_o_1. If keyword 1063 _f_a_m was not given, use mode from _i_o_1, otherwise use _f_a_m. All 1064 restrictions on reopen apply, for example, a file opened for reading 1065 cannot reopened for writing etc. 1066 "1-test" io-open-write value io1 1067 io1 "hello" io-write 1068 io1 "2-test" io-reopen value io2 1069 io1 io-closed? => #t 1070 io2 "world" io-write 1071 io2 io-close 1072 io2 io-closed? => #t 1073 "1-test" readlines => #( "hello" ) 1074 "2-test" readlines => #( "world" ) 1075 *stderr* "error.log" io-reopen value err-io 1076 iioo--rreewwiinndd ( io -- ) 1077 Rewind position to begin of _i_o object. 1078 iioo--sseeeekk ( io offset :key whence io-seek-set -- pos ) 1079 Add _o_f_f_s_e_t to the file position in _i_o object and return new 1080 position. Keyword _w_h_e_n_c_e can have the following values: 1081 SEEK_SET 1082 offset counts from begin of file (default) 1083 SEEK_CUR 1084 offset counts from current position 1085 SEEK_END 1086 offset counts from end of file. 1087 iioo--tteellll ( io -- pos ) alias for _i_o_-_p_o_s_-_r_e_f 1088 iioo--wwrriittee ( io line -- ) 1089 Write _l_i_n_e to _i_o object. 1090 iioo--wwrriittee--ffoorrmmaatt ( io fmt args -- ) 1091 Write string built from _f_m_t and array _f_m_t_-_a_r_g_s to _i_o object. 1092 iioo--wwrriitteelliinneess ( io array-of-lines -- ) 1093 Write _a_r_r_a_y_-_o_f_-_l_i_n_e_s to _i_o object. 1094 iioo== ( obj1 obj2 -- f ) 1095 Return #t if _o_b_j_1 and _o_b_j_2 are IO objects with equal filenames, 1096 modes and file positions, otherwise #f. 1097 iioo?? ( obj -- f ) 1098 Return #t if _o_b_j is an IO object, otherwise #f. 1099 rreeaaddlliinneess ( name -- array-of-lines ) 1100 Open file _n_a_m_e, read its content in an array, close file and return 1101 the array. 1102 wwrriitteelliinneess ( name array-of-lines -- ) 1103 Open file _n_a_m_e, write the content of _a_r_r_a_y_-_o_f_-_l_i_n_e_s to it and close 1104 file. 1105 1106 File functions: 1107 iioo--ooppeenn--ffiillee ( :key fam r/o args -- io ) 1108 General IO open function. Open and return any IO object for io- 1109 read/io-write etc. Keyword argument :fam defaults to r/o. See 1110 _m_a_k_e_-_s_o_f_t_-_p_o_r_t for keyword arguments. 1111 :filename "foo" io-open-file value io1 1112 :filename "foo" :fam r/o io-open-file value io2 1113 :filename "bar" :fam r/w io-open-file value io3 1114 :command "ls -lF" io-open-file value io4 1115 :command #( "ls" "-lF" ) io-open-file value io5 1116 :string "test string" io-open-file value io6 1117 :soft-port "test" io-open-file value io7 1118 iioo--ooppeenn--iinnppuutt--ffiillee ( :key args -- io ) 1119 General IO open function. Return IO object for reading. See _m_a_k_e_- 1120 _s_o_f_t_-_i_n_p_u_t_-_p_o_r_t for keyword arguments. 1121 :filename "foo" io-open-input-file value io1 1122 :command "ls -lF" io-open-input-file value io2 1123 :command #( "ls" "-lF") io-open-input-file value io3 1124 :string "test string" io-open-input-file value io4 1125 :soft-port "input-test" io-open-input-file value io5 1126 iioo--ooppeenn--oouuttppuutt--ffiillee ( :key args -- io ) 1127 General IO open function. Return IO object for writing. See _m_a_k_e_- 1128 _s_o_f_t_-_o_u_t_p_u_t_-_p_o_r_t for keyword arguments. 1129 :filename "foo" io-open-output-file value io1 1130 :command "cat" io-open-output-file value io2 1131 :command #( "cat" ) io-open-output-file value io3 1132 (dq(dq value s1 1133 :string s1 io-open-output-file value io4 1134 mmaakkee--ffiillee--iinnppuutt--ppoorrtt ( name -- io ) alias for _i_o_-_o_p_e_n_-_r_e_a_d 1135 mmaakkee--ffiillee--oouuttppuutt--ppoorrtt ( name :key args -- io ) alias for _i_o_-_o_p_e_n_-_w_r_i_t_e 1136 mmaakkee--ffiillee--ppoorrtt ( name :key args -- io ) alias for _i_o_-_o_p_e_n 1137 1138 Pipe functions: 1139 iioo--ppooppeenn ( cmd :key fam r/o -- io ) 1140 Open pipe for command _c_m_d and return new IO object. _c_m_d may be a 1141 string (with shell expansion) or an array of strings. If keyword 1142 _f_a_m was not given, open pipe read-only, otherwise use _f_a_m. See _i_o_- 1143 _o_p_e_n for fam. 1144 "ls -lAF ~/" io-popen value read-io1 1145 #( "ls" "-lAF" "~/") io-popen value read-io2 1146 read-io1 io->string => "..." 1147 read-io1 io-close 1148 "cat" :fam w/o io-popen-write value write-io1 1149 write-io1 "hello" io-write 1150 write-io1 io-close 1151 iioo--ppooppeenn--rreeaadd ( cmd -- io ) 1152 Open read-only pipe for command _c_m_d and return new IO object. _c_m_d 1153 may be a string (with shell expansion) or an array of strings. 1154 iioo--ppooppeenn--wwrriittee ( cmd -- io ) 1155 Open write-only pipe for command _c_m_d and return new IO object. _c_m_d 1156 may be a string (with shell expansion) or an array of strings. 1157 mmaakkee--ppiippee--iinnppuutt--ppoorrtt ( cmd -- io ) alias for _i_o_-_p_o_p_e_n_-_r_e_a_d 1158 mmaakkee--ppiippee--oouuttppuutt--ppoorrtt ( cmd -- io ) alias for _i_o_-_p_o_p_e_n_-_w_r_i_t_e 1159 mmaakkee--ppiippee--ppoorrtt ( cmd :key args -- io ) alias for _i_o_-_p_o_p_e_n 1160 1161 String functions: 1162 iioo--ssooppeenn ( str :key fam r/o -- io ) 1163 Open string with content _s_t_r_i_n_g and return new IO object. If 1164 keyword _f_a_m was not given, opens string read-only, otherwise takes 1165 _f_a_m. See _i_o_-_o_p_e_n for fam. 1166 "test-string" value s1 1167 s1 io-sopen value read-io1 1168 read-io1 io-read => "test-string" 1169 read-io1 io-close 1170 s1 :fam r/a io-sopen value append-io1 1171 append-io1 " with append content" io-write 1172 append-io1 io-rewind 1173 append-io1 io-read => "test-string with append content" 1174 append-io1 io-close 1175 s1 .string => "test-string with append content" 1176 iioo--ssooppeenn--rreeaadd ( str -- io ) 1177 Open read-only string with content _s_t_r and return new IO object. 1178 iioo--ssooppeenn--wwrriittee ( str -- io ) 1179 Open _s_t_r for writing and return new IO object. 1180 mmaakkee--ssttrriinngg--iinnppuutt--ppoorrtt ( cmd -- io ) alias for _i_o_-_s_o_p_e_n_-_r_e_a_d 1181 mmaakkee--ssttrriinngg--oouuttppuutt--ppoorrtt ( cmd :key args -- io ) alias for _i_o_-_s_o_p_e_n_-_w_r_i_t_e 1182 mmaakkee--ssttrriinngg--ppoorrtt ( str :key fam r/o -- io ) alias for _i_o_-_s_o_p_e_n 1183 1184 Socket functions: 1185 iioo--nnooppeenn (host :key port 1024 domain AF_INET -- io) 1186 Connect to an already established server and return new IO object. 1187 Raise an a _s_o_c_k_e_t_-_e_r_r_o_r exception if an error occured. _h_o_s_t is a 1188 host name (AF_INET) or a path name (AF_UNIX). If _h_o_s_t is not a 1189 string, "localhost" will be used. _p_o_r_t is the connection port 1190 (default 1024) if _d_o_m_a_i_n is AF_INET, otherwise unused, and _d_o_m_a_i_n 1191 can be one of AF_INET (default) or AF_UNIX. The socket is opened 1192 with _d_o_m_a_i_n, hardcoded second argument SOCK_STREAM, and hardcoded 1193 third argument of 0, see socket(2) and connect(2) for more 1194 information. 1195 "localhost" :port 25 io-nopen value io 1196 io io-read => "220 fth-devel.net ESMTP Sendmail ..." 1197 io "HELP\r\n" io-write 1198 io io-read => "... (sendmail help output)" 1199 io io-close 1200 "ftp.freebsd.org" :port 21 io-nopen to io 1201 io io-read => "220 ftp.beastie.tdk.net FTP server ..." 1202 io "HELP\r\n" io-write 1203 io io-read => "... (ftpd help output)" 1204 io io-close 1205 mmaakkee--ssoocckkeett--ppoorrtt ( host :key args -- io ) alias for _i_o_-_n_o_p_e_n 1206 nneett--aacccceepptt ( fd host domain -- io ) 1207 Accept a connection on a socket and return an IO object after 1208 established connection. _f_d is the socket descriptor, _h_o_s_t can be an 1209 arbitrary name, its only use is the name for the IO object, _d_o_m_a_i_n 1210 is one of AF_INET or AF_UNIX. This is used on the server side of a 1211 socket connection. Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if accept(2) 1212 fails. 1213 nneett--bbiinndd ( fd host port domain -- ) 1214 Assign a name to a socket. _f_d is the socket descriptor, _h_o_s_t is a 1215 host name (AF_INET) or a path name (AF_UNIX), _p_o_r_t is the port if 1216 _d_o_m_a_i_n is AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or 1217 AF_UNIX. This is used on the server side of a socket connection. 1218 Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if bind(2) fails. 1219 nneett--ccoonnnneecctt ( fd host port domain -- io ) 1220 Connect to a server and return IO object after an established 1221 connection. _f_d is the socket descriptor, _h_o_s_t is a host name 1222 (AF_INET) or a name (AF_UNIX), _p_o_r_t is the port if _d_o_m_a_i_n is 1223 AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or AF_UNIX. 1224 This is used on the client side of a socket connection. Raise a 1225 _s_o_c_k_e_t_-_e_r_r_o_r exception if connect(2) fails. 1226 nneett--lliisstteenn ( fd -- ) 1227 Inform the operating system that connection requests should be 1228 delivered. _f_d is the previously opened socket descriptor. This is 1229 used on the server side of a socket connection. Raise a 1230 _s_o_c_k_e_t_-_e_r_r_o_r exception if listen(2) fails. 1231 nneett--rreeccvv ( fd flags -- msg ) 1232 Receive data via a socket and return it. _f_d is the socket 1233 descriptor and _f_l_a_g_s can be 0, MSG_PEEK, or MSG_OOB. Raise a 1234 _s_o_c_k_e_t_-_e_r_r_o_r exception if recv(2) fails. 1235 nneett--rreeccvvffrroomm ( fd flags host port domain -- msg ) 1236 Receive data via a socket and return it. _f_d is the socket 1237 descriptor, _f_l_a_g_s can be 0, MSG_PEEK, or MSG_OOB. _h_o_s_t is a host 1238 name (AF_INET) or a path name (AF_UNIX), _p_o_r_t is the port if is 1239 AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or AF_UNIX. 1240 Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if recvfrom(2) fails. 1241 nneett--sseenndd ( fd msg flags -- ) 1242 Send data via a socket. _f_d is the socket descriptor, _m_s_g is the 1243 data to send and _f_l_a_g_s can be 0, MSG_PEEK or MSG_OOB. Raise a 1244 _s_o_c_k_e_t_-_e_r_r_o_r exception if send(2) fails. 1245 nneett--sseennddttoo ( fd msg flags host port domain -- ) 1246 Send data via a socket. _f_d is the socket descriptor, _m_s_g is the 1247 data to send, _f_l_a_g_s can be 0, MSG_PEEK, or MSG_OOB. _h_o_s_t is a host 1248 name (AF_INET) or a name (AF_UNIX), _p_o_r_t is the port if _d_o_m_a_i_n is 1249 AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or AF_UNIX. 1250 Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if sendto(2) fails. 1251 nneett--sshhuuttddoowwnn ( fd how -- ) 1252 Close socket connection. _f_d is the socket descriptor and _h_o_w is one 1253 of SHUT_RD, SHUT_WR or SHUT_RDWR. Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if 1254 shutdown(2) fails. 1255 nneett--ssoocckkeett ( domain type -- fd ) 1256 Return socket descriptor. _d_o_m_a_i_n can be AF_INET or AF_UNIX, _t_y_p_e 1257 can be SOCK_STREAM or SOCK_DGRAM. The third argument to socket(2) 1258 is 0 and cannot be set by the user. Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception 1259 if socket(2) fails. 1260 AF_INET SOCK_STREAM net-socket value fd 1261 fd "localhost" 1024 AF_INET net-bind 1262 fd net-listen 1263 fd "localhost" AF_INET net-accept value io 1264 1265 MMiisscceellllaanneeoouuss 1266 Constants: 1267 FICL_VM_STATE_INTERPRET 1268 FICL_VM_STATE_COMPILE 1269 INTERPRET_STATE alias for _F_I_C_L___V_M___S_T_A_T_E___I_N_T_E_R_P_R_E_T 1270 COMPILE_STATE alias for _F_I_C_L___V_M___S_T_A_T_E___C_O_M_P_I_L_E 1271 Return compile or interpret state value for comparison with global 1272 variable state. 1273 state @ COMPILE_STATE = if 1274 \ compile state here 1275 else 1276 \ interpret state here 1277 then 1278 cell 1279 Return bytes of one cell. 1280 dfloat 1281 Return bytes of one dfloat. 1282 ficl-version 1283 Return Ficl version string. 1284 float 1285 Return bytes of one float (same as dfloat). 1286 fth-date 1287 Return version date string. 1288 fth-version 1289 Return full Fth version string. 1290 sfloat 1291 Return bytes of one sfloat (same as dfloat). 1292 1293 Features and Source files: 1294 *features* 1295 Return array of all features. 1296 aadddd--ffeeaattuurree ( str -- ) 1297 Add _s_t_r, a string or symbol, to *features* list. 1298 'snd add-feature 1299 aadddd--llooaadd--lliibb--ppaatthh ( path -- ) 1300 Add string _p_a_t_h to *load-lib-path* array if not already there. 1301 "/home/mike/lib/fth" add-load-lib-path 1302 aadddd--llooaadd--ppaatthh ( path -- ) 1303 Add string _p_a_t_h to *load-path* array if not already there. 1304 "/home/mike/share/fth" add-load-path 1305 aapprrooppooss (( oobbjj ---- aarryy )) 1306 Return array of dictionary entries matching regexpression or string 1307 _o_b_j. 1308 /do/ apropos => #( "doLocal" ... ) 1309 ddll--llooaadd ( "lib" "func" -- ) 1310 Load dynamic library _l_i_b and call its function _f_u_n_c. 1311 dl-load dbm Init_dbm 1312 iinncclluuddee ( "name" -- ) 1313 Load Forth source file _n_a_m_e and add _n_a_m_e to *loaded-files* if it 1314 wasn't already there. If file extension wasn't specified, use 1315 `.fs'. If _n_a_m_e doesn't exist, try each entry of *load-path* with 1316 _n_a_m_e. With iinncclluuddee one can load a file more than once. Before 1317 loading _n_a_m_e, run hook _b_e_f_o_r_e_-_l_o_a_d_-_h_o_o_k. After loading _n_a_m_e, run 1318 hook _a_f_t_e_r_-_l_o_a_d_-_h_o_o_k. Raise a _n_o_-_s_u_c_h_-_f_i_l_e exception if file 1319 doesn't exist, raise a _l_o_a_d_-_e_r_r_o_r if an error occured during load. 1320 include hello 1321 iinnssttaallll ( "file" -- ) 1322 Install _f_i_l_e in first writeable path found in *load-path* (*.fs[m]) 1323 or *load-lib-path* (*.so). In the last example the trailing --ee is 1324 necessary because the last occurrence of --ee will be compiled. 1325 iinnssttaallll is a parse word and won't work in compile state. 1326 install snd-test.fs 1327 install sndlib.so 1328 % fth -ve "install sndlib.so" -e "" 1329 iinnssttaallll--ffiillee ( file -- ) 1330 Install _f_i_l_e in first writeable path found in *load-path* (*.fs[m]) 1331 or *load-lib-path* (*.so). A warning is given if no writable path 1332 is found. 1333 "snd-test.fs" install-file 1334 "sndlib.so" install-file 1335 llooaadd--iinniitt--ffiillee ( file -- ) 1336 If Forth source _f_i_l_e exists in current or $HOME dir, load it, 1337 otherwise do nothing. 1338 ".my-fth-init" load-init-file 1339 pprroovviiddeedd?? ( obj -- f ) 1340 Return #t if _o_b_j, a string or symbol, exists in *features* list, 1341 otherwise #f. 1342 'fth provided? => #t 1343 'foo provided? => #f 1344 rreeqquuiirree ( "name" -- ) 1345 If Forth source file _n_a_m_e doesn't exist in array *loaded-files*, 1346 load it and add _n_a_m_e to *loaded-files*. If file extension wasn't 1347 specified, use `.fs'. If _n_a_m_e doesn't exist, try each entry of 1348 *load-path* with _n_a_m_e. With rreeqquuiirree one can load a file only one 1349 time. Before loading _n_a_m_e, run hook _b_e_f_o_r_e_-_l_o_a_d_-_h_o_o_k. After 1350 loading _n_a_m_e, run hook _a_f_t_e_r_-_l_o_a_d_-_h_o_o_k. Raise a _n_o_-_s_u_c_h_-_f_i_l_e 1351 exception if file doesn't exist, raise a _l_o_a_d_-_e_r_r_o_r if an error 1352 occured during load. 1353 require hello 1354 uunnsshhiifftt--llooaadd--lliibb--ppaatthh ( path -- ) 1355 Prepend string _p_a_t_h to *load-lib-path* array if not already there. 1356 "/home/mike/lib/fth" unshift-load-lib-path 1357 uunnsshhiifftt--llooaadd--ppaatthh ( path -- ) 1358 Prepend string _p_a_t_h to *load-path* array if not already there. 1359 "/home/mike/share/fth" unshift-load-path 1360 1361 Catch errors: 1362 fftthh--ccaattcchh ( ?? obj exc arg -- ?? res ) 1363 Run proc or xt _o_b_j in save environment. If _o_b_j fails with an 1364 exception, data and return stack environments are recovered to the 1365 state before execution. If _o_b_j is #f, finishs immediately and 1366 returns #f. The second argument _e_x_c may be a symbol, an exception, 1367 or #t. If it's a symbol or an exception, this will be catched, if 1368 it's #t, all exceptions will be catched. The third argument _a_r_g may 1369 be nil or a return value. If _a_r_g is nil, the catched exception or 1370 #f will be returned, if _a_r_g is any other than nil, _a_r_g will be 1371 returned instead of the catched exception; if _a_r_g is a proc or xt, 1372 this will be executed instead of simply returned. The stack effect 1373 must be ( retval -- val ). 1374 3 :initial-element 0.3 make-array value ary 1375 ary .array => #( 0.3 0.3 0.3 ) 1376 ary 2 <'> array-ref #t nil fth-catch => 0.3 #f 1377 ary 4 <'> array-ref 'out-of-range #t fth-catch 1378 => #( 0.3 0.3 0.3 ) 4 #t 1379 : ary-handler { retval -- val } 1380 "from handler: %S\n" #( retval ) fth-print 1381 #t ( return value ) 1382 ; 1383 ary 4 0.4 <'> array-set! 1384 'out-of-range <'> ary-handler fth-catch 1385 prints: => from handler: \ 1386 #( 'out-of-range "array-set! (ary_set) arg 2: \ 1387 4 is out of range" ) 1388 => 0.4 #t 1389 ary 2 0.4 <'> array-set! 1390 'out-of-range <'> ary-handler fth-catch => #f 1391 fftthh--rraaiissee ( exc fmt args -- ) 1392 Raise exception _e_x_c with text built from _f_m_t and _a_r_g_s. If _f_m_t is a 1393 format string with N %s-format signs, _a_r_g_s should have N elements 1394 with corresponding values. If _e_x_c is #f, reraise last exception. 1395 'bad-arity "%s: %s args required, got %s" 1396 #( proc 2 3 ) fth-throw 1397 => #<bad-arity in test-proc: 2 args required, got 3> 1398 #f #f #f fth-raise 1399 => reraise last exception 1400 fftthh--tthhrrooww ( exc args -- ) 1401 Throw exception _e_x_c with text built from _a_r_g_s. If _a_r_g_s is not an 1402 array, its string representation is used. If _a_r_g_s is NIL or an empty 1403 array, a default string is used. If _a_r_g_s is an array with one 1404 element, this string is used. If _a_r_g_s is an array and its first 1405 element is a format string with N %s-format signs, _a_r_g_s should have 1406 N more elements with corresponding values. 1407 \ 1408 \ ARGS: any object 1409 \ 1410 'bad-arity proc fth-throw 1411 => #<bad-arity in test-proc> 1412 \ 1413 \ ARGS: nil or #() 1414 \ 1415 'bad-arity nil fth-throw 1416 => #<bad-arity: proc has bad arity> 1417 \ 1418 \ ARGS: #( string ) 1419 \ 1420 'bad-arity #( "test-proc" ) fth-throw 1421 => #<bad-arity in test-proc> 1422 \ 1423 \ ARGS: #( fmt arg1 arg2 arg3 ) 1424 \ 1425 'bad-arity #( "%s: %s args required, got %s" 1426 proc 1427 2 1428 3 ) fth-throw 1429 => #<bad-arity in test-proc: 2 args required, got 3> 1430 ssttaacckk--rreesseett ( ?? -- ) 1431 Reset the data stack to initial state. 1432 1433 Time functions: 1434 ccuurrrreenntt--ttiimmee ( -- secs ) 1435 Return time in seconds since 1970/01/01 as ficl2Unsigned. See 1436 time(3) for more information. 1437 ggmmttiimmee ( secs -- ary ) 1438 Return array of eleven elements with _s_e_c_s converted to Greenwich 1439 Mean Time. 1440 sec 1441 seconds after minute (0-60) 1442 min 1443 minutes after the hour (0-59) 1444 hour 1445 hours since midnight (0-23) 1446 mday 1447 day of the month (1-31) 1448 mon 1449 months since January (0-11) 1450 year 1451 years since 1900 1452 wday 1453 days since Sunday (0-6) 1454 yday 1455 days since January 1 (0-365) 1456 isdst 1457 Daylight Savings Time flag 1458 tm_gmtoff 1459 offset from UTC in seconds 1460 tm_zone 1461 timezone abbreviation 1462 llooccaallttiimmee ( secs -- ary ) 1463 Return array of eleven elements with _s_e_c_s converted to local time, 1464 see gmtime. 1465 mmkkttiimmee ( ary -- secs ) 1466 Return time constructed from values of _a_r_y. _a_r_y may be #f or an 1467 array of up to eleven elements where single elements may be #f, see 1468 gmtime for array elements. 1469 #( 28 40 2 14 0 112 6 13 #f 3600 "CET" ) mktime => 1326505228 1470 ssttrrffttiimmee ( fmt secs -- str ) 1471 Convert ficl2Unsigned _s_e_c_s in a date string corresponding to _f_m_t. 1472 The _f_m_t string will be interpreted by strftime(3). 1473 "%a %b %d %H:%M:%S %Z %Y" current-time strftime 1474 => "Sat Jan 14 02:40:28 CET 2012" 1475 ssttrrppttiimmee ( str fmt -- secs ) 1476 Parse _s_t_r according to _f_m_t and return seconds as ficl2Unsigned. 1477 "2012 01 14" "%Y %m %d" strptime time->string 1478 => "Sat Jan 14 02:40:28 CET 2012" 1479 ttiimmee ( -- r ) 1480 Return real time, a ficlFloat. 1481 ttiimmee-->>ssttrriinngg ( secs -- str ) 1482 Convert ficl2Unsigned _s_e_c_s in a date string in current local time. 1483 current-time time->string => "Sat Jan 14 02:40:28 CET 2012" 1484 ttiimmee--rreesseett ( -- ) 1485 Set global timeval struct variable to current time. 1486 uuttiimmee ( -- utime stime ) 1487 Return user and system time as ficlFloats. Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d 1488 exception if times(3) is not available. 1489 utime => 0.171875 0.0234375 1490 1491 System information: 1492 ddaattee ( -- str ) 1493 Return date in default UNIX format as a string. 1494 eennvviirroonn ( -- ary ) 1495 Return hash of all shell environment variables and their values. 1496 eexxeecc ( cmd -- ) 1497 Replace current process by running _c_m_d as shell command. If _c_m_d is 1498 a string, shell expansion takes place and $SHELL -- or sshh if $SHELL 1499 is empty -- executes _c_m_d. If _c_m_d is an array of strings, no shell 1500 expansion takes place and _c_m_d _N_O _0 _a_r_r_a_y_-_r_e_f should be a program 1501 name. 1502 lambda: <{}> #( "ls" "-lAF" ) exec ; fork 1503 lambda: <{}> "ls -lAF [A-Z]*" exec ; fork 1504 ffoorrkk ( xt -- pid ) 1505 Create child process and execute _x_t in the child. The child process 1506 returns nothing, parent returns child's process id. 1507 lambda: <{}> "ls -lAF" exec ; fork value pid 1508 pid SIGKILL kill 1509 ggeetteeggiidd ( -- id ) 1510 Return effective group id of calling process. 1511 ggeetteennvv ( name -- value ) 1512 Return content of shell environment variable _n_a_m_e as string or #f if 1513 variable is not defined. 1514 ggeetteeuuiidd ( -- id ) 1515 Return effective user id of calling process. 1516 ggeettggiidd ( -- id ) 1517 Return real group id of calling process. 1518 ggeetthhoossttnnaammee ( -- str ) 1519 Return name of current host. 1520 ggeettllooggiinn ( -- str ) 1521 Return name of user associated with current session. 1522 ggeettppiidd ( -- id ) 1523 Return process id. 1524 ggeettppppiidd ( -- id ) 1525 Return parent process id. 1526 ggeettsseerrvvbbyynnaammee ( str -- ary ) 1527 Return array containing the service, an array of aliases, the port 1528 number and the protocol. Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d exception if 1529 getservbyname(3) is not available. 1530 "smtp" getservbyname => #( "smtp" #( "mail" ) 25 "tcp" ) 1531 ggeettsseerrvvbbyyppoorrtt ( port -- ary ) 1532 Return array containing the service, an array of aliases, the port 1533 number and the protocol. Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d exception if 1534 getservbyport(3) is not available. 1535 25 getservbyport => #( "smtp" #( "mail" ) 25 "tcp" ) 1536 ggeettuuiidd ( -- id ) 1537 Return real user id of calling process. 1538 hhoossttnnaammee ( -- ) 1539 kkiillll ( pid sig -- ) 1540 Send signal _s_i_g to process ID _p_i_d. If _p_i_d is zero, send _s_i_g to 1541 current process. _s_i_g is a number or a constant like SIGKILL. 1542 ppuutteennvv ( name value -- ) 1543 Set _v_a_l_u_e to shell environment variable _n_a_m_e. 1544 sseetteeggiidd ( id -- ) 1545 Set effective user _i_d. This is only permitted if _i_d is equal real 1546 UID or effective UID or the effective UID is that of the super user. 1547 sseetteeuuiidd ( id -- ) 1548 Set effective group _i_d. This is only permitted if _i_d is equal real 1549 GID or effective GID or the effective UID is that of the super user. 1550 sseettggiidd ( id -- ) 1551 Set real group _i_d. This is only permitted if _i_d is equal real GID 1552 or effective GID or the effective UID is that of the super user. 1553 sseetthhoossttnnaammee ( str -- ) 1554 Set name of current host to _s_t_r. This call is restricted to the 1555 super-user. Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d exception if sethostname(3) is 1556 not available. 1557 sseettuuiidd ( id -- ) 1558 Set real user _i_d. This is only permitted if _i_d is equal real UID or 1559 effective UID or the effective UID is that of the super user. 1560 ssiiggnnaall ( sig xt -- old-xt ) 1561 Install _x_t for signal _s_i_g as an signal handler and return old 1562 handler. _X_T must take one value from the stack, the signal, and 1563 must not return any value; its stack effect is ( sig -- ). The old 1564 xt handler can be preserved for later use. 1565 SIGINT lambda: { sig -- } 1566 ." SIGINT received" cr 1567 ; signal value old-xt 1568 sslleeeepp ( secs -- ) 1569 Pause for _s_e_c_s seconds. 1570 wwaaiitt ( -- pid ) 1571 Wait for child process and return its process ID. Set global read 1572 only variable exit-status to wait status. 1573 wwaaiittppiidd ( pid flags -- ) 1574 Wait for child process _p_i_d. Set global read only variable exit- 1575 status to wait status. _f_l_a_g_s may be 0 or WNOHANG and WUNTRACED 1576 ored. 1577 1234 0 waitpid 1578 1234 WNOHANG waitpid 1579 1234 WNOHANG WUNTRACED or waitpid 1580 1581 Getopt variables: 1582 optarg 1583 Getopt set this variable to the option string of an argument which 1584 accepts options, otherwise to #f. 1585 opterr 1586 If #t, the default, getopt print error message in case of an error, 1587 if #f, no message will be printed. 1588 optind 1589 Getopt set this variable to the index of the next element of the 1590 *argv* array. 1591 optopt 1592 If getopt finds unknown options or getopt misses required arguments, 1593 it stores that option in this variable. 1594 1595 Getopt functions: 1596 ggeettoopptt ( argv opts -- c ) 1597 Return next option character from command line options. See 1598 _E_X_A_M_P_L_E_S for an getopt example. 1599 ggeettoopptt--lloonngg ( argv opts longopts -- c ) 1600 Return next option character from command line options. 1601 : long-test 1602 #f #f { bflag ffile } 1603 #f to opterr 1604 #( #( "flag" no-argument <char> b ) 1605 #( "file" required-argument <char> f ) ) { opts } 1606 begin 1607 *argv* "bf:" opts getopt-long ( ch ) dup 1608 while ( ch ) 1609 case 1610 <char> b of #t to bflag endof 1611 <char> f of optarg to ffile endof 1612 <char> ? of 1613 "-%c requires an argument" 1614 #( optopt ) fth-warning 1615 endof 1616 endcase 1617 repeat drop ( ch ) 1618 optind 0 ?do *argv* array-shift drop loop 1619 *argv* array-length to *argc* 1620 "-b, --flag (default #f): %s\n" #( bflag ) fth-print 1621 "-f, --file (default #f): %s\n" #( ffile ) fth-print 1622 ; 1623 1624 Information and configuration: 1625 ((bbyyee)) ( n -- ) 1626 The exit hook fth_exit_hook will be called if set, all procs 1627 registered for at-exit will be executed and the current process will 1628 be terminated with exit code _n. 1629 ..ccffllaaggss ( -- ) 1630 Print compiler flags to compile libfth.so to other applications. 1631 ..lliibbss ( -- ) 1632 Print linker flags to link libfth.so to other applications. 1633 ..lloonngg--vveerrssiioonn ( -- ) 1634 Print long package version. 1635 ..mmeemmoorryy ( -- ) 1636 Print used and free dictionary cells. 1637 ..pprreeffiixx ( -- ) 1638 Print installation prefix path. 1639 ..vveerrssiioonn ( -- ) 1640 Print package version number. 1641 aatt--eexxiitt ( obj -- ) 1642 _o_b_j, an proc or xt, will be called by Fth's exit function. More 1643 than one calls to at-exit are possible, all procs or xts will be 1644 called in order. The stack effect of _o_b_j must be ( -- ). 1645 lambda: <{ -- }> "test.file" file-delete ; at-exit 1646 ccoonnffiigg--ccffllaaggss ( -- str ) 1647 Return compiler flags to compile libfth.so to other applications. 1648 ccoonnffiigg--lliibbss ( -- str ) 1649 Return linker flags to link libfth.so to other applications. 1650 ccoonnffiigg--pprreeffiixx ( -- str ) 1651 Return installation prefix path. 1652 ccoonnffiigguurree--aarrggss ( -- str ) 1653 Return configure arguments. 1654 vveerr ( -- addr len ) 1655 Return fth-version as a Forth string with addr len. 1656 ver type => "1.3.1 (19-Mar-2012) [i386-portbld-freebsd9.0]" 1657 1658 NNuummbbeerrss 1659 Number predicates: 1660 bbiiggnnuumm?? ( obj -- f ) 1661 ccoommpplleexx?? ( obj -- f ) 1662 eevveenn?? ( obj -- f ) 1663 eexxaacctt?? ( obj -- f ) 1664 ffiixxnnuumm?? ( obj -- f ) 1665 ffllooaatt?? ( obj -- f ) 1666 iinneexxaacctt?? ( obj -- f ) 1667 iinnff?? ( obj -- f ) 1668 iinntteeggeerr?? ( obj -- f ) 1669 lloonngg--lloonngg?? ( obj -- f ) 1670 nnaann?? ( obj -- f ) 1671 nnuummbbeerr?? ( obj -- f ) 1672 oodddd?? ( obj -- f ) 1673 pprriimmee?? ( obj -- f ) 1674 rraattiioo?? ( obj -- f ) 1675 rraattiioonnaall?? ( obj -- f ) alias for _r_a_t_i_o_? 1676 uulloonngg--lloonngg?? ( obj -- f ) 1677 uunnssiiggnneedd?? ( obj -- f ) 1678 Return #t if a given object is of corresponding type, otherwise #f. 1679 1680 Miscellaneous math functions: 1681 >>bbiiggnnuumm ( x -- b ) alias for _s_>_b 1682 Convert any number _x to a bignum object. 1683 >>cc ( x -- c ) 1684 Convert any number _x to a complex object. 1685 >>ccoommpplleexx ( r1 r2 -- c ) 1686 Return complex object with real _r_1 and image _r_2. 1687 >>lllloonngg ( x -- d ) alias fo _s_>_d 1688 Convert any number _x to a llong object. 1689 >>rraattiioo ( x -- q ) alias for _s_>_q 1690 Convert any number _x to a ratio object. 1691 ddeennoommiinnaattoorr ( x -- n ) 1692 Return denominator of _x or 1. 1693 eexxaacctt-->>iinneexxaacctt ( x -- r ) 1694 Convert _x to an inexact number. 1695 iimmaagg--rreeff ( x -- r ) 1696 Return the image part of Ar x . 1697 iimmaaggee--rreeff ( x -- r ) alias for _i_m_a_g_-_r_e_f 1698 iinneexxaacctt-->>eexxaacctt ( x -- n ) 1699 Convert _x to an exact number. 1700 iinnff ( -- inf ) 1701 Return Infinity. 1702 mmaakkee--bbiiggnnuumm ( x -- b ) 1703 Return a new bignum object. 1704 mmaakkee--lloonngg--lloonngg ( val -- d ) alias for _s_>_d 1705 Return new llong object (ficl2Integer) from _v_a_l. 1706 mmaakkee--ppoollaarr ( real theta -- c ) 1707 Return polar complex object from _r_e_a_l and _t_h_e_t_a. 1708 mmaakkee--rraattiioo ( num den -- q ) 1709 Return a new ratio object with numerator _n_u_m and denumerator _d_e_n. 1710 mmaakkee--rreeccttaanngguullaarr ( r1 r2 -- c ) alias for _>_c_o_m_p_l_e_x 1711 mmaakkee--uulloonngg--lloonngg ( val -- ud ) alias for _s_>_u_d 1712 Return new ullong object (ficl2Unsigned) from _v_a_l. 1713 nnaann ( -- NaN ) 1714 Return Not-A-Number. 1715 nnuummeerraattoorr ( x -- n ) 1716 Return numerator of _x or 0. 1717 rraattiioonnaalliizzee ( x err -- y ) 1718 Return inexact number within _e_r_r of _x. 1719 rreeaall--rreeff ( x -- r ) 1720 Return the real part of _x. 1721 1722 Pseudo randomize number functions: 1723 rraanndd--sseeeedd--rreeff ( -- seed ) 1724 Return content of the seed variable fth_randx. 1725 rraanndd--sseeeedd--sseett!! ( seed -- ) 1726 Set _s_e_e_d to the seed variable fth_randx. 1727 ffrraannddoomm ( r -- -r...+r ) 1728 Return pseudo randomized value between _-_r and _+_r. 1729 rraannddoomm ( r -- 0.0..r ) 1730 Return pseudo randomized value between 0.0 and _r. 1731 1732 These formatted number output functions will by convention add a space 1733 after the number: 1734 ..rr ( n1 n2 -- ) 1735 Print integer _n_1 in a right-adjusted field of _n_2 characters. 1736 17 3 .r => | 17 | 1737 cc.. ( c -- ) 1738 Print complex number _c. 1739 17.0+1.0i c. => |17.000000+1.000000i | 1740 dd.. ( d -- ) 1741 Print (Forth) double _d (ficl2Integer). 1742 17 d. => |17 | 1743 dd..rr ( d n -- ) 1744 Print (Forth) double _d (ficl2Integer) in a right-adjusted field of _n 1745 characters. 1746 17 3 d.r => | 17 | 1747 ff..rr ( r n -- ) 1748 Print float _r with _n digits after decimal point. 1749 17.0 3 f.r => |17.000 | 1750 bbnn.. ( b -- ) 1751 Print bignum number. 1752 17.0 bn. => |17 | 1753 qq.. ( q -- ) 1754 Print rational number. 1755 17.0 q. => |17/1 | 1756 uu..rr ( u n -- ) 1757 Print unsigned integer _u in a right-adjusted field of _n characters. 1758 17 3 u.r => | 17 | 1759 uudd.. ( ud -- ) 1760 Print (Forth) unsigned double _u_d (ficl2Unsigned). 1761 17 ud. => |17 | 1762 uudd..rr ( ud n -- ) 1763 Print (Forth) unsigned double _u_d (ficl2Unsigned) in a right-adjusted 1764 field of _n characters. 1765 17 3 ud.r => | 17 | 1766 uuff..rr ( r len-all len-after-comma -- ) 1767 Print float _r in a right-adjusted field of _l_e_n_-_a_l_l characters with 1768 _l_e_n_-_a_f_t_e_r_-_c_o_m_m_a digits. 1769 17.0 8 3 uf.r => | 17.000 | 1770 17.0 8 2 uf.r => | 17.00 | 1771 1772 Comparison: 1773 00<< ( n -- f ) 1774 00<<== ( n -- f ) 1775 00<<>> ( n -- f ) 1776 00== ( n -- f ) 1777 00==>> ( n -- f ) 1778 00>> ( n -- f ) 1779 nneeggaattiivvee?? ( n -- f ) alias for _0_< 1780 ppoossiittiivvee?? << ( n -- f ) alias for _0_>_= 1781 zzeerroo?? ( n -- f ) alias for _0_= 1782 Comparison between integer (ficlInteger) and zero. 1783 << ( n1 n2 -- f ) 1784 <<== ( n1 n2 -- f ) 1785 <<>> ( n1 n2 -- f ) 1786 == ( n1 n2 -- f ) 1787 ==>> ( n1 n2 -- f ) 1788 >> ( n1 n2 -- f ) 1789 nneeggaattiivvee?? ( n -- f ) alias for _0_< 1790 ppoossiittiivvee?? << ( n -- f ) alias for _0_>_= 1791 zzeerroo?? ( n -- f ) alias for _0_= 1792 Comparison between two integers (ficlInteger). 1793 uu<< ( u1 u2 -- f ) 1794 uu<<== ( u1 u2 -- f ) 1795 uu<<>> ( u1 u2 -- f ) 1796 uu== ( u1 u2 -- f ) 1797 uu==>> ( u1 u2 -- f ) 1798 uu>> ( u1 u2 -- f ) 1799 Comparison between two unsigned integers (ficlUnsigned). 1800 dd00<< ( d -- f ) 1801 dd00<<== ( d -- f ) 1802 dd00<<>> ( d -- f ) 1803 dd00== ( d -- f ) 1804 dd00>> ( d -- f ) 1805 dd00>>== ( d -- f ) 1806 ddnneeggaattiivvee?? ( d -- f ) alias for _d_0_< 1807 ddppoossiittiivvee?? << ( d -- f ) alias for _d_0_>_= 1808 ddzzeerroo?? ( d -- f ) alias for _d_0_= 1809 Comparison between long integer (ficl2Integer) and zero. _d can be 1810 any type of number but should fit in ficl2Integer. 1811 1 d0>= => #t 1812 1.0 d0< => #f 1813 dd<< ( d1 d2 -- f ) 1814 dd<<== ( d1 d2 -- f ) 1815 dd<<>> ( d1 d2 -- f ) 1816 dd== ( d1 d2 -- f ) 1817 dd>> ( d1 d2 -- f ) 1818 dd>>== ( d1 d2 -- f ) 1819 Comparison between two long integers (ficl2Integer). _d_1 and _d_2 can 1820 be any type of number but should fit in ficl2Integer. 1821 1 2.0 d< => #t 1822 1.0 2 d= => #f 1823 dduu<< ( ud1 ud2 -- f ) 1824 dduu<<== ( ud1 ud2 -- f ) 1825 dduu<<>> ( ud1 ud2 -- f ) 1826 dduu== ( ud1 ud2 -- f ) 1827 dduu>> ( ud1 ud2 -- f ) 1828 dduu>>== ( ud1 ud2 -- f ) 1829 Comparison between two long unsigned integers (ficl2Unsigned). _u_d_1 1830 and _u_d_2 can be any type of number but should fit in ficl2Unsigned. 1831 1 2.0 du< => #t 1832 1.0 2 du= => #f 1833 cc00<<>> ( c -- f ) 1834 cc00== ( c -- f ) 1835 Comparison between a complex number and zero. _c can be any type of 1836 number but should fit in ficlComplex. 1837 1.0+1.0i c0<> => #t 1838 0.0+0.0i c0= => #t 1839 1 c0= => #f 1840 cc<<>> ( c1 c2 -- f ) 1841 cc== ( c1 c2 -- f ) 1842 Comparison between two numbers. _c_1 and _c_2 can be any type of number 1843 but should fit in ficlComplex. 1844 1.0+1.0i 1i c= => #t 1845 1+0i 2.0 c<> => #t 1846 1 1+0i c= => #t 1847 bb00<< ( b -- f ) 1848 bb00<<== ( b -- f ) 1849 bb00<<>> ( b -- f ) 1850 bb00== ( b -- f ) 1851 bb00>> ( b -- f ) 1852 bb00>>== ( b -- f ) 1853 Comparison between an arbitrary precision number and zero. _b can be 1854 any type of number. 1855 bb<< ( b1 b2 -- f ) 1856 bb<<== ( b1 b2 -- f ) 1857 bb<<>> ( b1 b2 -- f ) 1858 bb== ( b1 b2 -- f ) 1859 bb>> ( b1 b2 -- f ) 1860 bb>>== ( b1 b2 -- f ) 1861 Comparison between two arbitrary precision big numbers. _b_1 and _b_2 1862 can be any type of number. 1863 qq00<< ( q -- f ) 1864 qq00<<== ( q -- f ) 1865 qq00<<>> ( q -- f ) 1866 qq00== ( q -- f ) 1867 qq00>> ( q -- f ) 1868 qq00>>== ( q -- f ) 1869 Comparison between an arbitrary precision rational number and zero. 1870 _q can be any type of number. 1871 qq<< ( q1 q2 -- f ) 1872 qq<<== ( q1 q2 -- f ) 1873 qq<<>> ( q1 q2 -- f ) 1874 qq== ( q1 q2 -- f ) 1875 qq>> ( q1 q2 -- f ) 1876 qq>>== ( q1 q2 -- f ) 1877 Comparison between two arbitrary precision rational numbers. _q_1 and 1878 _q_2 can be any type of number. 1879 1880 Convertion between number types: 1881 >>bbiiggnnuumm ( x -- b ) 1882 ff>>bb ( r -- b ) alias for _>_b_i_g_n_u_m 1883 ss>>bb ( n -- b ) alias for _>_b_i_g_n_u_m 1884 Convert any number to a bignum object (ficlBignum). 1885 >>cc ( x -- c ) 1886 ff>>cc ( r -- c ) alias for _>_c 1887 qq>>cc ( q -- c ) alias for _>_c 1888 ss>>cc ( n -- c ) alias for _>_c 1889 Convert any number to a complex object (ficlComplex). 1890 ff>>dd ( r -- d ) alias for _s_>_d 1891 ss>>dd ( n -- d ) 1892 Convert any number to a llong object (ficl2Integer). 1893 ff>>uudd ( r -- ud ) alias for _s_>_u_d 1894 ss>>uudd ( n -- ud ) 1895 Convert any number to an ullong object (ficl2Unsigned). 1896 bb>>ff ( b -- r ) alias for _s_>_f 1897 cc>>ff ( c -- r ) alias for _s_>_f 1898 dd>>ff ( d -- r ) alias for _s_>_f 1899 qq>>ff ( q -- r ) alias for _s_>_f 1900 ss>>ff ( n -- r ) 1901 Convert any number to a float object (ficlFloat). 1902 >>rraattiioo (( cc ---- qq )) aalliiaass ffoorr _s_>_q 1903 cc>>qq ( c -- q ) alias for _s_>_q 1904 ff>>qq ( r -- q ) alias for _s_>_q 1905 ss>>qq ( n -- q ) 1906 Convert any number to a ratio object (ficlRatio). 1907 bb>>ss ( b -- n ) alias for _f_>_s 1908 cc>>ss ( c -- n ) alias for _f_>_s 1909 dd>>ss ( d -- n ) alias for _f_>_s 1910 ff>>ss ( r -- n ) 1911 qq>>ss ( q -- n ) alias for _f_>_s 1912 Convert any number to Forth single word set number (ficlInteger). 1913 1914 Math functions: 1915 11++ ( n1 -- n2 ) 1916 11-- ( n1 -- n2 ) 1917 22++ ( n1 -- n2 ) 1918 22-- ( n1 -- n2 ) 1919 22** ( n1 -- n2 ) 1920 22// ( n1 -- n2 ) 1921 aabbss ( n1 -- n2 ) 1922 nneeggaattee ( n1 -- n2 ) 1923 One argument integer (ficlInteger) operators. 1924 ++ ( n1 n2 -- n3 ) 1925 -- ( n1 n2 -- n3 ) 1926 ** ( n1 n2 -- n3 ) 1927 // ( n1 n2 -- n3 ) 1928 mmaaxx ( n1 n2 -- n3 ) 1929 mmiinn ( n1 n2 -- n3 ) 1930 Two argument integer (ficlInteger) operators. 1931 dd22** ( d1 -- d2 ) 1932 dd22// ( d1 -- d2 ) 1933 ddaabbss ( d1 -- d2 ) 1934 ddnneeggaattee ( d1 -- d2 ) 1935 One argument long integer (ficl2Integer) operators. _d_1 can be any 1936 type of number but should fit in ficl2Integer. 1937 dd++ ( d1 d2 -- d3 ) 1938 dd-- ( d1 d2 -- d3 ) 1939 dd** ( d1 d2 -- d3 ) 1940 dd// ( d1 d2 -- d3 ) 1941 ddmmaaxx ( d1 d2 -- d3 ) 1942 ddmmiinn ( d1 d2 -- d3 ) 1943 Two argument long integer (ficl2Integer) operators. _d_1 and _d_2 can 1944 be any type of number but should fit in ficl2Integer. 1945 11//ff ( r1 -- r2 ) 1946 ff22** ( r1 -- r2 ) 1947 ff22// ( r1 -- r2 ) 1948 ffaabbss ( r1 -- r2 ) 1949 ffnneeggaattee ( r1 -- r2 ) 1950 One argument real number (ficlFloat) operators. _r_1 can be any type 1951 of number but should fit in ficlFloat. 1952 ff++ ( r1 r2 -- r3 ) 1953 ff-- ( r1 r2 -- r3 ) 1954 ff** ( r1 r2 -- r3 ) 1955 ff// ( r1 r2 -- r3 ) 1956 ffmmaaxx ( r1 r2 -- r3 ) 1957 ffmmiinn ( r1 r2 -- r3 ) 1958 Two argument real numbers (ficlFloat) operators. _r_1 and _r_2 can be 1959 any type of number but should fit in ficlFloat. 1960 ff**** ( r1 r2 -- r3 ) 1961 ffaabbss ( r1 -- r2 ) 1962 ffaaccooss ( r1 -- r2 ) 1963 ffaaccoosshh ( r1 -- r2 ) 1964 ffaalloogg ( r1 -- r2 ) 1965 ffaassiinn ( r1 -- r2 ) 1966 ffaassiinnhh ( r1 -- r2 ) 1967 ffaattaann ( r1 -- r2 ) 1968 ffaattaann22 ( r1 r2 -- r3 ) 1969 ffaattaannhh ( r1 -- r2 ) 1970 ffcceeiill ( r1 -- r2 ) 1971 ffccooss ( r1 -- r2 ) 1972 ffccoosshh ( r1 -- r2 ) 1973 ffeexxpp ( r1 -- r2 ) 1974 ffeexxppmm11 ( r1 -- r2 ) 1975 fflloogg ( r1 -- r2 ) 1976 fflloogg1100 ( r1 -- r2 ) 1977 fflloogg22 ( r1 -- r2 ) 1978 fflloogg11pp ( r1 -- r2 ) 1979 ffllooggpp11 ( r1 -- r2 ) alias for _f_l_o_g_1_p 1980 fflloooorr ( r1 -- r2 ) 1981 ffppooww ( r1 r2 -- r3 ) alias for _f_*_* 1982 ffrroouunndd ( r1 -- r2 ) 1983 ffssiinn ( r1 -- r2 ) 1984 ffssiinnccooss ( r1 -- r2 r3 ) 1985 ffssiinnhh ( r1 -- r2 ) 1986 ffssqqrrtt ( r1 -- r2 ) 1987 ffttaann ( r1 -- r2 ) 1988 ffttaannhh ( r1 -- r2 ) 1989 ffttrruunncc ( r1 -- r2 ) 1990 Math library functions for real numbers. ffssiinnccooss returns sin(r1) 1991 and cos(r1). _r_1 and probable second argument _r_2 can be any type of 1992 number but should fit in ficlFloat. 1993 11//cc ( c1 -- c2 ) 1994 cc** ( c1 c2 -- c3 ) 1995 cc**** ( c1 c2 -- c3 ) 1996 cc++ ( c1 c2 -- c3 ) 1997 cc-- ( c1 c2 -- c3 ) 1998 cc// ( c1 c2 -- c3 ) 1999 ccaabbss ( c1 -- c2 ) 2000 ccaabbss22 ( c1 -- c2 ) 2001 ccaaccooss ( c1 -- c2 ) 2002 ccaaccoosshh ( c1 -- c2 ) 2003 ccaarrgg ( c1 -- c2 ) 2004 ccaassiinn ( c1 -- c2 ) 2005 ccaassiinnhh ( c1 -- c2 ) 2006 ccaattaann ( c1 -- c2 ) 2007 ccaattaann22 ( c1 c2 -- c3 ) 2008 ccaattaannhh ( c1 -- c2 ) 2009 ccccooss ( c1 -- c2 ) 2010 ccccoosshh ( c1 -- c2 ) 2011 cceexxpp ( c1 -- c2 ) 2012 cclloogg ( c1 -- c2 ) 2013 cclloogg1100 ( c1 -- c2 ) 2014 ccoonnjj ( c1 -- c2 ) 2015 ccoonnjjuuggaattee ( c1 -- c2 ) alias for _c_o_n_j 2016 ccppooww ( c1 c2 -- c3 ) alias for _c_*_* 2017 ccssiinn ( c1 -- c2 ) 2018 ccssiinnhh ( c1 -- c2 ) 2019 ccssqqrrtt ( c1 -- c2 ) 2020 ccttaann ( c1 -- c2 ) 2021 ccttaannhh ( c1 -- c2 ) 2022 mmaaggnniittuuddee ( c1 -- c2 ) 2023 Math library functions for complex numbers. _c_1 and probable second 2024 argument _c_2 can be any type of number but should fit in ficlComplex. 2025 bb22** ( b1 -- b2 ) 2026 bb22// ( b1 -- b2 ) 2027 bbaabbss ( b1 -- b2 ) 2028 bbnneeggaattee ( b1 -- b2 ) 2029 One argument arbitrary precision bignum functions. _b_1 can be any 2030 type of number. 2031 bb++ ( b1 b2 -- b3 ) 2032 bb-- ( b1 b2 -- b3 ) 2033 bb** ( b1 b2 -- b3 ) 2034 bb// ( b1 b2 -- b3 ) 2035 bb**** ( b1 b2 -- b3 ) 2036 bbmmaaxx ( b1 b2 -- b3 ) 2037 bbmmiinn ( b1 b2 -- b3 ) 2038 bbppooww ( b1 b2 -- b3 ) alias for _b_*_* 2039 Two argument arbitrary precision bignum functions. _b_1 and _b_2 can be 2040 any type of number. 2041 bbggccdd ( x y -- z ) 2042 Greatest common divisor. _x and _y can be any type of number, _z is of 2043 type bignum. 2044 bbllccmm ( x y -- z ) 2045 Least common multiple. _x and _y can be any type of number, _z is of 2046 type bignum. 2047 bbrroooott ( b1 u -- b2 n ) 2048 Returns the integer part of the _u _t_h root of _b_1. On top of stack 1 2049 if result is exact, otherwise 0. 2050 bbssqqrrtt ( b1 -- b2 n ) 2051 Returns the integer part of the square root of _b_1. On top of stack 2052 1 if result is exact, otherwise 0. 2053 bbmmoodd ( b1 b2 -- b3 n ) 2054 _b_3 becomes _b_1 modulo _b_2. 2055 bb//mmoodd ( b1 b2 -- b3 b4 n ) 2056 Divide _b_1 by _b_2 where _b_3 becomes the remainder and _b_4 becomes the 2057 quotient. 2058 bbllsshhiifftt ( b1 n -- b2 ) 2059 bbrrsshhiifftt ( b1 n -- b2 ) 2060 Shifts arbitrary precision number _b_1 _n bits to left resp. right. _b_1 2061 can be any type of number while _n has to be an integer 2062 (ficlInteger). 2063 11//qq ( q1 -- q2 ) 2064 qqaabbss ( q1 -- q2 ) 2065 qqcceeiill ( q1 -- q2 ) 2066 qqfflloooorr ( q1 -- q2 ) 2067 qqnneeggaattee ( q1 -- q2 ) 2068 One argument arbitrary precision rational functions. _q_1 can be any 2069 type of number. 2070 qq++ ( q1 q2 -- q3 ) 2071 qq-- ( q1 q2 -- q3 ) 2072 qq** ( q1 q2 -- q3 ) 2073 qq// ( q1 q2 -- q3 ) 2074 qq**** ( q1 q2 -- q3 ) 2075 qqppooww ( q1 q2 -- q3 ) alias for _q_*_* 2076 Two argument arbitrary precision rational functions. _q_1 and _q_2 can 2077 be any type of number. 2078 ffeeggeettrroouunndd (( ---- nn )) 2079 ffeesseettrroouunndd (( nn ---- )) 2080 Return or set current floating-point rounding mode, one of: 2081 FFEE__TTOONNEEAARREESS 2082 FFEE__DDOOWWNNWWAARRDD 2083 FFEE__UUPPWWAARRDD 2084 FFEE__TTOOWWAARRDDZZEERROO 2085 See fenv(3), fegetround(3) and fesetround(3). 2086 2087 Constants: 2088 eeuulleerr e (~2.71828) 2089 hhaallff--ppii pi/2 (~1.5708) 2090 llnn--tteenn log(10) (~2.30259) 2091 llnn--ttwwoo log(2) (~0.693147) 2092 ppii pi (~3.14159) 2093 ssqqrrtt--ttwwoo sqrt(2) (~1.41421) 2094 ttwwoo--ppii pi*2 (~6.28319) 2095 2096 OObbjjeecctt ttyyppeess 2097 bbaacckkttrraaccee ( -- ) 2098 Print last word list from stack frame to error output. 2099 bbtt ( -- ) alias for _b_a_c_k_t_r_a_c_e 2100 ffrraammee--ddeepptthh ( -- n ) 2101 Internal global variable. Return the current frame depth. 2102 oobbjjeecctt--pprriinntt--lleennggtthh ( -- n ) 2103 Return the number of objects to print for objects like array, list, 2104 hash. Default value is 12. 2105 sseett--oobbjjeecctt--pprriinntt--lleennggtthh ( n -- ) 2106 Set number of objects to print for objects like array, list, hash to 2107 _n. If _n is negative, print all elements of a given object. 2108 ssttaacckk--lleevveell ( -- n ) alias for _f_r_a_m_e_-_d_e_p_t_h 2109 2110 Garbage collection words: 2111 ggcc--mmaarrkk ( obj -- obj ) 2112 Mark _o_b_j to protect it from garbage collection on next gc-run. 2113 ggcc--mmaarrkkeedd?? ( obj -- f ) 2114 Return #t if _o_b_j is an instance and mark flag is set. All new 2115 created objects have mark flag set. 2116 ggcc--ooffff ( -- ) 2117 Turn off garbage collection. The return code is meaningless in 2118 Forth. 2119 ggcc--oonn ( -- ) 2120 Turn on garbage collection. The return code is meaningless in 2121 Forth. 2122 ggcc--ppeerrmmaanneenntt--oobbjjeeccttss ( -- ary ) 2123 Return array of all permanent objects. 2124 ggcc--ppeerrmmaanneenntt?? ( obj -- f ) 2125 Return #t if _o_b_j is an instance and permanent flag is set like 2126 constants. 2127 ggcc--pprrootteecctt ( obj -- obj ) 2128 Protect _o_b_j from garbage collection until gc-unprotect. 2129 ggcc--pprrootteecctteedd--oobbjjeeccttss ( -- ary ) 2130 Return array of all protected objects. 2131 ggcc--pprrootteecctteedd?? ( obj -- f ) 2132 Return #t if _o_b_j is an instance and protected flag is set. 2133 ggcc--rruunn ( -- ) 2134 Run garbage collection immediately. 2135 ggcc--ssttaattss ( -- ) 2136 Print garbage collection statistics. 2137 permanent 2138 permanent protected objects like constants 2139 protected 2140 temporary protected objects like gc-protected 2141 marked 2142 marked to protect from next freeing 2143 freed 2144 freed objects 2145 insts 2146 all other nonfreed objects 2147 buffer 2148 size of entire allocated buffer-array 2149 gc stack 2150 stack frame level 2151 ggcc--uunnmmaarrkk ( obj -- obj ) 2152 Unmark _o_b_j to unprotect it from garbage collection on next gc-run. 2153 ggcc--uunnpprrootteecctt ( obj -- obj ) 2154 Unprotect _o_b_j from garbage collection. 2155 2156 Object type and instance words: 2157 iinnssttaannccee--ggeenn--rreeff ( obj -- gen ) 2158 Return GEN-struct of _o_b_j. 2159 iinnssttaannccee--oobbjj--rreeff ( obj -- gen ) 2160 Return object type of _o_b_j. 2161 iinnssttaannccee--ooff?? ( obj type -- f ) 2162 Return #t if _o_b_j is an instance of _t_y_p_e, otherwise #f. 2163 iinnssttaannccee?? ( obj -- f ) 2164 Return #t if _o_b_j is an instance, otherwise #f. 2165 mmaakkee--iinnssttaannccee ( gen obj -- instance ) 2166 Return new instance of Object type _o_b_j with _g_e_n wrapped in. 2167 mmaakkee--oobbjjeecctt--ttyyppee ( name -- object-type ) 2168 Create new object type _n_a_m_e. Add _n_a_m_e to feature environment list, 2169 create a constant fth-_n_a_m_e of object-type and return new object-type 2170 _n_a_m_e. The new created object-type can be used to bind functions to 2171 it. 2172 oobbjjeecctt--ttyyppee--rreeff ( obj -- struct ) 2173 Return object struct of object-type _o_b_j. 2174 oobbjjeecctt--ttyyppee?? ( obj -- f ) 2175 Return #t if _o_b_j is an Object type, otherwise #f. 2176 oobbjjeecctt--ttyyppeess ( -- ary ) 2177 Return array of all object names known to the system. 2178 2179 Object set words: 2180 sseett--oobbjjeecctt-->>aarrrraayy ( xt obj -- ) 2181 Set _x_t as oobbjjeecctt-->>aarrrraayy function for _o_b_j type. 2182 sseett--oobbjjeecctt-->>ssttrriinngg ( xt obj -- ) 2183 Set _x_t as oobbjjeecctt-->>ssttrriinngg function for _o_b_j type. 2184 sseett--oobbjjeecctt--aappppllyy ( xt obj arity -- ) 2185 Set _x_t as oobbjjeecctt--aappppllyy function for _o_b_j type. 2186 sseett--oobbjjeecctt--ccooppyy ( xt obj -- ) 2187 Set _x_t as oobbjjeecctt--ccooppyy function for _o_b_j type. 2188 sseett--oobbjjeecctt--dduummpp ( xt obj -- ) 2189 Set _x_t as oobbjjeecctt--dduummpp function for _o_b_j type. 2190 sseett--oobbjjeecctt--eeqquuaall--pp ( xt obj -- ) 2191 Set _x_t as oobbjjeecctt--eeqquuaall?? function for _o_b_j type. 2192 sseett--oobbjjeecctt--ffrreeee ( xt obj -- ) 2193 Set _x_t as gc free function for _o_b_j type. 2194 sseett--oobbjjeecctt--iinnssppeecctt ( xt obj -- ) 2195 Set _x_t as oobbjjeecctt--iinnssppeecctt function for _o_b_j type. 2196 sseett--oobbjjeecctt--lleennggtthh ( xt obj -- ) 2197 Set _x_t as oobbjjeecctt--lleennggtthh function for _o_b_j type. 2198 sseett--oobbjjeecctt--mmaarrkk ( xt obj -- ) 2199 Set _x_t as gc mark function for _o_b_j type. 2200 sseett--oobbjjeecctt--vvaalluuee--rreeff ( xt obj -- ) 2201 Set _x_t as oobbjjeecctt--rreeff function for _o_b_j type. 2202 sseett--oobbjjeecctt--vvaalluuee--sseett ( xt obj -- ) 2203 Set _x_t as oobbjjeecctt--sseett!! function for _o_b_j type. 2204 2205 General object words 2206 ..iinnssppeecctt ( obj -- ) 2207 Print inspect string of _o_b_j. 2208 ..oobbjjeecctt--nnaammee ( obj -- ) 2209 Print object name of _o_b_j to current stdout. 2210 aappppllyy ( obj args -- result ) alias for _o_b_j_e_c_t_-_a_p_p_l_y 2211 ccyyccllee--rreeff ( obj -- val ) 2212 Return value at current cycle-index of _o_b_j and increment cycle- 2213 index. Cycle through content of _o_b_j from first to last entry and 2214 start again at the beginning etc. 2215 ccyyccllee--sseett!! ( obj value -- ) 2216 Store _v_a_l_u_e at current cycle-index of _o_b_j and increment cycle-index. 2217 Cycle through content of _o_b_j from first to last entry and start 2218 again at the beginning etc. 2219 ccyyccllee--ssttaarrtt!! ( obj index -- ) 2220 Set cycle-index of _o_b_j to _i_n_d_e_x. 2221 ccyyccllee--ssttaarrtt00 ( obj -- ) 2222 Set cycle-index of _o_b_j to zero. 2223 ccyyccllee--ssttaarrtt@@ ( obj -- index ) 2224 Return current cycle-index of _o_b_j. 2225 ddeetteecctt ( obj key -- value ) alias for _o_b_j_e_c_t_-_f_i_n_d 2226 eemmppttyy?? ( obj -- f ) alias for _o_b_j_e_c_t_-_e_m_p_t_y_? 2227 eeqquuaall?? ( obj1 obj2 -- f ) alias for _o_b_j_e_c_t_-_e_q_u_a_l_? 2228 ffiirrsstt--rreeff ( obj -- val ) 2229 Return first element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if 2230 length of _o_b_j is less than 1. 2231 ffiirrsstt--sseett!! ( obj value -- ) 2232 Store _v_a_l_u_e to first element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e 2233 exception if length of _o_b_j is less than 1. 2234 hhaasshh--iidd ( obj -- id ) 2235 Return hash id computed from string representation of _o_b_j. Objects 2236 with the same content have the same id. 2237 iinnddeexx ( obj key -- index ) alias for _o_b_j_e_c_t_-_i_n_d_e_x 2238 llaasstt--rreeff ( obj -- val ) 2239 Return last element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if 2240 length of _o_b_j is less than 1. 2241 llaasstt--sseett!! ( obj value -- ) 2242 Store _v_a_l_u_e to last element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception 2243 if length of _o_b_j is less than 1. 2244 lleennggtthh ( obj -- len ) alias for _o_b_j_e_c_t_-_l_e_n_g_t_h 2245 mmeemmbbeerr?? ( obj key -- f ) alias for _o_b_j_e_c_t_-_m_e_m_b_e_r_? 2246 oobbjjeecctt-->>aarrrraayy ( obj -- ary ) 2247 Return _o_b_j as array. 2248 oobbjjeecctt-->>ssttrriinngg ( obj -- str ) 2249 Return string representation of _o_b_j. 2250 oobbjjeecctt--aappppllyy ( obj args -- result ) 2251 Run apply on _o_b_j with _a_r_g_s as arguments. _a_r_g_s can be an array of 2252 arguments or a single argument. The number of _a_r_g_s must fit apply's 2253 definition. The next two examples require each 1 argument: 2254 fth_set_object_apply(vct_tag, vct_ref, 1, 0, 0); /* C */ 2255 <'> enved-ref fth-enved 1 set-object-apply \ Forth 2256 oobbjjeecctt--ccooppyy ( obj1 -- obj2 ) 2257 Return copy of _o_b_j_1. Copy any element if _o_b_j_1 is an instance. 2258 oobbjjeecctt--ddeebbuugg--hhooookk ( obj -- hook ) 2259 Return debug-hook member of _o_b_j if there is any, otherwise #f. The 2260 hook has the stack effect ( inspect-string obj -- new-str ). Every 2261 object can set this hook. If set, it will be called on inspecting 2262 the object with the inspect string as first argument. If there are 2263 more than one hook procedures, all of them will be called feeded 2264 with the new string previously returned. 2265 #( 0 1 ) value ary 2266 ary .inspect => #<array[2]: #<fixnum: 0> #<fixnum: 1>> 2267 ary object-debug-hook lambda: <{ str obj -- new-str }> 2268 "debug-inspect: %s" #( obj ) string-format 2269 ; add-hook! 2270 ary .inspect => #<debug-inspect: #( 0 1 )> 2271 ary object-debug-hook hook-clear 2272 ary .inspect => #<array[2]: #<fixnum: 0> #<fixnum: 1>> 2273 oobbjjeecctt--dduummpp ( obj -- str ) 2274 Return dump string of _o_b_j which one can eval to get the object back. 2275 oobbjjeecctt--eemmppttyy?? ( obj -- f ) 2276 Return #t if length of _o_b_j is zero, otherwise #f. 2277 oobbjjeecctt--eeqquuaall?? ( obj1 obj2 -- f ) 2278 Return #t if _o_b_j_1 and _o_b_j_2 have equal content, otherwise #f. 2279 oobbjjeecctt--ffiinndd ( obj key -- value ) 2280 Search for _k_e_y in _o_b_j and return corresponding value or #f if not 2281 found. 2282 oobbjjeecctt--iidd ( obj -- id ) 2283 Return object id of _o_b_j, a uniq number. 2284 oobbjjeecctt--iinnddeexx ( obj key -- index ) 2285 Search for _k_e_y in _o_b_j and return index or -1 if not found. 2286 oobbjjeecctt--iinnssppeecctt ( obj -- str ) 2287 Return inspect string of _o_b_j. 2288 oobbjjeecctt--lleennggtthh ( obj -- len ) 2289 Return length of _o_b_j. 2290 oobbjjeecctt--mmeemmbbeerr?? ( obj key -- f ) 2291 Return #t if _k_e_y is present in _o_b_j, otherwise #f. 2292 oobbjjeecctt--nnaammee ( obj -- name ) 2293 Return object type name of OBJ as a string. 2294 oobbjjeecctt--rraannggee?? ( obj index -- f ) 2295 Return #t if _i_n_d_e_x is in range of _o_b_j, otherwise #f. If _i_n_d_e_x is 2296 negative, return #f. 2297 oobbjjeecctt--rreeff ( obj index -- val ) 2298 Return value at _i_n_d_e_x from _o_b_j. If _o_b_j is of a type which can have 2299 multiple elements, an array for example, return value at _i_n_d_e_x. If 2300 _o_b_j is of a type which consists of only one element, a fixnum for 2301 example, ignore _i_n_d_e_x and return _o_b_j itself. 2302 oobbjjeecctt--sseett!! ( obj index value -- ) 2303 Set _v_a_l_u_e at _i_n_d_e_x to _o_b_j. If _o_b_j is of a type which can have 2304 multiple elements, an array for example, set _v_a_l_u_e at position 2305 _i_n_d_e_x. If _o_b_j is of a type which consists of only one element, a 2306 fixnum for example, do nothing. 2307 oobbjjeecctt--sseett**!! ( obj index value -- ) 2308 Multiply _v_a_l_u_e to value at _i_n_d_e_x of _o_b_j. Value may be any number 2309 (ficlInteger, ficlFloat, ficlRatio or ficlComplex). 2310 oobbjjeecctt--sseett++!! ( obj index value -- ) 2311 Add _v_a_l_u_e to value at _i_n_d_e_x of _o_b_j. Value may be any number 2312 (ficlInteger, ficlFloat, ficlRatio or ficlComplex). 2313 oobbjjeecctt--sseett--!! ( obj index value -- ) 2314 Subtract _v_a_l_u_e from value at _i_n_d_e_x of _o_b_j. Value may be any number 2315 (ficlInteger, ficlFloat, ficlRatio or ficlComplex). 2316 oobbjjeecctt--sseett//!! ( obj index value -- ) 2317 Divide value at _i_n_d_e_x of _o_b_j by _v_a_l_u_e. Value may be any number 2318 (ficlInteger, ficlFloat, ficlRatio or ficlComplex). 2319 oobbjjeecctt--ssoorrtt ( obj cmp-xt -- ary ) 2320 Convert _o_b_j to an array, sort and return it. _c_m_p_-_x_t compares two 2321 items A and B and should return a negative integer if A < B, 0 if A 2322 == B, and a positive integer if A > B. 2323 : numb-sort { val1 val2 -- n } 2324 val1 val2 < if 2325 -1 2326 else 2327 val1 val2 > if 2328 1 2329 else 2330 0 2331 then 2332 then 2333 ; 2334 #( 6 2 8 1 ) <'> numb-sort object-sort => #( 1 2 6 8 ) 2335 rraannggee?? ( obj index -- f ) alias for _o_b_j_e_c_t_-_r_a_n_g_e_? 2336 sseeccoonndd--rreeff ( obj -- val ) 2337 Return second element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if 2338 length of _o_b_j is less than 2. 2339 sseeccoonndd--sseett!! ( obj value -- ) 2340 Store _v_a_l_u_e to second element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e 2341 exception if length of _o_b_j is less than 2. 2342 ssoorrtt ( obj cmp-xt -- ary ) alias for _o_b_j_e_c_t_-_s_o_r_t 2343 tthhiirrdd--rreeff ( obj -- val ) 2344 Return third element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if 2345 length of _o_b_j is less than 3. 2346 tthhiirrdd--sseett!! ( obj value -- ) 2347 Store _v_a_l_u_e to third element of _o_b_j. Raise an _o_u_t_-_o_f_-_r_a_n_g_e 2348 exception if length of _o_b_j is less than 3. 2349 xxmmoobbjj?? ( obj -- f ) 2350 Return #t if _o_b_j is an XmObj (xm.c), otherwise #f. It is a very 2351 special Snd XM test. See snd(1) for more information. 2352 2353 Predicates: 2354 bboooolleeaann?? ( obj -- f ) 2355 Return #t if _o_b_j is #t or #f, otherwise #f. 2356 ffaallssee?? ( obj -- f ) 2357 Return #t if _o_b_j is #f, otherwise #f. 2358 nniill?? ( obj -- f ) 2359 Return #t if _o_b_j is nil, otherwise #f. 2360 ttrruuee?? ( obj -- f ) 2361 Return #t if _o_b_j is #t, otherwise #f. 2362 uunnddeeff?? ( obj -- f ) 2363 Return #t if _o_b_j is undef, otherwise #f. 2364 2365 PPoorrttss 2366 mmaakkee--ssoofftt--iinnppuutt--ppoorrtt ( :key args -- prt ) 2367 Return new input soft port IO object with corresponding procs. Not 2368 all procs are required. Recognized keyword options: 2369 ::cclloossee ( -- ) 2370 Proc for closing soft port. 2371 ::fflluusshh ( -- ) 2372 Proc for flushing port buffer. 2373 ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_" 2374 Name for IO object, default is "soft-port". 2375 ::rreeaadd--cchhaarr ( -- c ) 2376 Proc for reading one character. 2377 ::rreeaadd--lliinnee ( -- line ) 2378 Proc for reading one line. 2379 Input example, *stdin* IO object is preserved for later use: 2380 :port-name "sndin" 2381 :read-char lambda: <{ -- c }> *stdin* io-getc ; 2382 :read-line lambda: <{ -- line }> *stdin* io-read ; 2383 make-soft-port set-*stdin* value stdin-io 2384 mmaakkee--ssoofftt--oouuttppuutt--ppoorrtt ( :key args -- prt ) 2385 Return new output soft port IO object with corresponding procs. Not 2386 all procs are required. Recognized keyword options: 2387 ::cclloossee ( -- ) 2388 Proc for closing soft port. 2389 ::fflluusshh ( -- ) 2390 Proc for flushing port buffer. 2391 ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_" 2392 Name for IO object, default is "soft-port". 2393 ::wwrriittee--cchhaarr ( c -- ) 2394 Proc for writing one character. 2395 ::wwrriittee--lliinnee ( line -- ) 2396 Proc for writing one line. 2397 Output example, *stdout* IO object is preserved for later use: 2398 :port-name "sndout" 2399 :write-char lambda: <{ c -- }> c snd-print .stdout ; 2400 :write-line lambda: <{ line -- }> line snd-print .stdout ; 2401 make-soft-port set-*stdout* value stdout-io 2402 mmaakkee--ssoofftt--ppoorrtt ( :key args -- prt ) 2403 Return new soft port IO object with corresponding procs. Not all 2404 procs are required. Recognized keyword options: 2405 ::cclloossee ( -- ) 2406 Proc for closing soft port. 2407 ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w 2408 For read-only use constant rr//oo, for write-only use 2409 constant ww//oo and for read-write use constant rr//ww. 2410 ::fflluusshh ( -- ) 2411 Proc for flushing port buffer. 2412 ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_" 2413 Name for IO object, default is "soft-port". 2414 ::rreeaadd--cchhaarr ( -- c ) 2415 Proc for reading one character. 2416 ::rreeaadd--lliinnee ( -- line ) 2417 Proc for reading one line. 2418 ::wwrriittee--cchhaarr ( c -- ) 2419 Proc for writing one character. 2420 ::wwrriittee--lliinnee ( line -- ) 2421 Proc for writing one line. 2422 Input example, *stdin* IO object is preserved for later use: 2423 :port-name "sndin" 2424 :read-char lambda: <{ -- c }> *stdin* io-getc ; 2425 :read-line lambda: <{ -- line }> *stdin* io-read ; 2426 make-soft-port set-*stdin* value stdin-io 2427 Output example, *stdout* IO object is preserved for later use: 2428 :port-name "sndout" 2429 :write-char lambda: <{ c -- }> c snd-print .stdout ; 2430 :write-line lambda: <{ line -- }> line snd-print .stdout ; 2431 make-soft-port set-*stdout* value stdout-io 2432 ppoorrtt-->>ssttrriinngg ( prt -- str ) 2433 Return content of _p_r_t object as string if available, otherwise #f. 2434 ppoorrtt--cclloossee ( prt -- ) 2435 File and IO ports close their streams, other kind of ports do 2436 nothing. 2437 ppoorrtt--cclloosseedd?? ( prt -- f ) 2438 Return #t if _i_o object is closed, otherwise #f. 2439 ppoorrtt--ddiissppllaayy ( prt obj -- ) 2440 Write the string representation of _o_b_j to _p_r_t object. If _p_r_t is #f, 2441 write to current output port (stout). 2442 ppoorrtt--fflluusshh ( prt -- ) 2443 File and IO ports flush their streams, other kind of ports do 2444 nothing. 2445 ppoorrtt--ggeettcc ( prt -- c ) 2446 Return next character from _p_r_t IO object. If _p_r_t is #f, read from 2447 current input port (stdin). 2448 ppoorrtt--ggeettss ( prt -- str ) 2449 Return one line from _p_r_t IO object. If _p_r_t is #f, read from current 2450 input port (stdin). 2451 ppoorrtt--iinnppuutt?? ( obj -- f ) 2452 Return #t if _o_b_j is an input IO object or #f, otherwise #f. 2453 ppoorrtt--oouuttppuutt?? ( obj -- f ) 2454 Return #t if _o_b_j is an output IO object or #f, otherwise #f. 2455 ppoorrtt--ppuuttcc ( prt c -- ) 2456 Write character _c to _p_r_t IO object. If _p_r_t is #f, write to current 2457 output port (stout). 2458 ppoorrtt--ppuuttss ( prt str -- ) 2459 Write _s_t_r to _p_r_t IO object. If _p_r_t is #f, write to current output 2460 port (stout). 2461 ppoorrtt--ppuuttss--ffoorrmmaatt ( prt fmt fmt-args -- ) 2462 Write string built from _f_m_t and array _f_m_t_-_a_r_g_s to _p_r_t IO object. If 2463 _p_r_t is #f, write to current output port (stdout). For example, 2464 write "hello, world" to stdout (#f) port: 2465 #f "hello, %s" #( "world" ) port-puts-format 2466 => hello, world 2467 ppoorrtt--rreeaadd ( prt -- str ) alias for _p_o_r_t_-_g_e_t_s 2468 ppoorrtt--wwrriittee ( prt str -- ) alias for _p_o_r_t_-_p_u_t_s 2469 ppoorrtt--wwrriittee--ffoorrmmaatt ( prt fmt fmt-args -- ) alias for _p_o_r_t_-_p_u_t_s_-_f_o_r_m_a_t 2470 ppoorrtt?? ( obj -- f ) 2471 Return #t if _o_b_j is an IO object or #f, otherwise #f. 2472 2473 The following words recognize these options: 2474 ::ffiilleennaammee _s_t_r_i_n_g 2475 ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w 2476 For read-only use constant rr//oo, for write-only use 2477 constant ww//oo and for read-write use constant rr//ww. 2478 ::ccoommmmaanndd _s_t_r_i_n_g _| _a_r_r_a_y_-_o_f_-_s_t_r_i_n_g_s 2479 ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w 2480 For read-only use constant rr//oo, for write-only use 2481 constant ww//oo and for read-write use constant rr//ww. 2482 ::ssoocckkeett _s_t_r_i_n_g 2483 ::ddoommaaiinn _d_o_m_a_i_n (AF_INET | AF_UNIX) 2484 ::ppoorrtt _p_o_r_t (default 1024) 2485 ::ssoofftt--ppoorrtt _s_t_r_i_n_g 2486 ::cclloossee ( -- ) 2487 Proc for closing soft port. 2488 ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w 2489 For read-only use constant rr//oo, for write-only use 2490 constant ww//oo and for read-write use constant rr//ww. 2491 ::fflluusshh ( -- ) 2492 Proc for flushing port buffer. 2493 ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_" 2494 Name for IO object, default is "soft-port". 2495 ::rreeaadd--cchhaarr ( -- c ) 2496 Proc for reading one character. 2497 ::rreeaadd--lliinnee ( -- line ) 2498 Proc for reading one line. 2499 ::wwrriittee--cchhaarr ( c -- ) 2500 Proc for writing one character. 2501 ::wwrriittee--lliinnee ( line -- ) 2502 Proc for writing one line. 2503 wwiitthh--eerrrroorr--ttoo--ppoorrtt ( obj :key args -- ) 2504 Open IO object for output and point IO to _*_s_t_d_e_r_r_*. If _o_b_j is a 2505 string, write string to IO object, otherwise execute _o_b_j as proc or 2506 xt with stack effect ( -- ). Close IO object. _*_s_t_d_e_r_r_* will be 2507 reset to its previous value. 2508 lambda: <{ -- }> 2509 "hello\n" .stderr 2510 ; :filename "file.test" with-error-to-port 2511 % cat test.file 2512 hello 2513 % 2514 "" value s 2515 lambda: <{ -- }> 2516 *stderr* "hello" io-write 2517 ; :string s with-error-to-port 2518 s => "hello" 2519 "file.test" file-delete 2520 "hello\n" :filename "file.test" with-error-to-port 2521 % cat file.test 2522 hello 2523 % 2524 wwiitthh--iinnppuutt--ffrroomm--ppoorrtt ( obj :key args -- str ) 2525 Open IO object for input and point IO to _*_s_t_d_i_n_*. If _o_b_j is _n_i_l, 2526 read first line from IO object, otherwise execute _o_b_j as proc or xt 2527 with stack effect ( -- str ). Close IO object and return resulting 2528 string. _*_s_t_d_i_n_* will be reset to its previous value. 2529 % cat file.test 2530 hello 2531 % 2532 lambda: <{ -- str }> 2533 *stdin* io-read 2534 ; :filename "file.test" with-input-from-port => "hello\n" 2535 "hello" value s 2536 lambda: <{ -- str }> 2537 *stdin* io-read 2538 ; :string s with-input-from-port => "hello" 2539 nil :filename "file.test" with-input-from-port => "hello" 2540 wwiitthh--iinnppuutt--ppoorrtt ( obj :key args -- str ) 2541 Open IO object for input. If _o_b_j _i_s _n_i_l, read first line from IO 2542 object, otherwise execute _o_b_j as a proc or xt with stack effect ( io 2543 -- str ). Close IO object and return resulting string. 2544 % cat file.test 2545 hello 2546 % 2547 lambda: <{ io -- str }> 2548 io io-read 2549 ; :filename "file.test" with-input-port => "hello\n" 2550 "hello" value s 2551 lambda: <{ io -- str }> 2552 io io-read 2553 ; :string s with-input-port => "hello" 2554 nil :filename "file.test" with-input-port => "hello\n" 2555 wwiitthh--oouuttppuutt--ppoorrtt ( obj :key args -- ) 2556 Open IO object for output. If _o_b_j is a string, write string to IO 2557 object, otherwise execute _o_b_j as proc or xt with stack effect ( io 2558 -- ). Close IO object. 2559 lambda: <{ io -- }> 2560 io "hello\n" io-write 2561 ; :filename "file.test" with-output-port 2562 % cat file.test 2563 hello 2564 % 2565 "" value s 2566 lambda: <{ io -- }> 2567 io "hello" io-write 2568 ; :string s with-output-port 2569 s => "hello" 2570 "file.test" file-delete 2571 "hello\n" :filename "file.test" with-output-port 2572 % cat file.test 2573 hello 2574 % 2575 wwiitthh--oouuttppuutt--ttoo--ppoorrtt ( obj :key args -- ) 2576 Open IO object for output and point IO to _*_s_t_d_o_u_t_*. If _o_b_j is a 2577 string, write string to IO object, otherwise execute _o_b_j as proc or 2578 xt with stack effect ( -- ). Close IO object. _*_s_t_d_o_u_t_* will be 2579 reset to its previous value. 2580 lambda: <{ -- }> 2581 ." hello" cr 2582 ; :filename "file.test" with-output-to-port 2583 % cat test.file 2584 hello 2585 % 2586 "" value s 2587 lambda: <{ -- }> 2588 *stdout* "hello" io-write 2589 ; :string s with-output-to-port 2590 s => "hello" 2591 "file.test" file-delete 2592 "hello\n" :filename "file.test" with-output-to-port 2593 % cat file.test 2594 hello 2595 % 2596 2597 PPrrooccss aanndd XXttss 2598 *filename* 2599 Current filename. 2600 *lineno* 2601 Current line number. 2602 ..pprroocc ( prc -- ) 2603 Print proc object _p_r_c to current output. 2604 <<''sseett>> ( "name" -- set-name|#f ) 2605 Parse _n_a_m_e and search for word _s_e_t_-_n_a_m_e. Return xt of _s_e_t_-_n_a_m_e or 2606 #f if not found. 2607 <'set> object-print-length => set-object-print-length 2608 <<{{ ( -- ) 2609 Turn current colon definition in a proc object. Takes tokens up to 2610 closing `}>' as local variables, `--' start a comment ignoring rest 2611 to closing `}>'. In addition to other local variable words like {{ }} 2612 and {{{{ }}}} this form handles two keywords, ::kkeeyy and ::ooppttiioonnaall. 2613 Variable names are taken from keyword and optional names. This word 2614 can span over more than one lines but without empty lines or 2615 comments in between. If :key and :optional is used together, :key 2616 must come first. All keyword and optional variables must have 2617 default values. This word is immediate and compile only and can 2618 only be used in word definitions. 2619 : optkey-test <{ a b c 2620 :key d 10 e 20 :optional f 30 g 40 -- ary }> 2621 #( a b c d e f g ) 2622 ; 2623 1 2 3 optkey-test => #( 1 2 3 10 20 30 40 ) 2624 :d 11 1 :e 22 2 3 4 optkey-test => #( 1 2 3 11 22 4 40 ) 2625 <<{{}}>> ( -- ) 2626 Turn current colon definition in a proc object. This word is 2627 immediate and compile only and can only be used in word definitions. 2628 : we-dont-need-args <{}> ; 2629 <'> we-dont-need-args proc? => #t 2630 ddeeffiinneedd?? ( "name" -- f ) 2631 Return #t if _n_a_m_e is defined in the dictionary, otherwise #f. 2632 defined? 10 => #f 2633 defined? nil => #t 2634 defined? + => #t 2635 ddoocc"" ( <ccc>" -- ) 2636 Add input buffer to next double quote character `"' to documentation 2637 of current word. Escape double quote character with backslash if 2638 required in documentation. It is not necessary to repeat the stack 2639 effect if it already exist in the word definition. This word is 2640 immediate and compile only and can only be used in word definitions. 2641 : new-word ( -- ) 2642 doc" our documentation may contain \ 2643 \"double quotes\". \ 2644 Escape them with a backslash." 2645 \ we do nothing 2646 ; 2647 help new-word => new-word ( -- ) our documentation may 2648 contain qdouble quotes". Escape them with a backslash. 2649 ddooccuummeennttaattiioonn--rreeff ( obj -- str ) 2650 Return documentation string of _o_b_j (Forth word, object or topic) or 2651 #f. 2652 ddooccuummeennttaattiioonn--sseett!! ( obj str -- ) 2653 Set documentation of _o_b_j (Forth word, object or topic) to _s_t_r. 2654 ggeett--ffuunncc--nnaammee ( -- name ) 2655 Return name of current xt in word definition as string. This word 2656 is immediate and compile only and can only be used in word 2657 definitions. 2658 : new-word 2659 get-func-name .$ 2660 space 2661 10 2662 ; 2663 new-word => new-word 10 2664 ggeett--ooppttaarrgg ( req def -- val ) 2665 Return either default value _d_e_f or a value found on stack. _r_e_q is 2666 the sum of required and following optional arguments. It simulates 2667 the :optional keyword in Lisp/Scheme. 2668 : optarg-test ( a b c=33 d=44 e=55 -- ary ) 2669 4 55 get-optarg { e } 2670 3 44 get-optarg { d } 2671 2 33 get-optarg { c } 2672 { a b } 2673 #( a b c d e ) 2674 ; 2675 1 2 optarg-test => #( 1 2 33 44 55 ) 2676 1 2 3 4 optarg-test => #( 1 2 3 4 55 ) 2677 1 2 3 4 5 6 7 optarg-test => 1 2 #( 3 4 5 6 7 ) 2678 ggeett--ooppttaarrggss ( lst req -- vals ) 2679 The plural form of get-optarg. _a_r_g_s is an array with default 2680 values, _r_e_q is number of required arguments. Return _r_e_q + _a_r_g_s 2681 length values on stack, either default ones or from stack. 2682 : optargs-test ( a b c=33 d=44 e=55 -- ary ) 2683 #( 33 44 55 ) 2 get-optargs { a b c d e } 2684 #( a b c d e ) 2685 ; 2686 1 2 optargs-test => #( 1 2 33 44 55 ) 2687 1 2 3 4 optargs-test => #( 1 2 3 4 55 ) 2688 1 2 3 4 5 6 7 optargs-test => 1 2 #( 3 4 5 6 7 ) 2689 ggeett--ooppttkkeeyy ( key def -- val ) 2690 Return either default value _d_e_f or a value found on stack determined 2691 by keyword _k_e_y. It simulates the :key keyword in Lisp/Scheme. 2692 : optkey-test ( start dur keyword-args -- ary ) 2693 :frequency 440.0 get-optkey { freq } 2694 :initial-phase pi get-optkey { phase } 2695 { start dur } 2696 #( start dur freq phase ) 2697 ; 2698 0 1 optkey-test => #( 0.0 1.0 440.0 3.14159 ) 2699 0 2 :frequency 330.0 optkey-test => #( 0.0 2.0 330.0 3.14159 ) 2700 ggeett--ooppttkkeeyyss ( ary req -- vals ) 2701 The plural form of get-optkey. _a_r_y is an array of key-value pairs, 2702 _r_e_q is number of required arguments. Return _r_e_q + _a_r_y length / 2 2703 values on stack, either default ones or from stack. 2704 : optkeys-test ( start dur keyword-args -- ary ) 2705 #( :frequency 440.0 2706 :initial-phase pi ) 2707 2 get-optkeys { start dur freq phase } 2708 #( start dur freq phase ) 2709 ; 2710 0 1 optkeys-test => #( 0.0 1.0 440.0 3.14159 ) 2711 0 2 :frequency 330.0 optkeys-test => #( 0.0 2.0 330.0 3.14159 ) 2712 hheellpp ( "name" -- ) 2713 Print documentation of _n_a_m_e (Forth word or topic) or "no 2714 documentation available". 2715 help make-array \ Forth word 2716 help array \ topic 2717 hheellpp--aadddd!! ( obj str -- ) 2718 Append _s_t_r to documentation of _o_b_j. 2719 hheellpp--rreeff ( obj -- str ) 2720 Return documentation of _o_b_j (Forth word, object or topic) or "no 2721 documentation available". 2722 hheellpp--sseett!! ( obj str -- ) 2723 Set documentation of _o_b_j (Forth word or object) to _s_t_r. 2724 #( "behemoth" "pumpkin" "mugli" ) value hosts 2725 hosts "local-net hostnames" help-set! 2726 hosts help-ref => "local-net hostnames" 2727 llaammbbddaa:: ( -- xt ) 2728 Start nameless word definition and set variable latestxt to word. 2729 Stack-effect or normal comment immediately at the beginning will be 2730 used as documentation. Return xt after closing semicolon `;'. 2731 lambda: ( a b -- c ) + ; value plus 2732 plus help-ref => lambda-009 ( a b -- c ) 2733 1 2 plus execute => 3 2734 1 2 lambda: ( a b -- c ) * ; execute => 2 2735 llaatteessttxxtt ( -- xt ) 2736 Return latest defined xt. 2737 llooccaall--vvaarriiaabblleess ( -- vars ) 2738 Return a hash of local variable name-value pairs up to the location 2739 in definition. This word is immediate and compile only and can only 2740 be used in word definitions. 2741 : word-with-locals { foo -- } 2742 10 { bar } 2743 local-variables each 2744 .$ space 2745 end-each 2746 ; 2747 20 word-with-locals => #{ "bar" => 10 "foo" => 20 } 2748 mmaakkee--pprroocc ( xt arity -- prc ) 2749 Return new proc object. _a_r_i_t_y can be an integer or an array of 2750 length 3, #( req opt rest ). 2751 <'> + 2 make-proc => + 2752 lambda: ( a b -- c ) 2753 + 2754 ; #( 2 0 #f ) make-proc => lambda-009 2755 pprroocc-->>xxtt ( prc -- xt ) 2756 Return the actual word (the execution token xt) of _p_r_c. 2757 pprroocc--aappppllyy ( prc args -- res ) 2758 Execute proc object _p_r_c with arguments _a_r_g_s and return result or #f. 2759 _a_r_g_s can be an array of arguments or a single argument. If 2760 execution fails, raise an _e_v_a_l_-_e_r_r_o_r exception, if length of _a_r_g_s is 2761 less than required arity of _p_r_c, raise a _b_a_d_-_a_r_i_t_y exception. 2762 <'> + 2 make-proc value plus 2763 plus #( 5 6 ) proc-apply => 11 2764 pprroocc--aarriittyy ( prc -- arity ) 2765 Return arity array #( req opt rest ) of proc object _p_r_c, or #f if 2766 not a proc object. 2767 pprroocc--ccrreeaattee ( arity -- prc ) 2768 Create nameless proc object with _a_r_i_t_y. Like ccrreeaattee it goes with 2769 ddooeess>>. 2770 : input-fn ( gen -- proc; dir self -- r ) 2771 { gen } 2772 1 proc-create \ return proc with one argument 2773 gen , \ store gen for later use in DOES 2774 does> { dir self -- r } \ dir (ignored here) self (address) 2775 self @ \ return our gen 2776 readin \ return readin value 2777 ; 2778 instrument: src-simp <{ start dur amp sr sr-env fname -- }> 2779 :file fname find-file make-readin { f } 2780 :input f INPUT-FN :srate sr make-src { sc } 2781 :envelope sr-env :duration dur make-env { en } 2782 start dur run 2783 i sc en env #f src amp f* *output* outa drop 2784 loop 2785 f mus-close drop 2786 ;instrument 2787 0 1.5 0.5 0.2 #( 0 0 50 1 100 0 ) "fyow.snd" 2788 <'> src-simp with-sound 2789 pprroocc--nnaammee ( prc -- name ) 2790 Return name of proc object _p_r_c if found, otherwise an empty string. 2791 pprroocc--ssoouurrccee--rreeff ( prc -- str ) 2792 Return source string property of _p_r_c, or #f if not available. 2793 pprroocc--ssoouurrccee--sseett!! ( prc str -- ) 2794 Set source string property of _p_r_c to _s_t_r. 2795 pprroocc?? ( obj -- f ) 2796 Return #t if _o_b_j is a proc object. 2797 rruunn--pprroocc ( prc args -- res ) alias for _p_r_o_c_-_a_p_p_l_y 2798 rruunnnniinngg--wwoorrdd ( -- xt ) 2799 Return current xt in word definition. This word is immediate and 2800 compile only and can only be used in word definitions. 2801 : new-word 2802 running-word xt->name .$ 2803 space 2804 10 2805 ; new-word => new-word 10 2806 sseeee22 ( "name" -- ) 2807 Show word definition of _n_a_m_e. 2808 sseett!! ( "name" -- ) 2809 Parse _n_a_m_e and execute word _s_e_t_-_n_a_m_e if found, otherwise raise an 2810 _u_n_d_e_f_i_n_e_d_-_w_o_r_d exception. The following two lines do the same: 2811 128 set! object-print-length 2812 128 set-object-print-length 2813 sseett--eexxeeccuuttee ( xt -- ?? ) 2814 Execute _s_e_t_-_x_t if found, otherwise raise an _u_n_d_e_f_i_n_e_d_-_w_o_r_d 2815 exception. The following two lines do the same: 2816 128 <'> object-print-length set-execute 2817 128 set-object-print-length 2818 sseett--xxtt ( xt1 -- xt2 ) 2819 Return _s_e_t_-_x_t if found, otherwise #f. 2820 <'> object-print-length set-xt => set-object-print-length 2821 ssoouurrccee--ffiillee ( xt -- file ) 2822 Return source file where _x_t was created or #f if _x_t is a primitive 2823 or not defined. 2824 ssoouurrccee--lliinnee ( xt -- line ) 2825 Return source line number where _x_t was created or #f if _x_t is a 2826 primitive or not defined. 2827 ssoouurrccee--rreeff ( obj -- str ) 2828 Return source string of _o_b_j, a proc or xt, or #f if not found. 2829 ssoouurrccee--sseett!! ( obj str -- ) 2830 Set source string of _o_b_j, a proc or xt, to _s_t_r. 2831 tthhuunnkk?? ( obj -- f ) 2832 Return #t if _o_b_j is a proc object with no required, optional and 2833 rest arguments. If its arity is not #( 0 0 #f ), return #f. 2834 ttrraaccee--vvaarr ( var proc-or-xt -- ) 2835 Add _p_r_o_c_-_o_r_-_x_t to global _v_a_r hook which is utilized on every call of 2836 ttoo. The stack effect of _p_r_o_c_-_o_r_-_x_t must be ( val -- res ). 2837 mus-array-print-length => 8 2838 8 value *clm-array-print-length* 2839 <'> *clm-array-print-length* lambda: <{ val -- res }> 2840 val set-mus-array-print-length 2841 ; trace-var 2842 24 to *clm-array-print-length* 2843 *clm-array-print-length* => 24 2844 mus-array-print-length => 24 2845 <'> *clm-array-print-length* untrace-var 2846 uunnttrraaccee--vvaarr ( var -- ) 2847 Remove previously installed hook from _v_a_r. 2848 wwoorrdd?? ( obj -- f ) 2849 Return #t if _o_b_j is a proc object or an xt (execution token, address 2850 of a Ficl word), otherwise #f. 2851 wwoorrdd--ccrreeaattee ( name -- ) 2852 Create word _n_a_m_e in dictionary with does>-part as body. 2853 : make-setter ( name -- ; hs val self -- ) 2854 { name } 2855 name "!" $+ word-create 2856 name , 2857 does> { hs val self -- } 2858 hs self @ ( slot ) val hash-set! 2859 ; 2860 "user-time" make-setter ' creates setter word user-time! 2861 #{} value hs 2862 hs 3.2 user-time! 2863 hs ' #{ "user-time" => 3.2 } 2864 xxtt-->>nnaammee ( xt -- str ) 2865 Return name of _x_t if found, otherwise an empty string. 2866 xxtt-->>oorriiggiinn ( xt -- str ) 2867 Return name, source file and source line number where _x_t was defined 2868 (name:file:line). If _x_t is a C-primitive, return (name:primitive), 2869 if not defined, return an empty string. 2870 xxtt?? ( obj -- f ) 2871 Return #t if _o_b_j is an xt (execution token, address of a Ficl word), 2872 otherwise #f. 2873 2874 RReeggeexxpp oobbjjeecctt ttyyppee 2875 *re-syntax-options* 2876 This regexp variable can be set with the following constants. If 2877 more than one constant is used, combine them with oorr, see regex(3). 2878 REG_EXTENDED Compile modern regex, default. 2879 REG_ICASE Compile for matching ignore case. 2880 REG_NEWLINE Compile for newline-sensitive matching. 2881 REG_NOSUB Compile without creating subexpression. 2882 For example, set matching to ignore case before creating a new 2883 regexp 2884 REG_EXTENDED REG_ICASE or to *re-syntax-options* 2885 // ( <ccc>/ -- reg ) 2886 Prefix character `/' start a regular expression object delimited by 2887 a second `/'. 2888 /(B|b)+/ => /(B|b)+/ 2889 mmaakkee--rreeggeexxpp ( str -- reg ) 2890 Return new regexp object from _s_t_r which may contain regular 2891 expression. 2892 "(B|b)+" make-regexp value reg 2893 rree--mmaattcchh ( reg str start -- n ) 2894 Return count of matched characters or -1 for no match. 2895 /a*/ "aaaaab" 2 re-match => 3 2896 rree--sseeaarrcchh ( reg str start range -- n ) 2897 Return index of match or -1 for no match. 2898 /a*/ "aaaaab" 2 4 re-search => 2 2899 rree// ( space<ccc>/ -- reg ) 2900 Parse regexp _c_c_c delimited by `/' at compile time and at interpret 2901 time return parsed regexp. See _/ for an alternative. 2902 re/ (B|b)+/ => /(B|b)+/ 2903 rree== ( reg str -- len|#f ) alias for _r_e_g_e_x_p_-_m_a_t_c_h 2904 rreeggeexxpp--mmaattcchh ( reg str -- len|#f ) 2905 Return count of matched characters or #f. Possible matched group 2906 results or #f can be found in regexp object _r_e_g, in read-only 2907 variables *re1* to *re9* and in read-only array *re*. 2908 /.*(bar)/ value reg 2909 reg "foobar" regexp-match => 6 2910 reg 0 apply => foobar 2911 reg 1 apply => bar 2912 reg 2 apply => #f 2913 rreeggeexxpp== ( reg str -- len|#f ) alias for _r_e_g_e_x_p_-_m_a_t_c_h 2914 rreeggeexxpp--rreeppllaaccee ( reg str1 replace -- str2 ) 2915 Replace 1st occurrence of _r_e_g in _s_t_r_1 with _r_e_p_l_a_c_e if found. 2916 References \1 to \9 in _r_e_p_l_a_c_e will be replaced by corresponding 2917 subexpressions. If no corresponding subexpression exist, raise a 2918 _r_e_g_e_x_p_-_e_r_r_o_r exception. 2919 /(foo)/ "foo-bar" "***\\1***" regexp-replace 2920 => ***foo***-bar 2921 Note the double quotes on back reference characters . 2922 rreeggeexxpp--sseeaarrcchh ( reg str :key start 0 range -1 -- pos|f ) 2923 Return index of match or #f. If index is zero, return #t to fool 2924 Forth' iiff. If keyword _r_a_n_g_e is -1 (default), the entire string will 2925 be searched. Possible matched group results or #f can be found in 2926 regexp object _r_e_g, in read-only variables *re1* to *re9* and in 2927 read-only array *re*. 2928 /foo/ "foobar" :start 0 :range 6 regexp-search => #t (pos 0) 2929 /(bar)/ value reg 2930 reg "foobar" :start 0 :range 2 regexp-search => #f 2931 reg "foobar" :start 3 :range 2 regexp-search => 3 2932 reg 0 apply => bar 2933 reg 1 apply => bar 2934 reg 2 apply => #f 2935 rreeggeexxpp?? ( obj -- f ) 2936 Return #t if _o_b_j is a regexp object, otherwise #f. 2937 /^s/ regexp? => #t 2938 2939 SSttrriinngg oobbjjeecctt ttyyppee 2940 "" ( <ccc>" -- str ) 2941 Prefix character `"' start a string object delimited by a second 2942 `"'. 2943 "pumpkin" => "pumpkin" 2944 """" ( -- str ) 2945 Return empty string object (""). 2946 $$"" ( space<ccc>" -- str ) 2947 Parse string _c_c_c delimited by `"' at compile time and at interpret 2948 time return parsed string. See _" for an alternative. 2949 $" pumpkin" => "pumpkin" 2950 $$++ ( str1 str2 -- str3 ) alias for _s_t_r_i_n_g_-_a_p_p_e_n_d 2951 $$>>ssttrriinngg ( addr len -- str ) 2952 Return Forth string _a_d_d_r _l_e_n as string object. Standard words like 2953 ttyyppee and eevvaalluuaattee require this kind of string. 2954 $$ccrr ( -- str ) 2955 Return carriage return string object ("\n"). 2956 $$ssppaaccee ( -- str ) 2957 Return string of one space (" "). 2958 $$ssppaacceess ( len -- str ) 2959 Return string of _l_e_n spaces. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n 2960 < 0. 2961 ..$$ ( obj -- ) alias for _._s_t_r_i_n_g 2962 ..ddeebbuugg ( obj -- ) 2963 Print string representation of _o_b_j to stderr wrapped in ##<<DDEEBBUUGG((FF)):: 2964 ......>>. 2965 ..eerrrroorr ( obj -- ) 2966 Print string representation of _o_b_j to current error output. 2967 ..gg ( obj -- ) alias for _._s_t_r_i_n_g 2968 ..ssttddeerrrr ( obj -- ) 2969 Print string representation of _o_b_j to stderr. 2970 ..ssttddoouutt ( obj -- ) 2971 Print string representation of _o_b_j to stdout. 2972 ..ssttrriinngg ( obj -- ) 2973 Print string representation of _o_b_j to current output. 2974 <<<< ( str val -- str' ) alias for _s_t_r_i_n_g_-_p_u_s_h 2975 >>ssttrriinngg ( chars len -- str ) alias for _s_t_r_i_n_g_-_c_o_n_c_a_t 2976 cchhaarr?? ( obj -- ) 2977 Return #t if _o_b_j is a character, otherwise #f. 2978 ddiiee ( str -- ) 2979 Print _s_t_r wrappen in ##<<ddiiee:: ......>> to current stderr and exit 2980 interpreter with return code 1. 2981 eerrrroorr ( str -- ) 2982 Print _s_t_r wrappen in ##<<eerrrroorr:: ......>> to current stderr and throw 2983 exception. 2984 ffoorrmmaatt ( fmt args -- ) alias for _s_t_r_i_n_g_-_f_o_r_m_a_t 2985 fftthh--ddiiee ( fmt :optional args -- ) 2986 Print _f_m_t string with corresponding _a_r_g_s array wrapped in ##<<ddiiee:: 2987 ......>> to current stderr and exit interpreter with return code 1; _a_r_g_s 2988 is optional. See _s_t_r_i_n_g_-_f_o_r_m_a_t for _f_m_t description. 2989 fftthh--eerrrroorr ( fmt :optional args -- ) 2990 Print _f_m_t string with corresponding _a_r_g_s array wrapped in ##<<eerrrroorr:: 2991 ......>> to current stderr and throw exception; _a_r_g_s is optional. See 2992 _s_t_r_i_n_g_-_f_o_r_m_a_t for _f_m_t description. 2993 fftthh--ffoorrmmaatt ( fmt :optional args -- str ) 2994 Return string object from printf(3) _f_m_t string and _a_r_g_s array 2995 containing corresponding arguments; _a_r_g_s is optional. See _s_t_r_i_n_g_- 2996 _f_o_r_m_a_t for _f_m_t description. 2997 fftthh--pprriinntt ( fmt :optional args -- ) 2998 Print _f_m_t string with corresponding _a_r_g_s array to current stdout; 2999 _a_r_g_s is optional. See _s_t_r_i_n_g_-_f_o_r_m_a_t for _f_m_t description. 3000 fftthh--wwaarrnniinngg ( fmt :optional args -- ) 3001 Print _f_m_t string with corresponding _a_r_g_s array wrapped in ##<<wwaarrnniinngg:: 3002 ......>> to current stderr; _a_r_g_s is optional. See _s_t_r_i_n_g_-_f_o_r_m_a_t for 3003 _f_m_t description. 3004 mmaakkee--ssttrriinngg ( len :key initial-element ' ' -- str ) 3005 Return a new string of length _l_e_n filled with _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t 3006 characters, default space. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 3007 0. 3008 3 :initial-element <char> x make-string => "xxx" 3009 ssttrriinngg-->>aarrrraayy ( str -- ary ) 3010 Convert _s_t_r to an array of characters. 3011 "foo" string->array => #( 102 111 111 ) 3012 ssttrriinngg--aappppeenndd ( str1 str2 -- str3 ) 3013 Return new string _s_t_r_1 + _s_t_r_2. 3014 ssttrriinngg--ccaappiittaalliizzee ( str1 -- str2 ) 3015 Return new string with first character capitalized and remaining 3016 characters in lowercase. 3017 ssttrriinngg--ccaappiittaalliizzee!! ( str -- str' ) 3018 Return _s_t_r changed to first character capitalized and remaining 3019 characters to lowercase. 3020 ssttrriinngg--cchhoommpp ( str1 -- str2 ) 3021 Return new string object with possible trailing \n removed. 3022 ssttrriinngg--cchhoommpp!! ( str -- str' ) 3023 Return changed _s_t_r with possible trailing \n removed. 3024 ssttrriinngg--ccoonnccaatt ( objs len -- str ) 3025 Return new string with _l_e_n objects from stack converted to their 3026 string representation. 3027 0 1 2 " foo " "b" "a" "r" 7 >string 3028 => "012 foo bar" 3029 ssttrriinngg--ccooppyy ( str1 -- str2 ) 3030 Return copy of _s_t_r_1. 3031 ssttrriinngg--ddeelleettee!! ( str idx -- val ) 3032 Delete and return character at position _i_d_x from _s_t_r; negative index 3033 counts from backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is 3034 not in range of string. 3035 ssttrriinngg--ddoowwnnccaassee ( str1 -- str2 ) 3036 Return new string with all characters lowercase. 3037 ssttrriinngg--ddoowwnnccaassee!! ( str -- str' ) 3038 Return _s_t_r changed to all characters lowercase. 3039 ssttrriinngg--eevvaall ( str -- ?? ) 3040 Evaluate _s_t_r; values already on stack can be accessed, resulting 3041 values remain on stack. 3042 7 "3 4 + +" string-eval => 14 3043 ssttrriinngg--eevvaall--wwiitthh--ssttaattuuss ( str -- ?? status ) 3044 Evaluate _s_t_r and return eval-status on top of stack; values already 3045 on stack can be accessed, resulting values remain on stack. Eval- 3046 status can be one of the following constants: 3047 BREAK Ficl Break. 3048 ERROR_EXIT Ficl Error Exit. 3049 INNER_EXIT Ficl Inner Exit. 3050 OUT_OF_TEXT Ficl Out of Text. 3051 RESTART Ficl Restart. 3052 USER_EXIT Ficl User Exit. 3053 ssttrriinngg--ffiillll ( str char -- str' ) 3054 Fill _s_t_r with _c_h_a_r and return changed string object. 3055 ssttrriinngg--ffiinndd ( str1 key -- str2|#f ) 3056 Return match if string or regexp _k_e_y exist in _s_t_r, otherwise #f. 3057 "hello world" "l" string-find => "llo world" 3058 "hello world" /ell/ string-find => "lo world" 3059 ssttrriinngg--ffoorrmmaatt ( fmt args -- ) 3060 _f_m_t is a printf(3) format string and _a_r_g_s the needed arguments which 3061 may be an array, a single argument or #f. 3062 "%04d %8.2f %b %X %o" #( 128 pi 255 255 255 ) string-format 3063 => "0128 3.14 11111111 FF 377" 3064 The format string can have zero or more of the following flags: 3065 `##' The value will be converted to an alternate form. 3066 For bb, BB, oo and OO conversions prepend a zero before 3067 output, for xx and XX conversions prepend a `0x' 3068 respective `0X' before output. For aa, AA, ee, EE, ff, 3069 FF, gg and GG conversions the result will always have a 3070 decimal point. 3071 `--' Flush output left. 3072 `00' (zero) 3073 Padding with `0' (zero) rather than blank. 3074 The following conversion specifiers are known: 3075 %% A `%' is written. 3076 aaAAeeEEffFFggGG Floating point output like _p_r_i_n_t_f _3. 3077 cc Single character output. 3078 bbddoouuxxXX Integer output in binary, decimal, octal, unsigned 3079 and hexadecimal form. 3080 pp Inspect string output of any Forth object with 3081 oobbjjeecctt--iinnssppeecctt. 3082 ss String representation of any Forth object with 3083 oobbjjeecctt-->>ssttrriinngg. 3084 SS Dump string output of any Forth object with 3085 oobbjjeecctt--dduummpp. 3086 ssttrriinngg--iinnddeexx ( str key -- idx ) 3087 Return index of string _k_e_y in _s_t_r or -1 if not found. 3088 "hello world" "orl" string-index => 7 3089 ssttrriinngg--iinnsseerrtt!! ( str idx val -- str' ) 3090 Insert string representation of _v_a_l to _s_t_r at position _i_d_x; negative 3091 index counts from backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if 3092 index is not in range of string. 3093 ssttrriinngg--lleennggtthh ( str -- len ) 3094 If _s_t_r is a string object, return its length, otherwise -1. 3095 ssttrriinngg--mmeemmbbeerr?? ( str key -- f ) 3096 Return #t if string _k_e_y exist in _s_t_r, otherwise #f. 3097 "hello world" "ell" string-member? => #t 3098 ssttrriinngg--ppoopp ( str -- char ) 3099 Remove and return last character. If _s_t_r is empty, return #f. 3100 ssttrriinngg--ppuusshh ( str val -- str' ) 3101 Append string representation of _v_a_l to _s_t_r and return changed string 3102 object. 3103 ssttrriinngg--rreeff ( str idx -- val ) 3104 Return character at position _i_d_x; negative index counts from 3105 backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in range 3106 of string. 3107 ssttrriinngg--rreeppllaaccee ( str1 from to -- str2 ) 3108 Return new string object with string _f_r_o_m replaced by string _t_o. If 3109 _t_o is the empty string, delete the _f_r_o_m part from _s_t_r_1. 3110 ssttrriinngg--rreeppllaaccee!! ( str from to -- str' ) 3111 Return changed _s_t_r with string _f_r_o_m replaced by string _t_o. If _t_o is 3112 the empty string, delete the _f_r_o_m part from _s_t_r. 3113 ssttrriinngg--rreevveerrssee ( str1-- str2 ) 3114 Return _s_t_r_1 reversed as new string object. 3115 ssttrriinngg--rreevveerrssee!! ( str -- str' ) 3116 Return the same string object _s_t_r reversed. 3117 ssttrriinngg--sseett!! ( str idx val -- ) 3118 Store character _c_h_a_r at index _i_d_x; negative index counts from 3119 backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in range 3120 of string. 3121 ssttrriinngg--sshhiifftt ( str -- char ) 3122 Remove and return first character. If _s_t_r is empty, return #f. 3123 ssttrriinngg--sspplliitt ( str sep -- ary ) 3124 Split _s_t_r using _s_e_p as delimiter and return result as array of 3125 strings. If _s_e_p is not a string or regexp, delimiter is space. 3126 "foo:bar:baz" ":" string-split 3127 => #( "foo" "bar" "baz" ) 3128 "foo:bar:baz" "/:/" string-split 3129 => #( "foo" "bar" "baz" ) 3130 ssttrriinngg--ssuubbssttrriinngg ( str1 start end -- str2 ) 3131 Return new string from position _s_t_a_r_t to, but excluding, position 3132 _e_n_d. If _e_n_d is not an integer, _e_n_d will be set to length of _s_t_r_1; 3133 negative index counts from backward. Raise an _o_u_t_-_o_f_-_r_a_n_g_e 3134 exception if _s_t_a_r_t is not in range of string. 3135 "hello world" 2 4 string-substring => "ll" 3136 "hello world" -4 -2 string-substring => "or" 3137 "hello world" -4 nil string-substring => "orld" 3138 ssttrriinngg--uunnsshhiifftt ( str val -- str' ) 3139 Prepend string representation of _v_a_l to _s_t_r and return changed 3140 string object. 3141 ssttrriinngg--uuppccaassee ( str1 -- str2 ) 3142 Return new string with all characters uppercase. 3143 ssttrriinngg--uuppccaassee!! ( str -- str' ) 3144 Return _s_t_r changed to all characters uppercase. 3145 ssttrriinngg--ccmmpp ( str1 str2 -- n ) 3146 Return -1 if _s_t_r_1 is less than _s_t_r_2, 1 if _s_t_r_1 is greater than _s_t_r_2, 3147 and 0 if _s_t_r_1 is equal to _s_t_r_2. It may be used with sort functions. 3148 ssttrriinngg<< ( str1 str2 -- f ) 3149 Return #t if _s_t_r_1 is lexicographically lesser than _s_t_r_2, otherwise 3150 #f. 3151 ssttrriinngg<<>> ( str1 str2 -- f ) 3152 Return #t if strings are not equal, otherwise #f. 3153 ssttrriinngg== ( str1 str2 -- f ) 3154 Return #t if strings are equal, otherwise #f. 3155 ssttrriinngg>> ( str1 str2 -- f ) 3156 Return #t if _s_t_r_1 is lexicographically greater than _s_t_r_2, otherwise 3157 #f. 3158 ssttrriinngg>>$$ ( str -- addr len ) 3159 Return string object _s_t_r converted to a Forth string with _a_d_d_r _l_e_n. 3160 Standard words like ttyyppee and eevvaalluuaattee require this kind of string. 3161 ssttrriinngg?? ( obj -- f ) 3162 Return #t if _o_b_j is a string object, otherwise #f. 3163 wwaarrnn ( str -- ) alias for _w_a_r_n_i_n_g 3164 wwaarrnniinngg ( str -- ) 3165 Print _s_t_r wrappen in ##<<wwaarrnniinngg:: ......>> to current stderr. 3166 3167 SSyymmbboollss 3168 ..ssyymmbbooll ( sym -- ) 3169 Print symbol _s_y_m to current output. 3170 ccrreeaattee--ssyymmbbooll ( "name" -- ) 3171 Create symbol _n_a_m_e prepended by `''. Symbols are actually values 3172 (variables) named _'_n_a_m_e. 3173 create-symbol new-symbol => create symbol 'new-symbol 3174 mmaakkee--ssyymmbbooll ( name -- sym ) 3175 Return symbol _n_a_m_e prepended by `''. Symbols are actually values 3176 (variables) named _'_n_a_m_e. 3177 "new-symbol" make-symbol => 'new-symbol 3178 ssyymmbbooll--nnaammee ( sym -- str ) 3179 Return name of symbol _s_y_m. 3180 'new-symbol symbol-name => "new-symbol" 3181 ssyymmbbooll== ( obj1 obj2 -- f ) 3182 Return #t if _o_b_j_1 and _o_b_j_2 are symbols with identical name, 3183 otherwise #f. 3184 ssyymmbbooll?? ( obj -- f ) 3185 Return #t if _o_b_j is a symbol, otherwise #f. 3186 3187 KKeeyywwoorrddss 3188 ..kkeeyywwoorrdd ( kw -- ) 3189 Print keyword _k_w to current output. 3190 ccrreeaattee--kkeeyywwoorrdd ( "name" -- ) 3191 Create keyword _n_a_m_e prepended by `:'. Keywords are actually values 3192 (variables) named _:_n_a_m_e. 3193 create-keyword new-keyword => create keyword :new-keyword 3194 kkeeyywwoorrdd--nnaammee ( kw -- name ) 3195 Return name of keyword _k_w. 3196 :new-keyword keyword-name => "new-keyword" 3197 kkeeyywwoorrdd== ( obj1 obj2 -- f ) 3198 Return #t if _o_b_j_1 and _o_b_j_2 are keywords with identical name, 3199 otherwise #f. 3200 kkeeyywwoorrdd?? ( obj -- f ) 3201 Return #t if _o_b_j is a keyword, otherwise #f. 3202 mmaakkee--kkeeyywwoorrdd ( name -- kw ) 3203 Return keyword _n_a_m_e prepended by `:'. Keywords are actually values 3204 (variables) named _:_n_a_m_e. 3205 "new-keyword" make-keyword => :new-keyword 3206 3207 EExxcceeppttiioonnss 3208 *last-exception* 3209 Hold last raised exception. 3210 ..eexxcceeppttiioonn ( ex -- ) 3211 Print exception _e_x to current output. 3212 ccrreeaattee--eexxcceeppttiioonn ( msg "name" -- ) 3213 Create exception named _n_a_m_e with message _m_s_g, _m_s_g can be #f. The 3214 exception has a symbol name, that means it has prefix `'' before 3215 _n_a_m_e. 3216 "New test exception" create-exception new-exception 3217 => create 'new-exception 3218 eexxcceeppttiioonn--llaasstt--mmeessssaaggee--rreeff ( ex -- msg ) 3219 Return last message of exception _e_x. Last message was set after an 3220 exception was thrown with e.g. fftthh--tthhrrooww or fftthh--rraaiissee. 3221 eexxcceeppttiioonn--llaasstt--mmeessssaaggee--sseett!! ( ex msg -- ) 3222 Set _m_s_g, a string or #f, as last message of exception _e_x. This will 3223 be set automatically after an exception was thrown with e.g. 3224 fftthh--tthhrrooww or fftthh--rraaiissee. 3225 eexxcceeppttiioonn--mmeessssaaggee--rreeff ( ex -- msg ) 3226 Return message of exception _e_x. 3227 eexxcceeppttiioonn--mmeessssaaggee--sseett!! ( ex msg -- ) 3228 Set _m_s_g, a string or #f to exception _e_x. 3229 eexxcceeppttiioonn--nnaammee ( ex -- name ) 3230 Return name of exception _e_x. 3231 'new-exception exception-name => "new-exception" 3232 eexxcceeppttiioonn== ( obj1 obj2 -- f ) 3233 Return #t if _o_b_j_1 and _o_b_j_2 are exeptions with identical name, 3234 otherwise #f. 3235 eexxcceeppttiioonn?? ( obj -- f ) 3236 Return #t if _o_b_j is a exception, otherwise #f. 3237 mmaakkee--eexxcceeppttiioonn ( name msg -- ex ) 3238 Return exception named _n_a_m_e with message _m_s_g, _m_s_g can be #f. The 3239 exception has a symbol name, that means it has prefix `'' before 3240 _n_a_m_e. 3241 "New test exception" create-exception new-exception 3242 => create 'new-exception 3243 ssyymmbbooll-->>eexxcceeppttiioonn ( sym -- ex ) 3244 Return symbol _s_y_m as exception. 3245 3246EENNVVIIRROONNMMEENNTT 3247 FTH_DICTIONARY_SIZE 3248 Overwrite default dictionary size (1024 * 1024). 3249 FTH_LOCALS_SIZE 3250 Overwrite default number of locals (2048). 3251 FTH_RETURN_SIZE 3252 Overwrite default size of return stack (1024). 3253 FTH_STACK_SIZE 3254 Overwrite default size of parameter stack (8192). 3255 FTH_FTHPATH 3256 A colon separated list of paths pointing to Forth script files. 3257 These paths will be prepended to *load-path*. 3258 FTH_HISTORY 3259 Overwrite default history filename _~_/_._f_t_h_-_h_i_s_t_o_r_y. 3260 FTH_HISTORY_LENGTH 3261 Overwrite default history file length (100). 3262 FTH_INIT_FILE 3263 Overwrite default initialization filename _~_/_._f_t_h_r_c. 3264 FTH_LIBPATH 3265 A colon separated list of paths pointing to C extension libraries. 3266 These paths will be prepended to *load-lib-path*. 3267 3268FFIILLEESS 3269 _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_f_t_h_r_c 3270 Global initialization file for system wide configuration. 3271 _~_/_._f_t_h_r_c 3272 Local initialization file for user configuration. The name can be 3273 changed with FTH_INIT_FILE. 3274 _~_/_._f_t_h_-_h_i_s_t_o_r_y 3275 Local history file. The name can be changed with FTH_HISTORY. 3276 3277EEXXIITT SSTTAATTUUSS 3278 The fftthh utility exits 0 on success, and >0 if an error occurs. 3279 3280EEXXAAMMPPLLEESS 3281 The following are examples of typical usage of the fftthh command: 3282 3283 Print 32 Fahrenheit as Celsius (0.0) 3284 3285 % fth -e "32 f2c . cr" 3286 3287 Load C extension library _l_i_b_x_m with initialization function IInniitt__lliibbxxmm() 3288 and Forth source file _m_o_t_i_f_-_s_c_r_i_p_t_._f_s with at least one word mmaaiinn defined 3289 in it, execute word mmaaiinn and exit if finished 3290 3291 % fth -S "libxm Init_libxm" -e "main" motif-script.fs 3292 3293 Prepend path _~_/_s_h_a_r_e_/_f_o_r_t_h to *load-path*, load Forth source file 3294 _s_o_u_n_d_-_s_c_r_i_p_t_._f_s and start the repl showing a prompt. Initialization 3295 files _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_f_t_h_r_c and _~_/_._f_t_h_r_c are loaded if they exist 3296 3297 % fth -I ~/share/forth sound-script.fs 3298 3299 Run Forth script _c_h_e_c_k_._f_t_h and provide options --aabb _1_0 to the script which 3300 should handle at least these two; exit if finished 3301 3302 % fth -s check.fth -ab 10 3303 3304 Rename _c_o_n_f_i_g_._h to _c_o_n_f_i_g_._h_._o_r_i_g and read it line by line. If a line 3305 with 3306 #define HAVE_COMPLEX_DOUBLE 3307 occures, replace it with 3308 /* #undef HAVE_COMPLEX_DOUBLE */ 3309 otherwise write original to _c_o_n_f_i_g_._h. The first --ee set the global Forth 3310 variable reg to a regexp object, the second --ee uses this variable for 3311 testing. The _p_a_t_t_e_r_n of the first --ee is evaluated in interpret state 3312 before reading file while the _p_a_t_t_e_r_n of the second --ee is evaluated in 3313 compile state in a nameless llaammbbddaa:: <<{{}}>> ppaatttteerrnn ;; word during reading 3314 file line by line. 3315 3316 % fth -ni.orig -e '/#define HAVE_COMPLEX_DOUBLE/ value reg' \ 3317 -e 'reg *line* re= if \ 3318 "/* #undef HAVE_COMPLEX_DOUBLE */\n" \ 3319 else \ 3320 *line* \ 3321 then' config.h 3322 3323 Print name and login time from the who command: 3324 who | fth -ane '.*1* .*5* cr' 3325 3326 The same with output file separator set to " == ": 3327 who | fth -ane '" == " to *ofs* .*1* .*5* cr' 3328 3329 Stand-alone executable Forth scripts have a first line of at least 3330 #! /usr/local/bin/fth -s 3331 but may have more options; adjust the path to the interpreter. Note the 3332 space after ##!!. It's a Forth word starting a comment and must be 3333 separated by at least one space. 3334 3335 % cat hello-world.fth 3336 #! /usr/local/bin/fth -s 3337 ." Hello, World!" cr 3338 3339 Add option --vv to turn on verbose mode. _N_o_t_e_: Option --ss must be the last; 3340 fftthh doesn't process options after --ss, they are transfered to the script 3341 and can be processed there with Forth word ggeettoopptt, see below. 3342 3343 % cat hello-world.fth 3344 #! /usr/local/bin/fth -Ds 3345 ." Hello, World!" cr 3346 3347 The getopt(3) example in Forth: 3348 3349 % cat getopt-test.fth 3350 #! /usr/local/bin/fth -Ds 3351 : main ( -- ) 3352 #f #f { bflag ffile } 3353 #t to opterr \ getopt prints error messages 3354 begin 3355 *argv* "bf:" getopt ( ch ) dup 3356 while ( ch ) 3357 case 3358 <char> b of #t to bflag endof 3359 <char> f of optarg to ffile endof 3360 <char> ? of 3361 "usage: [-b] [-f file]\n" #() 3362 fth-print 3363 1 (bye) \ exit with return code 1 3364 endof 3365 endcase 3366 repeat ( ch ) drop 3367 optind 0 ?do *argv* array-shift drop loop 3368 *argv* array-length to *argc* 3369 "-b: %s, -f: %s\n" #( bflag ffile ) fth-print 3370 ; 3371 main 3372 0 (bye) \ exit with return code 0 3373 % ./getopt-test.fth 3374 -b: #f, -f: #f 3375 % ./getopt-test.fth -b 3376 -b: #t, -f: #f 3377 % ./getopt-test.fth -bf outfile 3378 -b: #t, -f: outfile 3379 % ./getopt-test.fth -f 3380 fth: option requires an argument -- f 3381 usage: [-b] [-f file] 3382 % ./getopt-test.fth -h 3383 fth: illegal option -- h 3384 usage: [-b] [-f file] 3385 3386DDIIAAGGNNOOSSTTIICCSS 3387 The command may fail for one of the following reasons: 3388 3389 bbaadd--aarriittyy Arity doesn't match for a given proc object. 3390 3391 bbaadd--ssyynnttaaxx Paren mismatch for array, list or hash objects. 3392 3393 bbiiggnnuumm--eerrrroorr Bignum error. 3394 3395 ccaattcchh--eerrrroorr Catch-throw mismatch. 3396 3397 eevvaall--eerrrroorr Evaluation error. 3398 3399 ffiiccll--eerrrroorr Ficl evaluation error. 3400 3401 ffoorrtthh--eerrrroorr Forth error. 3402 3403 llooaadd--eerrrroorr Error while loading a Forth file. 3404 3405 mmaatthh--eerrrroorr Math error occured. 3406 3407 nnuullll--ssttrriinngg Empty string occured. 3408 3409 nnoo--mmeemmoorryy--eerrrroorr Memory exhausted. 3410 3411 ooppttkkeeyy--eerrrroorr Error while evaluating option key functions. 3412 3413 oouutt--ooff--rraannggee Argument is out of range. 3414 3415 rreeggeexxpp--eerrrroorr Regexp error occured. 3416 3417 ssiiggnnaall--ccaauugghhtt Signal received. 3418 3419 ssoocckkeett--eerrrroorr Error while processing sockets. 3420 3421 ssoo--ffiillee--eerrrroorr Dynamic library load error. 3422 3423 ssyysstteemm--eerrrroorr General system function error occured. 3424 3425 wwrroonngg--nnuummbbeerr--ooff--aarrggss Wrong number of arguments provided. 3426 3427 wwrroonngg--ttyyppee--aarrgg Wrong argument type provided. 3428 3429SSEEEE AALLSSOO 3430 csh(1), snd(1), tcsh(1), vi(1), accept(2), bind(2), connect(2), 3431 listen(2), recv(2), recvfrom(2), send(2), sendto(2), shutdown(2), 3432 socket(2), fegetround(3), fenv(3), fesetround(3), fopen(3), getopt(3), 3433 getservbyname(3), getservbyport(3), gl_prompt_style(3), libfth(3), 3434 printf(3), realpath(3), regex(3), sethostname(3), strftime(3), time(3), 3435 times(3), tecla(7). 3436 3437HHIISSTTOORRYY 3438 This manual page describes version 1.4.1. fftthh is based on _F_i_c_l, 3439 _F_o_r_t_h_-_i_n_s_p_i_r_e_d _c_o_m_m_a_n_d _l_a_n_g_u_a_g_e, version 4.0.31 written by John Sadler. 3440 3441AAUUTTHHOORRSS 3442 fftthh and this manual page was written by Michael Scholz 3443 <mi-scholz@users.sourceforge.net>. 3444 3445BBUUGGSS 3446 Please report bugs to the author. 3447 3448NetBSD 9.99.18 2019/11/25 NetBSD 9.99.18 3449