AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs
File typedict
 
A File is a type of Stream used by Yoix for file I/O, that usually represents locally stored data identified by the name and fullname fields. On systems that support Microsoft's UNC setting name to a field that looks like 
//ComputerName/SharedFolder/Resource
can be used to create a File that represents a network resource. Yoix always lets you use the the slash character / to delimit the components in name, but the platform dependent separator character also works, so on a Windows system the more familiar notation 
\\ComputerName\SharedFolder\Resource
references the same network resource. Yoix also uses File streams when I/O is needed for a Process or a Socket, as well as for the stderr, stdin and stdout streams. The complete set of fields in a File are:
autoready When set to a non-zero int value, read attempts on the stream will return an end-of-input indication rather than block when the stream has no input available. An alternative to avoid a blocking read is to check the value of ready before doing a read.
bufsize For efficiency, reading and writing is buffered up to the number of characters indicated by this int. Changing bufsize after a stream is used to read or write is not allowed and will result in an invalidaccess error.
callback(int mode [, Function func[, int trigger]]) A built-in for associating a user function with reading or writing activity. The mode can be READ, WRITE or EOF. When the mode is READ or WRITE, a trigger should also be supplied in addition to the user-defined function, func. Once a callback for a particular mode is defined, then the supplied values for func and trigger can be retrieved by omitting those arguments in the call to this built-in. When the mode is READ or WRITE, the supplied user function is called whenever the byte count exceeds the trigger value. When the mode is EOF, the user function is called when read operations reach the end of the stream. The byte count of activity since the callbacks were set-up is automatically supplied as the sole argument to the user function when it is called. Note that the byte count increments depend on the Stream buffer size. Thus, a trigger value of 5000 with a buffer size of 4096 means that the first function call occurs when the byte count is 8192, namely after the stream buffer is filled for the second time. This built-in is useful for providing interactive feedback using, for example, a JProgressBar.
checksum When a checksum filter is activated, the current checksum value can be obtained from this double. Note that for BSD and SYSV checksums, the built-in chkstr can be used to convert the value here to the more familiar string format. Writing any value to this field causes the checksum calculation to be reset.
cipher allows the assigning of a cipher to the stream when either reading or writing. The cipher should be suitable for the encrypting or decrypting of a large number of bytes as opposed to a small number as might occur in a signature. When assigning to this field, the value can be one of the following: a Cipher, an Array or a Dictionary. When the value is a Dictionary, it should contain at least two String fields, one called transformation and the other called keystring. Optionally, there can be a String field called provider. These field names correspond to those found in the Cipher object and have the same meaning. The same information can be supplied in shorthand via an Array. In that case, two array elements can provide transformation and keystring information, respectively, while three array elements can provide transformation, provider and keystring information, respectively. When either an Array or Dictionary is used, the mode of the cipher is automatically set to ENCRYPT_MODE for a stream that is writing and to DECRYPT_MODE for a stream that is reading. Changing cipher after a stream is used to read or write is not allowed and will result in an invalidaccess error.
encoding A String that indicates the type of byte-to-char encoding used when reading or the char-to-byte encoding used for writing. Changing encoding after a stream is used to read or write is not allowed and will result in an invalidaccess error.
filters One or more int flags can be combined to indicate how the stream should be filtered either for input or output. The flags are:
BSD Indicates that a BSD-style checksum should be calculated on the stream.
CRC32 Indicates that a CRC32-style checksum should be calculated on the stream.
GZIP Indicates that the stream should use gzip compression when writing or gzip decompression when reading.
HEXCODER Indicates that the stream should use hex encoding when writing or hex decoding when reading. Hex coding converts each character into bytes using ISO-8859-1 encoding and then converts each byte into a two character hexadecimal string with the high nybble first.
IETFCODER Indicates that the stream should use IETF RFC 2396 encoding when writing or IETF RFC 2396 decoding when reading. IETF RFC 2396 encoding is used, for example by perl's uri_escape.
LINEDHEXCODER Indicates that the stream should use fixed line length hex encoding when writing or hex decoding that ignores line breaks when reading. Output in this case is limited to 60 hex characters before a line break is inserted.
MIMECODER Indicates that the stream should use x-www-mime-urlencoded encoding when writing or x-www-mime-urlencoded decoding when reading. x-www-mime-urlencoded encoding is used, for example by Java's URLEncoder class.
SYSV Indicates that a SYSV-style checksum should be calculated on the stream.
ZIPPED Indicates that the stream should create when writing or decode when reading a stream of bytes consistent with the ZIP format (such as Java jar files or PKZIP files).
If checksum flags are used in combination with other checksum flags, the result is to default to a SYSV checksum. Changing filters after a stream is used to read or write is not allowed and will result in an invalidaccess error.
flushmode An int value that indicates the flushing strategy to use when writing. The value can be one of:
FLUSHDISABLED Do not flush output automatically except when the output buffer is full.
FLUSHLINES Flush output after each line-at-a-time write request. Note that writing an end-of-line character will not automatically cause a flush.
FLUSHWRITES Flush output after each write request.
An alternative is to explicitly call the fflush built-in.
fullname A read-only String that is the full pathname of the file as determined by yoixPath when an underlying file is involved.
interrupted An int that counts the number of times read operations on this file are interrupted. An interrupted read operation automatically increments interrupted before returning a value that indicates the end-of-input. Writing is allowed and is the only way to reset interrupted to zero.
marksupported An int value indicating if the mark and reset built-ins are supported by this stream. A non-zero value means that they are supported.
mode An int value describing the mode of access. The value is some combination of the following flags:
APPEND If the underlying file already exists, do not destroy its contents and position access at the end of the file.
READ Access the file for reading.
UPDATE When reading and writing to an existing file, do not destroy its contents initially, but position access at the beginning of the file.
WRITE Access the file for writing.
It is possible to access a file for reading and writing in the same stream, in which case the built-ins seek and getFilePointer will be of value. Changing mode while a stream is open is not allowed and will result in an invalidaccess error.
name A String that identifies the stream or underlying file. The components in name can be separated by the slash character, /, or by the platform dependent file separator character. Changing name while a stream is open is not allowed and will result in an invalidaccess error.
nextbuf If the stream is open for writing, then assigning a String to this field will write it to the stream. If the stream is open for reading, then by requesting the value of this field, up to bufsize characters will be read from the stream and returned. When there is nothing to read, NULL is returned.
nextchar If the stream is open for writing, then assigning a int within the range 0 to 0xFFFF to this field will write it to the stream as a character. If the stream is open for reading, then by requesting the value of this field, the next character will be read from the stream and returned. When there is nothing to read, NULL is returned.
nextentry When a ZIPPED filter is active and the stream is open for writing, then assigning a ZipEntry to this field will write it to the stream, appropriately closing any existing entry being written. When a ZIPPED filter is active and the stream is open for reading, then requesting the value of this field causes the current entry being read, if any, to be closed and a ZipEntry describing the next entry int the stream to be returned. When there is nothing to read, NULL is returned. Accessing this field when a ZIPPED filter is not active causes an invalidaccess error.
nextline If the stream is open for writing, then assigning a String to this field will write it to the stream with a new-line appended. If the stream is open for reading, then by requesting the value of this field, all characters up to the next new-line will be returned from the input stream. The new-line itself is not returned. When there is nothing to read, NULL is returned.
open An int value indicating the open/close status of the stream. A non-zero value indicates the stream is open for access. Setting this value causes the stream to be opened or closed.
ready An int value indicating, when it is non-zero, that the stream can be read without blocking.
size The size of the underlying file. If the stream is not associated with an underlying file, then for an output stream, the value is the number of characters written to the stream so far, while for an input stream the value is the number of characters read from the stream so far.
Several permanent fields have not been documented and should not be used in Yoix applications. Certain File fields, namely: can have side-effects when accessed. Therefore, they must be explicitly referenced for their value to be retrieved. Simply dumping the entire File will only display a default value for these fields.
 
 Example:   The program, 
import yoix.*.*;

String line;

File outfile = {
    String name = "output.txt";
    int    mode = WRITE;
    int    open = TRUE;
};

while(line = stdin.nextline) {
    stdout.nextline = line;
    outfile.nextline = line;
}

fprintf(stderr,
    "Read %d chars, wrote %d chars, file contains %d bytes.\n",
    stdin.size, stdout.size, outfile.size
);

outfile.open = FALSE;
gets its input from stdin and writes it to stdout and a file called output.txt in the current directory. It then gives a summary of I/O counts on stderr. If the input to the script were the script itself, then the result on stderr would be as follows: 
Read 423 chars, wrote 423 chars, file contains 423 bytes.
on standard output.
 
 See Also:   close, fopen, open, read, readChar, readLine, readStream, Stream, StringStream, URL, write, writeChar, writeLine, yoixPath, ZipEntry

 

Yoix is a registered trademark of AT&T Inc.