Section Intro: File Operators

THE META-HTML LANGUAGE REFERENCE MANUAL

Page Operators

[TOC]

Stream Operators

Section Intro: File Operators

File Operators

Synopsis:

There are several types of commands in Meta-HTML for dealing with files.

Some of these commands operate directly on an open files, while others operate on streams (see Stream Operators), which may be connected to files or network data.

The functions allow you to include the contents of, open (with-open-stream), create, read, or write various data sources, or to replace the contents of a page (replace-page) with another file.

Commands:

cgi-exec
dir::basename
dir::canonicalize-pathname
dir::copy-file
dir::create-emacs-backup
dir::dir-table
dir::dirname
dir::filename-extension

dir::filename-sans-extension
dir::handle-dots
dir::names-in-dir
dir::read-file
dir::write-file
directory-contents
directory-p
directory?

file-exists
file-newer?
get-file-properties
make-directories
path::find-executable
require
unix::mkfifo
webpath-exists

Variables:

MHTML::EXEC-PATH

More Information:

Commands such as get-file-properties may return additional information on some systems; this is documented with each function where that is the case.

<cgi-exec PATHNAME &optional [ARG...] &key [OUTPUT=VARNAME] [ERRORS=VARNAME] [TIMEOUT=SECONDS] [NOWAIT=TRUE] Simple

Execute the system function named by PATHNAME, perhaps passing it arguments ARG ... ARGN.

If OUTPUT=VARNAME is supplied, then the variable referenced by VARNAME receives the output of the command. Otherwise, the resultant output is placed in the page.

If ERRORS=VARNAME is supplied, then VARNAME receives the error output of the command. Otherwise, the resultant output is placed in SYSTEM-ERROR-OUTPUT.

<dir::basename PATHNAME Simple

Return the "basename" of PATHNAME. This simply returns the last component of PATHNAME.

Example:

 <dir::basename /foo/bar/baz.dtd>

baz.dtd

<dir::canonicalize-pathname PATH Simple

Make PATH be absolute in the file system.

If PATH starts with a "/", then do nothing, otherwise, prefix it with mhtml::include-prefix and mhtml::relative-prefix.

Given an empty PATH, return the full path to the directory that this page resides in.

Example:

 <dir::canonicalize-pathname foo.mhtml>

/home/groups/m/me/metahtml/htdocs/documentation/manual/foo.mhtml

<dir::copy-file SOURCE DEST &key [ERRORS] Simple

Copy the file named SOURCE to the file named DEST, completely replacing the contents of destination file. Returns "true" if the file was successfully copied, or the empty string otherwise.

Both SOURCE and DEST are fully qualified pathnames -- they may point to anywhere in the file system, and are not directly related to web space at all.

The directory containing the destination file is created if it doesn't already exist.

<dir::create-emacs-backup PATHNAME &key [MAX] [FORCE] [ERRORS] Simple

Create an Emacs-style backup of PATHNAME, and return the name of the backup file. No more than MAX backups may exist -- if you pass MAX as a positive integer then multiple backups up to that many will be made. The default value for MAX is infinity.

