Chapter 4.3:  File Access

[TOP] [UP] [PREV] [NEXT]

$includecml (name [iargs])

Parse the contents of a CML file name as though it had been "included" by an include directive at this point.  Name is relative to the top CML directory, as defined in $cml_path().  Iargs is an optional list of tokens that will be expanded inside name as $inc(1), $inc(2), etc.

A call to $includecml() evaluates to the "output" generated by double-quote lines in CML file name.  So the "output" generated by name is not sent to the browser (or stdout, if run from sweba).  This is how $includecml() "returns" values computed by name.

Notes:

1. The quit directive acts like a return directive inside such an included file.

2. This is a very powerful extension to Caucus (in version 4.23), especially when combined with Caucus "macros", since a macro can now effectively execute any Caucus directives, including for and count loops, etc.

3. There are some unanswered security questions about this function.  Future versions may put more explicit restrictions on which files can be included.  Unfortunately, $protect() is too blunt an instrument to be much help with this.

$file(name)        {protected}         (Probably obsoleted by $includecml().)

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.)  Any CML functions inside name are interpreted, by CML directives are not.

If you need to include a large file, or one that contains CML directives, see the include directive, or $includecml() above.

$include (name)

(Obsoleted by $includecml().)  Include contents of CML file name.  Very limited and probably buggy.  Do not use.

$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)        {protected}

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.

$readfile() automatically translates Windows return-newline pairs into single newline characters, effectively converting the read data into unix format.

$write(name text)        {protected}

Write text to file with absolute pathname name.  Overwrites previous contents of name, if any.

$append(name text)        {protected}

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)        {protected}

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, minus the protocol (http:// or https://) part.  Thus it is possible to make the file immediately available on the Web in any subsequently produced HTML.

$copyfile(source target perms)        {protected}

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, -1 if the source could not be opened, or 0 if the target could not be written.

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

$mkdir(fullpathname [perms])        {protected}

Attempts to create a directory fullpathname with (optional) permission mask perms (as described above).  Evaluates to 1 if successful, otherwise 0.

$open(name perm)        {protected}

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.

$exists(name)

Evaluates to "1" if file name (full pathname) exists, and "0" otherwise.

$rename(a b)        {protected}

Rename file a to file b.

$delfile(a)        {protected}

Delete file a.  Must use full pathname of file.

$deldir(a)        {protected}

Delete directory a, and all contained files and subdirectories.  Must use full pathname of directory.  Use with caution!

$file_data(name bytes range...)        {protected}

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)        {protected}

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.  If format is 2, each filename is followed by a space, the size, another space, and a directory code (1 means the filename is a directory, 0 means it is an ordinary file).

$output(name mask)        {protected}

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" (decimal!) means read/write owner, read group, and read world.  (The file is created & truncated each time this is done, so subsequent $output()'s to the same file rewrite it each time.)

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.