The OMVFS library allows you to manipulate files and directories and to read and write data in files.
The OMVFS library is intended to provide a unified interface to files and directories regardless of their location or the protocol used to access the them. Full OMVFS functionality is being delivered in stages. The current version supports full functionality for accessing the local file system and partial functionality for accessing FTP, HTTP, and HTTPS servers.
OMVFS supports the use of either local system paths or URLs for specifying files and directories. You must use URLs to access external file systems such as FTP or HTTP. You may use either local system paths or URLs to access the local file system. If you know that your function will only be accessing files on the local file system, we recommend that you use local file paths.
OMVFS support both a generic open function (vfs.open) and protocol specific open functions (vfs.open-ftp, etc.). Protocol specific functions provide support for additional parameters that may not be supported by the generic open command, or may require the insertion of additional information into the URL. For flexibility, and ease of typing, we recommed that you use the generic vfs.open function unless you need to use one of the protocol specific open functions for the functionality it provides.
One of the principal advantages of using the generic vfs.open function is that it can be used to open different types of file systems at different points in the run of your program. For instance, it could be used in an application that gathered URLs from a web page and then downloaded the information pointed to by those links.
Here is a very simple example of the versatility of vfs.open. The following program can be used to display a file on the console and can accept a local file path, or a file, ftp, or http URL as an argument:
; showany.xom import "omvfs.xmd" prefixed by vfs. process local vfs.file f set f to vfs.open #args[1] output vfs.reader of f
For example, you can print out raw markup of the Stilo homepage with a command line like this:
omcpe -s showany.xom http://www.stilo.com/
The OMVFS library contains two opaque data types, vfs.file and vfs.directory.
You can think of vfs.file as a file handle or a file object. It is used to read and write files, to lock and unlock files, and to retrieve information about files.
The vfs.directory object is designed to act as a handle or object to represent a directory. It is intended mostly to manage the connection to external directories or directory-like data sources over HTTP or FTP protocols. Since the use of vfs.directory is not currently supported for these protocols, we recommend that you not use vfs.directory at this time.
The OMVFS library is packaged as a module. To use OMVFS, you must import the OMVFS module into your program using a statement like this:
import "omvfs.xmd" prefixed by vfs.
Note that the prefix "vfs.", which is attached to all functions, constants, and opaque data types exported by this library, is set in this statement and can be changed. For readability, we recommend that you always use the standard prefix when importing modules supplied by OmniMark.
All file system paths in omvfs operations are system independent and use the "/" UNIX-style separator. Windows style paths are supported when running under Windows.
Here is a sample program that will list all files in /temp/ which have been modified more recently than 8 am October 31st EST, 2000.
process local stream listing variable local stream list-dir set list-dir to "c:/temp/" vfs.list matching (list-dir || "*") into listing include vfs.all-files repeat over listing local stream attrs variable vfs.describe (list-dir || listing) into attrs output listing || '%n' when ymdhms-second-difference ( attrs{"mtime"}, "20001131080000-0500" ) > 0 again
This is a complete list of the VFS library external exceptions that may be
thrown back to the calling OmniMark program. These are all catchable using
the #external-exception label.
VFS001 The requested function is not supported for the type of connection VFS002 The requested function is only available on UNIX platforms VFS003 vfsDir objects cannot be created for local paths VFS004 The specified name exceeds system length limits: VFS005 Memory could not be allocated VFS006 An internal error has occurred in omvfs VFS100 The vfsDir object must be connected before it can be used VFS101 The connection location must be specified as an absolute or relative path in URL format: VFS105 The path is not a valid absolute or relative path: VFS109 An invalid value was specified for the content type include indicator VFS111 The URL contains invalid encoding: VFS200 The vfsFile object must be opened before it can be used VFS201 An invalid value was specified for the file access VFS203 The file name 'X' must be specified as a file with optional absolute or relative path information or as an URL VFS204 The file 'X' must not have an active output or source associated with it VFS206 The file 'X' must be opened with write access to enable writing to it VFS207 The file 'X' must be opened with read access to enable reading from it VFS209 An invalid value was specified for the absolute cursor movement VFS210 Absolute and relative cursor movement may not both be specified VFS211 The cursor cannot be positioned before the start of the file VFS212 An invalid value was specified for the start of the locked region VFS213 An invalid value was specified for the end of the locked region VFS214 An invalid timeout value was specified VFS215 The locked region must be at least one character long VFS216 The specified lock region overlaps an existing lock region for the file VFS217 The function timed out before the lock could be obtained on 'X' VFS218 An invalid lock ID was specified VFS300 Generic operating system error VFS301 The directory 'X' does not exist VFS302 The buffer length received from OmniMark is out of range VFS305 The directory 'X' is not empty VFS306 The file 'X' does not exist VFS307 The path 'X' exists VFS308 This function is not available on this operating system VFS309 At least one of owner and group must be specified VFS310 Insufficient permissions to complete operation VFS311 Could not read data VFS312 Could not write data VFS400 Protocol error: VFS500 Protocol unsupported on this platform.