If PATHNAME exists, a backup of it is made by appending "~num" to the name. If the most recent backup is within 1 hour of the existing file, no backup is made (unless FORCE is "true". Thus, we maintain some compatibility with the Emacs style of making backup files.

If PATHNAME is already a backup file, nothing is done.

<dir::dir-table &optional [WEBPATH] [REGEXP] &key [SHOW-ICONS=TRUE] [ICON-DIR=PATHNAME] [SORT=SORT-OP] [LINK=URL] Simple

Produces a clickable listing of the files in WEBPATH limited to those which match REGEXP, displaying icons found in ICON-DIR.

WEBPATH defaults to the directory containing this page.

REGEXP defaults to "(^[^.].*[^~]$)|(^\.\.$)|(^\.$)", i.e., files which do not begin with a dot, and files which do not end with a tilde, and the two special directories, `.' and `..'.

ICON-DIR defaults to /images/icons -- each file is associated with an icon file named by file extension (e.g, mhtml.gif, html.gif, etc.) Icons are only shown if SHOW-ICONS is set.

Possible values for SORT-OP are:

size: Order by size of file,
name: Order alphabetically by name,
type: Order by directory .vs. file, and filename extension,
created: Order by creation date,
accessed: Order by last access time, and
modified: Order by last modification time.

SORT-OP defaults to name.

<dir::dir-table>

<dir::dirname PATHNAME Simple

Return the directory part of PATHNAME. This simply returns everything but the last component of PATHNAME.

Example:

 <dir::dirname /foo/bar/baz.dtd>

/foo/bar

<dir::filename-extension FILENAME Simple

Return the filename extension of FILENAME, without the leading period. Returns the empty string if FILENAME doesn't have an extension.

 <dir::filename-extension /images/foo.gif>       ==> gif
 <dir::filename-extension /downloads/foo.tar.gz> ==> gz
 <dir::filename-extension /data/file>            ==>

<dir::filename-sans-extension FILENAME Simple

Return FILENAME without its extension part.

 <dir::filename-sans-extension /www/bin/foo.lib>

/www/bin/foo

<dir::handle-dots PATH Simple

Return PATH, resolving any "./" or "../" found within. Example:

 <dir::handle-dots /foo/bar/../baz/./../below-foo>

/foo/below-foo

<dir::names-in-dir &optional [DIR] [TYPE] [MATCHING] Simple

Return an array of the fully qualified pathnames in DIR which are of type TYPE (either "FILE" or "DIRECTORY") and which satisfy the regular expression MATCHING.

DIR defaults to the directory of the currently executing page.
TYPE defaults to "FILE".
MATCHING defaults to all possible filenames.

<dir::read-file FILENAME &optional [VARNAME] &key [ERRORS] Simple

Read in the contents of the file named by FILENAME and return them. If the optional variable VARNAME is given, it is the name of a binary variable to receive the contents of the file. In that case, the word "true" is returned if the file was successfully read, or the empty string otherwise.

 <dir::read-file /tmp/foo.gif gifdata> ==>true
 <set-var hosts[]=<dir::read-file /etc/hosts>>

<dir::write-file FILENAME VARNAME &key [MODE] [ERRORS] Simple

Write the contents of the variable named by VARNAME to the file named by FILENAME. Returns "true" if the file was written, and the empty string otherwise. MODE defaults to "write-create", thus creating the file. See with-open-stream for different values that can be supplied for MODE.

<directory-contents PATHNAME &optional [PACKAGE-NAME] &key [MATCHING=PATTERN] Simple

Returns a newline separated list of association lists for the files matching PATTERN.

When PACKAGE-NAME is supplied, each variable in PACKAGE-NAME is the name of a file in PATHNAME, and the value of each variable is the association list for that file.

<directory-p VAR Simple

Treat the argument VAR as the name of a variable which contains an alist produced by get-file-properties or directory-contents, and return "true" if the referenced file object is a directory, as opposed to a file.

<directory? PATHNAME Simple

Return "true" if PATHNAME is a directory, or "" if not.

<file-exists PATHNAME Simple

Returns "true" if PATHNAME is an existing file or directory.

PATHNAME is absolute, that is to say that it is looked up in absolute file system space, not in Web space. To find out if a file foo in the current directory exists, use:

<file-exists <thisdir>/foo>

<file-newer? FILE1 FILE2 Simple

Return "true" if FILE1 has been written more recently than FILE2.

Both FILE1 and FILE2 are fully qualified pathnames.

<get-file-properties PATHNAME Simple

Return an association-list containing operating system information about the file or directory named by PATH. PATHNAME must be given fully; it is not relative to Web space in any way.

If the file exists and is accessible, the members of the returned association-list which are guaranteed to be present are:

NAME: welcome.mhtml
The name of the file or directory, without any of the path information.
FULL-NAME: /www/site/docs/welcome.mhtml
The name of the file or directory, with full path information. This should be identical to PATH as received by <get-file-properties>.
SIZE: 2188
The size of the file in bytes.
TYPE: FILE
The type of the file. This will either be FILE or DIRECTORY.

In addition to the above fields, the following fields appear on Unix based systems:

CREATED: 6 29 96 10 3 24 897595648
The date on which this file was created. The value is an array, with ordered values being: month, day, year, hours, minutes, and seconds, and then the number of seconds since Jan 1st, 1970.
WRITTEN: 6 29 96 10 3 24 897595648
The date on which this file was last written. The value is an array, with ordered values being: month, day, year, hours, minutes, and seconds, and then the number of seconds since Jan 1st, 1970.
READ: 6 30 96 19 27 51 897595648
The date on which this file was last read. The value is an array, with ordered values being: month, day, year, hours, minutes, and seconds, and then the number of seconds since Jan 1st, 1970.
CREATOR: bfox
The system identifier of the user who created this file.

Example:

<dump-alist <get-file-properties />>

Dump of package: ^

CREATED:

03
05
113
00
51
36
1362444696

CREATOR: root

FULL-NAME: /

MODE: 755

NAME:

READ:

03
05
113
00
51
36
1362444696

SIZE: 4096

TYPE: DIRECTORY

WRITTEN:
1. 03
2. 05
3. 113
4. 00
5. 51
6. 36
7. 1362444696

<make-directories PATH &optional [MODE-STRING] &key [ERRORS] Simple

Create all of the directories in PATH (a fully qualified path to a directory) if they are not already present. If MODE-STRING is present, the final directory is set to that mode using the chmod() command.

<path::find-executable BASENAME Simple

Return the fully qualified path to the program which would be executed by CGI-EXEC for BASENAME.

Example:

 <path::find-executable ls> ==> /bin/ls

<require STEM Simple

require tries hard to locate the source or library file specified by STEM, and then loads that file if it hasn't already been loaded.

Both ` STEM.lib' and ` STEM.mhtml' are searched for -- <require> loads the one which is newer. In either case, if a function named ` .LIBINIT' is defined after the load, then that function is executed with 0 arguments, and the function definition is then removed.

If the variable mhtml::require-directories is present, then it is an array of directory names (without trailing slashes) relative to Web space that should be searched through, in the order that they appear in the array.

require understands the following extensions:

.mhtml, or .src: A Meta-HTML source file.
.lib: A Meta-HTML library file.

require loads the newest version of the file that it finds, and records the complete pathname of the loaded file in the array variable mhtml::require-loaded.

<unix::mkfifo FILENAME &optional [MODE-BITS] Simple

Create a named pipe on unix systems that support named pipes.

The pipe is named FILENAME and is created with the access mode specified by MODE-BITS, an octal permissions mask.

MODE-BITS defaults to 0666 if not specified.

After a named pipe is created, it can be written to and read from in the normal manner for writing and reading file streams.

UNIX::MKFIFO returns "true" if the named pipe could be created, or the empty string if not. In the case of an error, the human readable text of the error message appears in SYSTEM-ERROR-OUTPUT.

<webpath-exists DOCUMENT-PATH Simple

Returns "true" if the specified DOCUMENT-PATH exists with "/" being equal to the document root directory.

Edit Section
Function Index
Variable Index