"Dynamic-Strings extension"dstrings
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU Library General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free
Software Foundation, 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA.
If you take advantage of the option in the LGPL to put a particular
version of this library part under the GPL, the author would regard it
as polite if you would put any direct modifications under the LGPL as
well, and include a copy of this request near the beginning of the
modified library source. A "direct modification" is one that enhances
or extends the library in line with its original concept, as opposed to
developing a distinct application or library which might use it.
This file is based on the ^Forth Motorola 680x0 strings package
of June, 1999.
Please direct any comments to david.n.williams@umich.edu.
Push the PSA of a fixed, external representation of the empty string onto
the string stack. "empty-string"
|
dstrings ordinary primitive
Leave the PSA of a string whose body is the Unix newline character on the
string stack. "newline-string"
|
dstrings ordinary primitive
A Forth variable that holds the address of the current string space, where
all dynamic string operations take place. "d-strings"
|
dstrings threadstate variable
ALLOT room and store the Forth string into data space as a packed string,
leaving data space aligned; and leave the length and new body address. It
is assumed that len is unsigned. An error is thrown if len is larger than
the system parameter MAX_SCOUNT. "s-comma"
NOTE: MAX_SCOUNT is returned by
S" /SCOPY" ENVIRONMENT?
Perhaps this restriction should be removed in favor of the normal data
space overflow error.
NOTE: S, is the same as STRING, in Wil Baden's Tool Belt, except it
stores a packed string instead of a counted string.
|
dstrings ordinary primitive
Set all string variables holding bound string values in string space to
the empty string, and clear string space including the string buffer,
string stack, and string stack frames. This word should be executed
only when string space is in a valid state.
"zero-strings"
|
dstrings ordinary primitive
Unlock string space for garbage collection. This is the default.
"string-g-c-off"
|
dstrings ordinary primitive
Lock string space so garbage collection cannot occur. An error will be
thrown if garbage collection is attempted.
"string-g-c-on"
|
dstrings ordinary primitive
Leave the number of bytes available for dynamic strings and string stack
entries in the string buffer. "string-unused"
|
dstrings ordinary primitive
If string space is not marked as containing garbage, return false. If
there is garbage, throw an error when garbage collection is locked.
Otherwise remove the garbage and return true. Garbage collection is
"transparent", so the user would not normally use this word.
"collect-string-garbage"
|
dstrings ordinary primitive
Allocate and initialize a string space with size bytes available for
the string buffer including the string stack, and with a string frame
stack for frame description entries holding up to #frames. The size is
rounded up to cell alignment, and the buffer begins and ends with cell
alignment. Return addr, the address of the string space. The standard
word FREE with addr as input can be used to release the space.
"make-string-space"
|
dstrings ordinary primitive
(M$:) no special info, see general notes dstrings compiling primitive
$" no special info, see general notes dstrings compiling primitive
Create a definition for "name" with the execution semantics
"name" execution: ($: -- a$ )
It is assumed that the input string resides as a packed, unchanging string
outside of string space. "string-constant"
For example:
$" This is a sample string." $constant sample$
|
dstrings defining primitive
"name" execution: ( -- dfa )
Create an ordinary Forth variable and initialize it to the address of a
fixed, external, packed representation of the empty string, such as that
pushed onto the string stack by EMPTY$.
"string-variable""
|
dstrings ordinary primitive
A synonym for (. Immediate. "paren-string-colon"
|
dstrings immediate primitive
compilation: ( -- $: arg1$ ... argN$ )
Immediate and compilation-only.
Copy the argument strings to the string buffer, push them onto
the string stack with "argN" the most accessible, and make them
into the top compile-time string stack frame. Compile the run-time
code to make an argument frame out of the N most accessible
run-time string stack entries. Inform the system interpreter that
it should compile run-time code for any white-space delimited
argument encountered in the text of the definition, that
concatenates the corresponding string in the run-time frame. At
the semicolon terminating the definition, drop the compile-time
argument frame and compile code to drop the run-time argument
frame. "args-brace"
Syntax for defining a string macro GEORGE:
: george ($: a$ b$ c$ -- cat$ )
args{ arg1 arg2 arg3 }
m" This is arg1: " arg1 m" ." ENDCAT ;
The blank following the last argument is required. For a macro
with no arguments, ARGS{ } does nothing but add useless
overhead and should be omitted. Two of the arguments in this example
are ignored and could have been left out. Words intended only as steps
in building a macro would omit ENDCAT, which terminates concatenation
and leaves the concatenated string on the string stack.
Sample syntax using the string macro GEORGE:
$" bill" $" sue" $" marie" george $.
The resulting display is:
This is arg1: bill.
NOTE: Macro argument labels must be distinct from each other and
from any local labels that appear in the same definition, and there
is no check for that.
NOTE: At the moment the semantics of ARGS{ is undefined
before DOES>.
|
dstrings immediate primitive
M" no special info, see general notes dstrings compiling primitive
This word has only compile-time semantics, just like M".
It appends run-time semantics to the current definition that
concatenates the back-ticked string according to the specification
for CAT. An error is thrown if the length of the quoted string
is longer than the system parameter MAX_SCOUNT (see S,).
"m-back-tick"
NOTE: M" and M` are not just for use in macros. Perhaps better
names would be +" and +`, but that suggests a string operand
on the stack. A choice consistent with the rest of our names
would be cat" and cat`, which requires more typing.
|
dstrings compiling primitive
Drop the two topmost string stack entries, marking them as garbage if
appropriate. "string-two-drop"
|
dstrings ordinary primitive
Leave copies of the two topmost string stack entries. The string
values are not copied. "string-two-dupe"
|
dstrings ordinary primitive
Leave the number of items on the string stack.
"string-depth"
|
dstrings ordinary primitive
Drop the topmost string stack entry, marking it as garbage if it is
initially bound to the top of the string stack.
"string-drop"
|
dstrings ordinary primitive
Leave a copy of the topmost string stack entry. The string value is
not copied. "string-dupe"
|
dstrings ordinary primitive
Drop the next to top item from the string stack.
"string-nip"
NOTE: Because of essential string space bookkeeping, the
system level implementation can be little more efficient than
the high-level definition:
: $NIP $SWAP $DROP ;
|
dstrings ordinary primitive
Leave a copy of the next most accessible string stack entry on top of
the string stack. The string value is not copied.
"string-over"
|
dstrings ordinary primitive
Copy the u-th string stack entry to the top of the string stack. The
string value is not copied. Throw an error if the input string stack
does not have at least u+1 items. "string-pick"
|
dstrings ordinary primitive
$SWAP no special info, see general notes dstrings ordinary primitive
Drop a$ from the string stack and leave it as a Forth string a.str,
without copying. "string-s-from"
WARNING: If a$ is a dynamic string, it may at the next garbage
collection, making a.str invalid.
|
dstrings ordinary primitive
Drop a$ from the string stack, copy it into data space as a packed string,
and leave it as a Forth string a.str. An error is thrown if the string
length is larger than the system parameter MAX_SCOUNT (see S,).
"string-s-from-copy"
|
dstrings ordinary primitive
Leave the string stack unchanged, and leave the string body address and
length on the data stack. "string-s-fetch"
NOTE: In earlier versions this was call $S@S. The trailing "S" is
superfluous if it is understood that the only string format that
usually appears on the data stack is the Forth string format.
WARNING: If a$ is a dynamic string, it may move at the next garbage
collection, making a.str invalid.
|
dstrings ordinary primitive
Copy the top string stack item just below the second item. The
string value is not copied. "string-tuck"
NOTE: Because of essential string space bookkeeping, the
system level implementation can be little more efficient than
the high-level definition:
: $TUCK $SWAP $OVER ;
|
dstrings ordinary primitive
Copy the external string value whose body address and count are on the
parameter stack into the string buffer and push it onto the string stack.
Errors are thrown if the count is larger than MAX_DSCOUNT, if there is not
enough room in string space, even after garbage collection, or if there is
an unterminated string concatenation. The input external string need not
exist as a packed string. "to-string-s-copy"
NOTE: MAX_DSCOUNT is the largest size the count field of a packed string
can hold, e.g., 255 or 64K - 1. It is returned by:
S" /DYNAMIC-STRING" ENVIRONMENT?
WARNING: This word should not be used when the input string is a bound
string because the copy operation may generate a garbage collection which
invalidates its PSA.
|
dstrings ordinary primitive
Push the external Forth string a.str onto the string stack, without
copying the string value into the string buffer. It is an unchecked
error if the Forth string a.str is not stored as an external packed
string. "to-string-s"
WARNING: If the string value of a.str is actually in the string
buffer, the push operation may generate a garbage collection
that invalidates its PSA.
|
dstrings ordinary primitive
$! no special info, see general notes dstrings ordinary primitive
Display the string on the terminal. If the system implementation of TYPE
has its output vectored, $. uses the same vector.
"string-dot"
|
dstrings ordinary primitive
($: -- $ )
Leave the PSA of the string held by the string variable.
"string-fetch"
|
dstrings ordinary primitive
Display the string on the terminal. A $. synonym.
"string-type"
|
dstrings ordinary primitive
Append the string body to the end of the string currently
being concatenated as the last string in the string buffer,
and update its count field. If there is no concatenating
string, start one. An error is thrown if there is not
enough room in string space even after a garbage collection.
When there is a concatenating string, CAT and S-CAT are
the only basic string operations that can copy a string into
the string buffer. Pushes onto the string stack without copy
are still allowed.
"cat"
NOTE: It is left to the user to define special concatenating
words like:
: \n-cat ( -- ) \n$ cat ;
|
dstrings ordinary primitive
If there is no concatenating string, do nothing. If there is,
leave it as a string bound to the string stack, and terminate
concatenation, permitting normal copies into the string buffer.
"end-cat"
|
dstrings ordinary primitive
Append the string body to the end of the string currently
being concatenated as the last string in the string buffer,
and update its count field. If there is no concatenating
string, start one. An error is thrown if there is not
enough room in string space even after a garbage collection.
When there is a concatenating string, S-CAT and CAT are the
only basic string operations that can copy a string into the
string buffer. "s-cat"
|
dstrings ordinary primitive
Push the description of a string stack frame starting at the
top of the string stack and containing u entries onto the
string frame stack. Errors are thrown if the frame stack
would overflow or if the depth of the string stack above the
top frame, if there is one, is less than u. The value u = 0
is allowed. "string-frame"
NOTE: The current implementation pushes u and the string stack pointer
onto the frame stack.
|
dstrings ordinary primitive
Drop the topmost string frame from the string frame stack
and string stack. Errors are thrown if either stack would
underflow or if the string frame does not begin at the top
of the string stack. The case where the frame has zero entries
on the string stack is handled properly.
"drop-string-frame"
|
dstrings ordinary primitive
Leave true and its index in the top string frame if the
Forth string matches an element of the frame, else leave
false. The index of the top frame element is zero.
"find-arg"
NOTE: This word should probably be available only to the
implentation. We may remove it from the dynamic-strings word
set in the future.
|
dstrings ordinary primitive
cleanupcode for the end of a definition that used ARGS{.
;-semicolon should be overloaded to compile it automatically
if dynamic string arguments were in use.
|
dstrings compiling primitive
/$SPACE no special info, see general notes dstrings ordinary primitive
/$SPACE-HEADER no special info, see general notes dstrings ordinary primitive
$BREAK no special info, see general notes dstrings ordinary primitive
$BUFFER no special info, see general notes dstrings ordinary primitive
$SP no special info, see general notes dstrings ordinary primitive
$SP0 no special info, see general notes dstrings ordinary primitive
#FRAMES no special info, see general notes dstrings ordinary primitive
/FRAME-STACK no special info, see general notes dstrings ordinary primitive
$FBREAK no special info, see general notes dstrings ordinary primitive
$FSP no special info, see general notes dstrings ordinary primitive
$FSP0 no special info, see general notes dstrings ordinary primitive
0$SPACE no special info, see general notes dstrings ordinary primitive
ENVIRONMENT
an ENVIRONMENT constant to be checked with ENVIRONMENT?
the value is currently encoded as a datecode with a decimal
printout of format lik YYMMDD
|
dstrings ordinary constant
dstrings ordinary constant
dstrings ordinary constant
ENVIRONMENT DSTRINGS-LOADED no special info, see general notes dstrings constructor primitive
EXTENSIONS
P4_EXPT ("string count too large"
, P4_ON_SCOUNT_OVERFLOW),
P4_EXPT ("string space overflow"
, P4_ON_SSPACE_OVERFLOW),
P4_EXPT ("string garbage locked"
, P4_ON_SGARBAGE_LOCK),
P4_EXPT ("string stack underflow"
, P4_ON_SSTACK_UNDERFLOW),
P4_EXPT ("cat lock preventing string copy"
, P4_ON_SCAT_LOCK),
P4_EXPT ("dynamic string count too large"
, P4_ON_DSCOUNT_OVERFLOW),
P4_EXPT ("too many string frames"
, P4_ON_SFRAME_OVERFLOW),
P4_EXPT ("not enough strings for frame"
, P4_ON_SFRAME_ITEMS),
P4_EXPT ("string frame stack underflow"
, P4_ON_SFRAME_UNDERFLOW),
P4_EXPT ("string frame not at top of string stack"
,
P4_ON_SFRAME_MISMATCH),
|