| blob | feb530d492b6cf6188dbb90be9f8c8c49f930185 |
2 <TABLE>
7 <TR><TD></TD>
8 <!--TD ALIGN=CENTER>
9 <A HREF="mailto:ai108@rz.tu-ilmenau.de">Mail the author</A></TD-->
10 <TD></TD></TR>
11 </TABLE><HR>
13 <H1>FLK non-standard words</H1>
14 This section describes useful words provided by the system. Since there a
15 lots of useful words in the system only those are explained which are
16 important for every day's work.
18 <A NAME=ccstring><H3>Cell counted string handling</H3></A>
19 To overcome the limitations of the byte counted strings proposed by the
20 standard cell counted strings are available. Both static variables and
21 dynamicly allocated ones can be used.
22 <TABLE BORDER=2 COLS=3>
23 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
24 <TR><TD>$COUNT</TD><TD>(addr -- addr+cell count)</TD><TD>COUNT for cell counted
25 strings</TD></TR>
26 <TR><TD>$cat</TD><TD>(caddr u addr -- )</TD><TD>Append the cell counted string at
27 addr by the given string.</TD></TR>
28 <TR><TD>$copy</TD><TD>(caddr u addr -- )</TD><TD>Replace the cell counted string at
29 addr by the given string.</TD></TR>
30 <TR><TD>$VARIABLE</TD><TD>(n -<name>-)</TD><TD>Create a cell counted
31 string variable reserving n characters. </TD></TR>
32 </TABLE>
34 <A NAME=vocs><H3>Vocabularies</H3></A>
35 <TABLE BORDER=2 COLS=3>
36 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
37 <TR><TD>VOCS</TD><TD>( -- )</TD><TD>Show the names of all known vocabularies.</TD></TR>
38 <TR><TD>.VOC</TD><TD>( wid --) </TD><TD>Display the name of the given wordlist.</TD></TR>
39 <TR><TD>SEARCH-WORDLISTS</TD><TD>( c-addr u -- 0 / xt 1 / xt -1 )</TD><TD>Perform
40 the function of FIND but with a faster and simpler interface.</TD></TR>
41 <TR><TD>VOCABULARY</TD><TD>( -<name>- )</TD><TD>Create a named wordlist.
42 The execution of name replaces the first word list in the search order.</TD></TR>
43 </TABLE>
45 <A NAME=transport><H3>Transport functions</H3></A>
46 <TABLE BORDER=2 COLS=3>
47 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
48 <TR><TD>TURN</TD><TD>( t3 t2 t1 t0 -- t2 t1 t0 t3 )</TD><TD>ROT with 4 items</TD></TR>
49 <TR><TD>-TURN</TD><TD>( t3 t2 t1 t0 -- t0 t3 t2 t1 )</TD><TD>-ROT with 4 items</TD></TR>
50 <TR><TD>TWIST</TD><TD>( t4 t3 t2 t1 t0 -- t3 t2 t1 t0 t4 )</TD><TD>ROT with 5
51 items</TD></TR>
52 <TR><TD>-TWIST</TD><TD>( t4 t3 t2 t1 t0 -- t0 t4 t3 t2 t1 )</TD><TD>-ROT with 5
53 items</TD></TR>
54 <TR><TD>ROTARE</TD><TD>( t5 t4 t3 t2 t1 t0 -- t4 t3 t2 t1 t0 t5 )</TD><TD>ROT
55 with 6 items </TD></TR>
56 <TR><TD>-ROTARE</TD><TD>( t5 t4 t3 t2 t1 t0 -- t0 t5 t4 t3 t2 t1 )</TD><TD>-ROT
57 with 6 items </TD></TR>
58 <TR><TD>PLUCK</TD><TD>( t2 t1 t0 -- t2 t1 t0 t2 )</TD><TD>OVER with 3 items</TD></TR>
59 <TR><TD>FLOCK</TD><TD>( t3 t2 t1 t0 -- t3 t2 t1 t0 t3 )</TD><TD>OVER with 4 items</TD></TR>
60 <TR><TD>exchange</TD><TD>( x1 addr -- x2 )</TD><TD>Exchange the value at addr
61 with x1 returning the old content of addr</TD></TR>
62 <TR><TD>nDROP</TD><TD>( n*x n-- )</TD><TD>Drop the top n+1 items.</TD></TR>
63 <TR><TD>TO++</TD><TD>( -<name>- )</TD><TD>Increase a VALUE by one.</TD></TR>
64 <TR><TD>TO--</TD><TD>( -<name>- )</TD><TD>Derease a VALUE by one.</TD></TR>
65 <TR><TD>+TO</TD><TD>( x -<name>- )</TD><TD>Add a number to a VALUE.</TD></TR>
66 </TABLE>
68 <A NAME=string><H3>String tools</H3></A>
69 <TABLE BORDER=2 COLS=3>
70 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
71 <TR><TD>CAPS-COMPARE</TD><TD>( caddr1 u1 caddr2 u2 -- n</TD><TD>Perform the
72 function of the word COMPARE but case insensitive.</TD></TR>
73 <TR><TD>ARGC</TD><TD>( -- u )</TD><TD>Return the number of commandline arguments.</TD></TR>
74 <TR><TD>ARGV</TD><TD>( -- addr )</TD><TD>Return the address of the array containg
75 the addresses of zero-terminated string containing the commandline arguments.
76 There are exactly ARGC items stored in consequtive cells beginning at the
77 returned address.</TD></TR>
78 <TR><TD>CHAR-H-LINE+</TD><TD>( x y w -- )</TD><TD>Draw a horizontal line of w
79 characters starting at (x,y).</TD></TR>
80 <TR><TD>CHAR-V-LINE+</TD><TD>( x y h -- )</TD><TD>Draw a vertical line of h
81 characters starting at (x,y).</TD></TR>
82 <TR><TD>CHAR-FRAME</TD><TD>( x y width height -- )</TD><TD>Draw a frame of the
83 given width and height with the left upper corner at (x,y).</TD></TR>
84 <TR><TD>strlen</TD><TD>( caddr -- caddr u )</TD><TD>Count the characters in a
85 zero terminated string.</TD></TR>
86 </TABLE>
88 <A NAME=system><H3>System storage</H3></A>
89 FLK is able to save its current state to disk. Sadly you cannot save to a
90 currently running file. The code area is the room where all code is compiled
91 to and where the headers are placed. The data area holds the data space
92 accessed by CREATE etc.
93 <TABLE BORDER=2 COLS=3>
94 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
95 <TR><TD>SAVE-SYSTEM</TD><TD>( caddr u -- )</TD><TD>Saves the system to the file
96 with the given name. You need to have write permission. If the file already
97 exists and contains an image it is overwritten. Otherwise the image is
98 appended or the file is created.</TD></TR>
99 <TR><TD>TURN-KEY</TD><TD>( caddr u -<name>- )</TD><TD>Make name the first word to
100 be executed and perform the function of SAVE-SYSTEM.</TD></TR>
101 <TR><TD>copy-executable</TD><TD>( name #name -- )</TD><TD>Copy the running
102 executable to a different name in preparation for SAVE-SYSTEM or TURN-KEY.</TD></TR>
103 <TR><TD>set-codesize</TD><TD>( n -- )</TD><TD>Set a new size for the code area.</TD></TR>
104 <TR><TD>set-datasize</TD><TD>( n -- )</TD><TD>Set a new size for the data area.</TD></TR>
105 <TR><TD>new-system</TD><TD>( addr len -- )</TD><TD>Copy the current executable to
106 the given name and save the system to it. The name must not be the name of the
107 current executable.</TD></TR>
108 </TABLE>
110 <A NAME=misc><H3>Other useful words</H3></A>
111 <TABLE BORDER=2 COLS=3>
112 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
113 <TR><TD>INCLUDE</TD><TD>( -- )</TD><TD>Input a filename and perform INCLUDED.</TD></TR>
114 <TR><TD>TODO</TD><TD>( -- )</TD><TD>Throw the "to do" exception. If you mark
115 unfinished code with this word execution of the unfinished parts raises an
116 exception and does not crash.</TD></TR>
117 <TR><TD>INLINE</TD><TD>( -- )</TD><TD>Inline code into the currently compiled
118 defintion. This word can bee seen as a throw-away primitive.</TD></TR>
119 <TR><TD>DEFER</TD><TD>( -<name>- )</TD><TD>Create name. If you assign an xt to
120 name using TO the execution of name calls the stored xt.</TD></TR>
121 <TR><TD>r,</TD><TD>( x -- )</TD><TD>Perform the function of , but relocate the
122 stored value.</TD></TR>
123 <TR><TD>TURN-ON</TD><TD>( -<name>- )</TD><TD>Perform the equivalent to <CODE>TRUE
124 TO name</CODE>.</TD></TR>
125 <TR><TD>TURN-OFF</TD><TD>( -<name>- )</TD><TD>Perform the equivalent to <CODE>FALSE
126 TO name</CODE>.</TD></TR>
127 <TR><TD>ALERT</TD><TD>( -- )</TD><TD>Alert the user by a bell if
128 <CODE>audible-signal</CODE> is <CODE>TRUE</CODE> or by flashing the screen.</TD></TR>
129 <TR><TD>.NOW</TD><TD>( -- )</TD><TD>Tell the current time and date.</TD></TR>
130 <TR><TD>>UPPER</TD><TD>( char -- char2 )</TD><TD>Convert a character to upper
131 case.</TD></TR>
132 <TR><TD>SYSTEM</TD><TD>( addr len -- retval )</TD><TD>Shell out and perform the
133 command in the string.</TD></TR>
134 <TR><TD>RCONSTANT</TD><TD>( x -<name>- )</TD><TD>A relocated CONSTANT.</TD></TR>
135 <TR><TD>RVALUE</TD><TD>( x -<name>- )</TD><TD>A relocated VALUE.</TD></TR>
136 <TR><TD>COMMENT</TD><TD>--</TD><TD>Mark the last defined word as a comment,
137 i.e. execute it instead of caching it. If you <CODE>POSTPONE</CODE> a
138 <CODE>COMMENT</CODE>ing word the current definition becomes a comment itself.</TD></TR>
139 <TR><TD>PARSING</TD><TD>--</TD><TD>Mark the last defined word to be parsing.
140 You have to give this flag if you mess around in the parsing area and do not
141 use <CODE>PARSE</CODE> directly or indirectly.</TD></TR>
142 <TR><TD>.faulty-word</TD><TD>( fault-at base -- )</TD><TD>Debugging utility.
143 If you encounter a segmentation fault you can't explain just run FLK in
144 <TT>gdb</TT> and write down the address of the fault and the base address of
145 the image. Then restart the same image again and execute
146 <CODE>.faulty-word</CODE>. It tells you which word is closest to the given
147 address.</TD></TR>
148 </TABLE>
150 <A NAME=macro><H3>Macro words</H3></A>
151 By default FLK compiles every word as separate subroutine ended by return.
152 Sometimes this is not desirable e.g. if words are factored for readability and
153 the factors are not meant to be used interactively. Using the macro recorder
154 invoced by <CODE>macro</CODE> you can define those words to be compiled inline.
155 <p>
156 <CODE>macro</CODE> reads the input until an empty line or the end of the file
157 is found and connects these lines to a single string separated by new-lines.
158 When the created word is executed (it is <CODE>IMMEDIATE</CODE>) the recorded
159 string is passed to <CODE>EVALUATE</CODE>. All words are allowed in the macro
160 but be aware that long definitions can use a lot of memory in the
161 dictionary.<p>
162 The flag setting words are provided here to.
163 <TABLE BORDER=2 COLS=3>
164 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
165 <TR><TD>macro</TD><TD>( -<name>- )</TD><TD>Create an <CODE>IMMEDIATE</CODE> word
166 <CODE>name</CODE> and record all further up to the next empty one into the
167 definition. When <CODE>name</CODE> is executed the recorded string is processed
168 by <CODE>EVALUATE</CODE>.</TD></TR>
169 </TABLE>
171 <A NAME=library><H3>Shared library words</H3></A>
172 To extend the abilities of FLK even further you can bind dynamically loaded
173 libaries or shared objects using the following words. The used syntax is
174 similiar but not equal to bigforth.<p>
175 When a library is loaded and the system is saved the library is loaded again
176 at the next start of the new system. <p>
177 If either a symbol name or library file can not be found an error message from
178 the linker is produced and <CODE>ABORT</CODE> is called.<p>
179 <TABLE BORDER=2 COLS=3>
180 <TR><TD>Word</TD><TD>Stack effect</TD><TD>Function</TD></TR>
181 <TR><TD>lib</TD><TD>( addr len -<name>- )</TD><TD>Create <CODE>name</CODE>,
182 load the library who's filename is given in the string and make the library
183 the current library (The one to be searched for symbols.). Execution of
184 <CODE>name</CODE> makes the library the current library too..</TD></TR>
185 <TR><TD>fct:</TD><TD>( returns -<name parameters>- )</TD><TD>Declare a
186 word <CODE>name</CODE> and bind the function <CODE>name</CODE> found in the
187 current library to it. The accepted return types are <CODE>int</CODE>,
188 <CODE>double</CODE> and <CODE>void</CODE>. The parameters are declared in
189 <B><I>reverse</I></B> and passed in the same order as a C-prototype. Accepted
190 parameter types are <CODE>int</CODE>, <CODE>double</CODE>, <CODE>float</CODE>
191 and <CODE>void</CODE>. All integer and pointer parameters are passed as
192 <CODE>int</CODE>. As an abbreviation <CODE>ints</CODE> is provided. <CODE>2
193 ints</CODE> is the same as <CODE>int int</CODE> but generates more efficient
194 code.</TD></TR>
195 <TR><TD>var:</TD><TD>( -<name>- )</TD><TD>Bind the address of the
196 variable <CODE>name</CODE> found in the the current library to
197 <CODE>name</CODE>. <CODE>name</CODE> behaves like declared by
198 <CODE>VARIABLE</CODE>.</TD></TR>
199 <TR><TD>libs</TD><TD>( -- )</TD><TD>Display the names of the loaded libraries.</TD></TR>
200 </TABLE>
202 <A NAME=syscall><H3>Linux system calls</H3></A>
203 This feature is somehow experimental at the moment. You can use the Linux
204 system calls (man page section 2 functions) like colon definitions. It is not
205 advisable to use them interactively but it is possible and if you're
206 careful...<p>
207 The actual words are named <CODE>sys_</CODE><B>name</B> where <B>name</B> is
208 the name of the call as found in <CODE>/usr/include/asm/unistd.h</CODE>.<p>
209 I present no comment on the individual words. Look into the man page if you're
210 curious. The calling order is left-to-right i.e. <CODE>write(a,b,c);</CODE> in
211 C becomes <CODE>a b c sys_write</CODE> in FORTH.<p>
212 The return value from them is put onto the stack after removal of the
213 parameters. If this value is negative the call failed and the number is the
214 negative content of <CODE>errno</CODE> in C.<p>
215 The script <CODE>mksc</CODE> to generate <CODE>linuxsc.fs</CODE> is included
216 but not connected to the <TT>Makefile</TT>. If anyone finds bugs in the script
217 please send a mail to me.<p>
218 Some system calls are listed with a negative number of parameters. Those calls
219 are either obsolete or require more than 5 parameters. Their number of
220 parameters (the first case) are not known or the calling sequence for that
221 many parameters is not documented anywhere. A Linux hacker who knows this
222 could be helpful.<p>
224 <A NAME=flags><H3>Flags</H3></A>
225 <TABLE BORDER=2 COLS=3>
226 <TR><TD>Word</TD><TD>Behaviour when TRUE</TD><TD>Behaviour when FALSE</TD></TR>
227 <TR><TD>CAPS</TD><TD>String comparison is case insensitive.</TD><TD>String
228 comparison is case sensitive.</TD></TR>
229 <TR><TD>audible-signal</TD><TD>ALERT rings a bell.</TD><TD>ALERT flashes the
230 screen.</TD></TR>
231 <TR><TD>redef-warning</TD><TD>A warning is printed, when a word in the same
232 wordlist is redefined.</TD><TD>The warning is not displayed.</TD></TR>
233 <TR><TD>checkpoints</TD><TD>Checkpoints are compiled or
234 displayed.</TD><TD>Checkpoints are ignored.</TD></TR>
235 </TABLE>
237 <HR><TABLE>
238 <TR><TD></TD><TD ALIGN=CENTER><A HREF="index.html">Up</A> </TD><TD></TD></TR>
239 <TR><TD><A HREF="intro.html">Previous</A></TD>
240 <TD ALIGN=CENTER><H1>FLK</H1></TD>
241 <TD><A HREF="license.html">Next</A></TD></TR>
242 <TR><TD></TD>
243 <!--TD ALIGN=CENTER>
244 <A HREF="mailto:ai108@rz.tu-ilmenau.de">Mail the author</A></TD-->
245 <TD></TD></TR>
246 </TABLE>
247 </BODY></HTML>
248 <!-- vim:tw=78
249 >