VFX Forth implements text macro substitution, where a text macro named FOO my be substituted in a string. When referenced in a string the macro name must be surrounded by % characters. If a % character is needed in a string it must be entered as %%.
Thus if FOO is defined as "c:\apps\vfxforth" then the string
|
would be expanded to
|
Macros are defined in the Substitutions vocabulary which is searched when the string is expanded. When executed these words return the address of a counted string for the text to substitute.
TextMacro: <name> defines an empty macro with a 255 character buffer in the Substitutions vocabulary.
<string> SETMACRO <name> sets the given string into the required macro <name>. If <name> does not exist in the Substitutions vocabulary an error is reported. SETMACRO may also be used in colon definitions, providing that the macro name already exists. If a colon definition needs to create a new macro name it should use $SETMACRO instead.
|
char % value textmac-delimiter \ -- char ; text macro delimiter
A VALUE returning the character used as the delimiter
for macro names during text macro expansion. Unless you have
a very good reason, do not change this value. In a future
VFX Forth release, this word will be removed.
: substituteC \ src slen dest dlen --
Expand the source string using text macro substitutions,
placing the result as a counted string at dest/dlen.
If an error occurred, the length of the counted string
is zero.
: substituteZ \ src slen dest dlen --
Expand the source string using text macro substitutions,
placing the result as a zero terminated string at dest/dlen.
If an error occurred, the length of the string is zero.
: replaces \ text tlen name nlen --
Define the string text/tlen as the text to substitute for the
substitution named name/nlen. If the substitution does not
exist it is created.
: subsitute-safe \ c-addr1 len1 c-addr2 len2 -- c-addr2 len3 ior
Replace each '%' character in the input string c-addr1/len1
by two '%' characters. The output buffer is represented by
caddr2/len2. The output is caddr2/len3 and ior
is zero on success.
If you pass a string through SUBSITUTE-SAFE and then
SUBSTITUTE, you get the original string.
: Expand \ caddr len -- caddr' len'
Macro expand the given string, returning a global buffer
containing the expanded string. The string is zero-terminated
and has a count byte before caddr'. If len is longer
than 254 bytes only the first 254 bytes will be processed.
: MacroExists? \ caddr -- xt nz | 0
If a macro of the given name exists, return its xt and a
non-zero flag, otherwise just return zero. The name is a
counted string.
: MacroSet? \ caddr -- flag
If a macro of the given name exists and text has been set
for it, return true. Often used to find out if a macro has
been set, so that a sensible default can be defined. In the
following example, IDIR is the current include directory
and MC" is a version of C" that expands macros.
|
: TextMacro: \ <"name"> --
Builds a new text-macro with an empty macro string.
TextMacro: Foo
: setmacro \ string "<name>" --
Reset/Create a text macro. Used in the form:
C" abcd" SETMACRO <name>
: $setmacro \ string name --
This version of SETMACRO takes both the string and
macro name as counted strings.
: getTextMacro \ caddr len -- macro$
Given a macro name, return the address of its text (a counted
string). If the name cannot be found the null counted string
cNull is returned.
: .macros \ --
Display all text macros by macro name.
: .macro \ "<name>" -- ; .MACRO <name>
Display the text for macro <name>.
: ShowMacros \ --
Display all macro names and text.
: $expand \ $source $dest --
Macro expand a counted string at $source to a counted
string at $dest.
: $ExpandMacros \ $ -- $'
Macro expand a counted string. Note that the returned string
buffer is in a global buffer.
: z$ExpandMacros \ z$ -- 'z$
Macro expand a 0 terminated string. The
returned string buffer is a global buffer.
: ExpandMacro \ c-addr u buff -- 'buff 'len
Perform TextMacro expansion on a string in c-addr u with
the result being placed as a counted string at buff. The
address and length of the expanded string are returned. The
string at 'buff is also zero terminated.
: M", \ "text" --
Compile the text string up to the closing quote into the
dictionary as a counted string, expanding text macros as
M", executes, usually at compile time.
The end of the string is aligned.
: MS" \ Comp: "<quote>" -- ; Run: -- c-addr u
Like S" but expands text macros. Text is taken up to
the next double-quotes character. Text macros are expanded
at compile time. The address and length of the string are
returned. To expand macros at run time, use:
s" <string>" expand
: MC" \ Comp: "<quote>" -- ; Run: -- c-addr
Like C" but expands text macros. Text is taken up to
the next double-quotes character. Text macros are expanded at
compile time. At run-time the address of the counted string
is returned. To expand macros at run time, use:
c" <string>" $ExpandMacros
The following text macros are defined by the system and are always available. They are implemented as words in the substitutions vocabulary.
create DevPath ( -- c$ ) 0 c, $FF allot
The path containing the developer's application source.
If selected by setting BuildLevel to -1, the contents
of this macro will be prepended to source file names in
the SOURCEFILES vocabulary.
create VfxPath ( -- c$ ) 0 c, $FF allot
The path containing the VFX Forth source code.
For most users, this is the Sources
folder of the VFX Forth installation. You
must set this yourself. It is preserved in the INI
file.
create BasePath ( -- c$ ) 0 c, $FF allot
The root folder of the VFX Forth installation. You
must set this yourself. It is preserved in the INI
file.
create LOCATE_PATH ( -- c$ ) 0 c, $FF allot
The name of the current/last file to be compiled.
Used by LOCATE and friends.
create LOCATE_LINE ( -- c$ ) 0 c, $FF allot
The line number of the line in the current file being compiled.
Used by LOCATE and friends.
: f locate_path ;
The name of the current/last file to be compiled.
A synonym for LOCATE_PATH. Used by LOCATE
and friends.
: l locate_line ;
The line number of the line in the current file being compiled.
A synonym for LOCATE_LINE. Used by LOCATE
and friends.
create LIBRARYDIR ( -- c$ ) 0 c, $FF allot
The pathname of the VFX Forth Lib directory.
: lib LIBRARYDIR ;
A synonym for LIBRARYDIR above, which returns
the pathname of the VFX Forth Lib directory.
create LOAD_PATH ( -- c$ ) 0 c, $FF allot
The directory containg the running program's executable.
: bin LOAD_PATH ;
The directory containing the VFX Forth executables.
A synonym for LOAD_PATH.
: idir \ -- c$
The current include directory. This string is '.' if no file
is being INCLUDEd and allows a load file to be
in the form below. The load file can then be referenced
from any other directory.
|
create wd \ -- c$
The working directory. Under Windows, DOS, Unices and OS X
this is ".". Do not change this macro.
End of text macros. What follows are normally exposed words.
LOAD_PATH constant Forth-Buff \ -- caddr
Returns the address of a counted string holding the directory
from which the application was loaded. This gives programs
access to the LOAD_PATH macro.
The code described here is specific to VFX Forth for Linux. Do not rely on any of the words documented here being present in any other VFX Forth implementation.
: GetExeName \ caddr --
Get the fully qualified name of the executable. It is saved
as a counted string at caddr.
: InitMacros \ --
Initialises the directory macros. Run at start up.
#256 buffer: editor$ \ -- addr
A buffer holding the path and name of the preferred editor
as a counted string, e.g.
/bin/vi
0 value EditOnError? \ -- flag
Set true to call the editor on an error.
: editor-is \ "<editor-name>" --
Set your preferred editor, e.g.
editor-is /bin/vi
: .ed \ --
Display the name of your preferred editor
#256 buffer: locate$ \ -- addr
A buffer holding the macro expansion required to edit a
specific line of a file. This information is used by
LOCATE. In the example below the macros
%f% and %l% will be replaced by the file name and
line number.
%f% -# %l%
: edit$ \ -- cstring
If the preferred editor has been set, return the program name,
otherwise return the default editor string for vi.
: $edit \ cstring --
Edit the file provided as a counted string.
: edit \ "<filename>" --
Edit the file whose name follows in the input stream, e.g.
EDIT release.txt
: (EditOnError) \ -- ; run editor on error
Edit the file at an error, using the contents of the variables
'SOURCEFILE and LINE#.
: SetLocate \ --
Tells VFX Forth how your editor can be called to go a
particular file and line. Use in the form
SetLocate <rest of line>
where the text after SetLocate is used to define how parameters are passed to the editor, e.g. for Emacs, use
SetLocate +%l% "%f%" &
The rest of line following SetLocate is used as the editor configuration string. Within the editor configuration string '%f%' will be replaced by the file name and '%l%' will be replaced by the line number. If you use file names with spaces, you should put quotation marks around the %f% text macro. Finish the line with " &" to run the editor detached from VFX Forth.