"The Official Guide to Programming with OmniMark"
| HOME | COMPANY | SOFTWARE | DOCUMENTATION | EDUCATION & TRAINING | SALES & SERVICE | |
|
"The Official Guide to Programming with OmniMark" |
|
| International Edition | |
Previous chapter is Chapter 9, "Expressions And Operators".
Next chapter is Chapter 11, "Cross-Referencing and Hypertext Linking".
This chapter documents the features of OmniMark that can be used to obtain information from, and pass information to, the external world.
The facilities described here are:
The programmer can define their own interactions with the external world by writing and using external functions. These are described in Section 12.3, "External Functions".
DATE string-expression
The DATE operator is used to find the date and time at which the program is running, and format them in a suitable form. It can be used in any string expression.
COMPILED-DATE constant-string-expression
The COMPILED-DATE operator returns date and time information taken at the time that the OmniMark program was compiled.
The COMPILED-DATE operator can be used both in a general string expression or a constant string expression.
Note that the argument of COMPILED-DATE is a constant string primary in both contexts, so that even if it is used in a general string expression, its value can be determined at compile time.
The time and date information returned by COMPILED-DATE may vary within an OmniMark program, reflecting the fact that an OmniMark program takes some time to compile.
The operand of the DATE and COMPILED-DATE operators is a string expression containing ordinary characters and date format items and other format items. The ordinary characters are passed through unchanged, and the date format items and the other format items are replaced with the values that they indicate.
Date format items begin with an "=" character and have the following meanings:
the equals ("=") character itself
a lower-case letter indicating morning or afternoon/evening
an upper-case letter indicating morning or afternoon/evening
the English name of the month with the first letter capitalized and all the others not (e.g. "December").
the English name of the day of the week with the first letter capitalized and all the others not (e.g. "Tuesday").
the hour of the day in 24-hour form.
the hour of the day in 12-hour form.
the minute of the hour.
the second of the minute (without a fraction).
the second of the minute (with a fraction when available from the system on which the program is running).
the year.
the number of the month (January = 1, December = 12).
the number of the day in the month.
All of the date format items which produce a numeric string can be modified with the "x" date format modifier. When the "x" modifier is given, the value uses as many digits as are required to produce the full value. Without this modifier these values are represented by two digits, with a leading zero added or (for "=y") with leading digits truncated.
In the following examples, the comment at the end of each gives an example of what is output by the action on the line:
OUTPUT DATE "=H:=m:=s" ; 14:25:30 OUTPUT DATE "=xh:=m =a.m." ; 2:25 p.m. OUTPUT DATE "=W, =n =xD, =xY" ; Tuesday, December 18, 1990 OUTPUT DATE "=M/=D/=Y" ; 12/18/90
Other formats for dates and times can be produced by scanning the result of the DATE operator, or by using the results to index other shelves. For example, if the stream shelf nom-du-moin contains the names of the twelve months in French, the following will output the name of the current month:
OUTPUT nom-du-moin @ DATE "=n"
This example takes advantage of the fact that string expressions used in a numeric context are automatically converted to numeric expressions.
It is an error to have any character other than those listed above following an equals sign ("=") in the string passed to DATE. A string containing no equals signs, on the other hand, is valid: as with any other string containing no format items, it represents itself.
OmniMark provides two different kinds of information about itself through built-in stream shelves.
The built-in read-only stream shelf #LANGUAGE-VERSION contains a string describing the version of OmniMark that is currently running.
The form of the string returned by #LANGUAGE-VERSION is:
To compare the current OmniMark version with another one, the safest method is illustrated in the following example:
DO SCAN #LANGUAGE-VERSION
MATCH "V" DIGIT+ => v "R" DIGIT+ => r
DO WHEN v > 2 | (v = 2 & r >= 4)
OUTPUT "Version is at least V2R4.%n"
ELSE
OUTPUT "Version is prior to V2R4.%n"
DONE
DONE
#PLATFORM-INFO is a keyed built-in stream shelf that contains information about the platform that the currently-running OmniMark supports.
The key is used to select the particular piece of information desired. Currently, the shelf has an item with the key "os-class". This item describes the type (or class) of operating system that the currently-running OmniMark supports.
The possible values of this item are:
Additional values will be added as need arises.
WARNING: Do not depend on the order of the items in this shelf. Always use the key when looking for a specific piece of information.
For instance, code that assumes that a particular item is the last one on the shelf will likely break the next time that a new item is added. Similarly, code that assumes that a particular item is the first item on the shelf will also likely break in a future release. Always use the key.
An example of the use of this information is:
...
GLOBAL STREAM tmp-prefix
...
PROCESS-START
DO SCAN #PLATFORM-INFO ^ "os-class"
MATCH "MS-DOS"
SET tmp-prefix TO "C:\tmp\"
MATCH "UNIX"
SET tmp-prefix TO "/var/tmp/"
ELSE
PUT #ERROR "Unsupported platform "
|| #PLATFORM-INFO ^ "os-class"
HALT WITH 1
DONE
...
Other programs can be run from OmniMark with the SYSTEM-CALL feature. (This requires operating system support and may not be available on some systems.)
SYSTEM-CALL string-expression
The keyword SYSTEM-CALL must be followed by a string-expression that contains a system-specific command. SYSTEM-CALL invokes that command and returns the numeric result code returned by that command when it completes its task.
The string-expression contains the name of the program to run as well as any command-line arguments that are being passed to it.
Because the SYSTEM-CALL operator returns a numeric value, it must be used in a context where a numeric expression is required.
The functionality provided by SYSTEM-CALL and the value it returns depends on the system on which OmniMark is running. (The built-in stream shelf #PLATFORM-INFO can supply some of this information. See Section 10.2.2, "OmniMark Platform Information".)
In the following example, an editing session is called with the name of the file to edit. After the SYSTEM-CALL is made, a check for a negative value is made, which presumably means that the editor, "sled", could not be found. Note that because the SYSTEM-CALL is made in a condition, it occurs before the OUTPUT action actually takes place.
FIND "\input{" [ANY EXCEPT "}"]+ => file-name "}"
OUTPUT "Couldn't start the SLED editor%n"
WHEN SYSTEM-CALL "sled %x(file-name)" < 0
OmniMark provides many fundamental operations on files in addition to being able to write data into them through STREAM shelf items. The OmniMark programmer can:
OmniMark provides a number of tests that can determine whether a specified file exists or can be used in the way intended. This subsection describes those tests.
These tests can also fail if the named file or directory is inaccessible. In particular:
Various combinations of these tests are meaningful: a writable file may or may not exist; a directory may or may not be readable or writable.
FILE string-expression EXISTS
The "FILE ... EXISTS" tests whether the file named by the string-expression exists.
This test is useful for avoiding overwriting an existing file with a new one, as in the following example:
GLOBAL STREAM error-strm
...
DO WHEN FILE "errors.log" EXISTS
PUT #ERROR "File errors.log already exists.%n"
PUT #ERROR "Please delete or rename it before running this program.%n"
HALT WITH 1
ELSE
OPEN error-strm AS FILE "errors.log"
DONE
FILE string-expression (IS | ISNT) READABLE
The "FILE ... IS READABLE" operator returns TRUE if the file named by the string-expression exists and is readable by the OmniMark program. The keyword ISNT can be used instead of IS to reverse the sense of the test.
This can be done before executing an action that requires the file to be readable. If the file does not exist or is not readable, the programmer can choose an alternative path:
FIND "\input{" [ANY EXCEPT "}"]+ => filename "}"
DO WHEN FILE filename IS READABLE
SUBMIT FILE filename
ELSE
PUT #ERROR "File %x(filename) doesn't exist.%n"
PUT #ERROR "Processing continues... %n"
DONE
FILE string-expression (IS | ISNT) WRITABLE
The "FILE ... IS WRITABLE" operator returns TRUE if the file named by the string-expression exists and is writable by the OmniMark program, or if it does not exist but can be created. The keyword ISNT can be used instead of IS to reverse the sense of the test.
This test can be performed before opening a stream item as a file:
CROSS-TRANSLATE
GLOBAL STREAM out
FIND-START
DO WHEN FILE "myfile.out" IS WRITABLE
OPEN out AS FILE "myfile.out"
ELSE
PUT #ERROR "Cannot write to file 'myfile.out'.%n"
HALT WITH 1
DONE
FILE string-expression (IS | ISNT) DIRECTORY
The "FILE ... IS DIRECTORY" operator returns TRUE if the file system path named by the string-expression exists and is a directory. The keyword ISNT can be used instead of IS to reverse the sense of the test.
FILE string-expression (IS | ISNT) FILE
The "FILE ... IS FILE" operator returns TRUE if the file system path named by the string-expression exists and is a file (not a directory). The keyword ISNT can be used instead of IS to reverse the sense of the test.
File tests are often not needed in OmniMark programs because the default handling of file input/output error conditions is what most programmers would want to do themselves.
In particular, OmniMark displays a message with the file name involved, and terminates the program, when any of the following problems are encountered:
In most cases, the OmniMark program can just go ahead and read or write and let the OmniMark system take care of errors. The file tests exist for those cases where what the OmniMark system does is not appropriate.
For example, when searching a list of directories for a file, the correct response for an unreadable file or a directory is to try the next alternative.
(BINARY-MODE | TEXT-MODE)? FILE string-expression
The operator FILE (when not used in one of the above tests) retrieves the contents of the file named by the string-expression.
Usually, OmniMark reads the file in its entirety and uses the whole contents in the string expression. This can require large amounts of computer memory.
In certain limited cases, the file is read in smaller chunks, allowing very large files to be processed without requiring huge amounts of computer memory. These cases occur whenever the FILE expression is used:
The following examples both output a file, and append a newline. But the first example will process very large files, while the second may run out of memory:
Example A
... OUTPUT (FILE "myfile.in") || "%n"
Example B
...
REPEAT SCAN (FILE "myfile.in") || "%n"
MATCH (ANY-TEXT+ | "%n"+) => text
OUTPUT text
AGAIN
The BINARY-MODE or TEXT-MODE keywords affect the automatic processing of newlines in the file being read. When the programmer specifies the mode:
No processing is performed on the newlines.
The following sequences are translated to a single newline (ASCII 10) character:
On UNIX systems, the file is treated as a BINARY-MODE file. (On UNIX systems, the newline (ASCII 10) character is the system specific newline sequence, so no transformation is necessary for text files.)
On all non-UNIX systems, the file is treated as a TEXT-MODE file.
The following example reads the contents of the binary file "source.text" into a buffer attached to raw-text:
LOCAL STREAM raw-text SET raw-text TO BINARY-MODE FILE "source.txt"
SET FILE string-expression
open-modifiers TO string-expression
"SET FILE" is a convenient way to create a file when the entire contents can be described with a single string-expression. It can be used anywhere that the sequence "OPEN ... AS FILE", PUT, CLOSE would be used. As an example:
DOWN-TRANSLATE
...
ELEMENT copyright
SET FILE "copy.txt" TO "%c%n"
The same open-modifiers that can be used for OPEN can also be used for "SET FILE".
SET FILE "binfile.out" WITH BINARY-MODE TO BINARY-MODE FILE "binfile.in"
"SET FILE" is a convenient way to copy files, but is most useful when the right-hand-side refers to an "EXTERNAL SOURCE FUNCTION".
The string-expression is only evaluated as needed. This means that if the string-expression consists of any of the following alone or in a JOIN, they are processed "as needed". If the string-expression contains:
Next chapter is Chapter 11, "Cross-Referencing and Hypertext Linking".
Copyright © OmniMark Technologies Corporation, 1988-1997. All rights reserved.
EUM27, release 2, 1997/04/11.
|
|
|
|
|