- $file(name)
-
Include the entire text of file name at this point.
The $file() function should only be used to include relatively
short (a couple of lines, maximum) files, such as when you need
to include the contents of a file in the middle of an HTML or
SET string that you are building. Name is relative to
the CML_Path directory specified in the swebd.conf file. (See
the Caucus installation guide for details.)
If you need to include a large file, or one that contains CML
directives, see the "include" directive in section 5.
- $readterm()
-
Reads a single line of text from the user's terminal, removes
the trailing newline, and evaluates to that line as a string.
This function is only useful with sweba, the stand-alone
CML interpreter.
If used with swebs (i.e., Caucus), it evaluates to an empty string.
- $readfile(name)
-
Evaluate to the entire contents of text file name. Name
should be the full pathname of a file on the server host. Whereas
$file() is meant as a way to include additional CML code in a
page, $readfile() is meant for reading data that will somehow
be processed or displayed by a CML page.
- $write(name text)
-
Write text to file with absolute pathname name.
Overwrites previous contents of name, if any.
- $append(name text)
-
Append text to file with absolute pathname name.
- $dosfile(name)
-
Truncates name to the first 8 characters, and replaces
all dots (".") with underscores ("_"). Useful
when name refers to a file on the client machine.
- $copy2lib(file libname)
-
Copies file (a full pathname) to a new file called libname,
in the Caucus file library. (See the parameters Caucus_Lib and
HTTP_Lib in the swebd configuration file swebd.conf for more
information about the Caucus file library.) Libname may
contain sub-directory names, and is always treated as relative
to the root of the Caucus file library. Sub-directories are created
automatically. Thus a libname of "demo/xyz"
would copy file to a file called "xyz" in a sub-directory
"demo" under the Caucus file library, and would automatically
create the "demo" directory if needed.
The function evaluates to the full URL of the newly created file,
thus making it possible to make the file immediately available
on the Web in any subsequently produced HTML.
- $copyfile(source target perms)
-
Copies file source (a full pathname) to a new file called
target (also a full pathname). Gives target
the permissions perm.
Automatically creates subdirectories in target if
necessary (and if possible).
Evaluates to 1 on success, and 0 on failure.
The value of perms is a "permissions mask" that is the sum
of some or all of the values below. This mask is
mapped directly into Unix file permission values, and as closely
as possible to the equivalent Windows/NT permissions.
400 | | read by owner |
200 | | write by owner |
100 | | execute by owner |
40 | | read by group |
20 | | write by group |
10 | | execute by group |
4 | | read by anyone |
2 | | write by anyone |
1 | | execute by anyone |
- $open(name perm)
-
Open a file name for reading (if perm is "r"),
for writing (if perm is "w"), or to append to
(if perm is "a"). Evaluates to a number which
is the file "handle", or to "0" if the file
could not be opened.
- $readln(handle var)
-
Read a line from the file open on handle, and put the
text into variable var. Evalutes to "1" if successful,
or to "0" on end-of-file.
- $writeln(handle text)
-
Writes text to the file open on handle. Evaluates
to "1" on success, or "0" if handle
does not refer to an open file.
- $close(handle)
-
Close file open on handle.
- $rename(a b)
-
Rename file a to file b.
- $delfile(a)
-
Delete file a. Must use full pathname of file.
- $file_data(name bytes range...)
-
Checks the first bytes characters of file name to
see if its contents fit within certain byte-value ranges.
(A bytes value of -1 means "check the entire file".)
Range is one or more byte values or byte value ranges,
expressed as decimal numbers.
For example "32" is the decimal code for a "blank" character,
and the range "65-90" covers the codes for the upper-case
letters A through Z.
$file_data() evaluates to 1 if the first bytes characters
of name are included in the range values,
and 0 otherwise.
Thus, for example, $file_data(name 500 32 65-90) would evaluate to 1
if the first 500 characters were either blanks or the letters A-Z, and
0 otherwise.
A good use of $file_data() is to determine if a file contains
only "plain text", or is some other kind of file (word processor
file, image file, etc.)
If $file_data (name -1 9-26 32-126) is 1, name is most likely
a text file.
- $dirlist(format dir)
-
If format is 0, evaluates to a space-separated list of
the files (and directories) in directory dir. If format
is 1, each filename is immediately followed by a space and the
size of the file in bytes.
- $output(name mask)
-
Normally, CML lines that begin with a double-quote (") are
interpreted and sent directly to the user's browser. The $output()
function redirects this text, and writes it to a file name,
instead. Mask is the numeric Unix file permission mask,
e.g. a value of "644" means read/write owner, read group,
and read world.
The redirection takes effect on all quoted lines that follow
the use of $output(). Another call to $output(), with no arguments,
returns subsequent output from quoted lines to the browser, in
effect "closing" the file.