- Proposals Process
- 200x Membership
- 1 Introduction
- 2 Terms, notation, and references
- 3 Usage requirements
- 4 Documentation requirements
- 5 Compliance and labeling
- 6 Glossary
- 7 The optional Block word set
- 8 The optional Double-Number word set
- 9 The optional Exception word set
- 10 The optional Facility word set
- 11 The optional File-Access word set
- 12 The optional Floating-Point word set
- 13 The optional Locals word set
- 14 The optional Memory-Allocation word set
- 15 The optional Programming-Tools word set
- 16 The optional Search-Order word set
- 17 The optional String word set
- 18 The optional Extended-Character word set
- Annex A: Rationale
- Annex B: Bibliography
- Annex C: Compatibility analysis
- Annex D: Portability guide
- Annex E: Reference Implementations
- Annex F: Test Suite
- Annex H: Alphabetic list of words
11 The optional File-Access word set
11.1 IntroductionThese words provide access to mass storage in the form of "files" under the following assumptions:
- files are provided by a host operating system;
- file names are represented as character strings;
- the format of file names is determined by the host operating system;
- an open file is identified by a single-cell file identifier (fileid);
- file-state information (e.g., position, size) is managed by the host operating system;
- file contents are accessed as a sequence of characters;
- file read operations return an actual transfer count, which can differ from the requested transfer count.
11.2 Additional terms
- file-access method:
- A permissible means of accessing a file, such as "read/write" or "read only".
- file position:
- The character offset from the start of the file.
- input file:
- The file, containing a sequence of lines, that is the input source.
11.3 Additional usage requirements
11.3.1 Data typesAppend table 11.1 to table 3.1.
184.108.40.206 File identifiersFile identifiers are implementation-dependent single-cell values that are passed to file operators to designate specific files. Opening a file assigns a file identifier, which remains valid until closed.
220.127.116.11 File access methods (18.104.22.168)File access methods are implementation-defined single-cell values.
22.214.171.124 File names
A character string containing the name of the file. The file name may include an implementation-dependent path name. The format of file names is implementation defined.
11.3.2 Blocks in files
Blocks may, but need not, reside in files. When they do:
- Block numbers may be mapped to one or more files by implementation-defined means. An ambiguous condition exists if a requested block number is not currently mapped;
- An UPDATEd block that came from a file shall be transferred back to the same file.
11.3.3 Input source
The File-Access word set creates another input source for the text interpreter. When the input source is a text file, BLK shall contain zero, SOURCE-ID shall contain the fileid of that text file, and the input buffer shall contain one line of the text file. During text interpretation from a text file, the value returned by FILE-POSITION for the fileid returned by SOURCE-ID is undefined. A standard program shall not call REPOSITION-FILE on the fileid returned by SOURCE-ID.
11.3.4 Other transient regions
The system provides transient buffers for S" and S\" strings. These buffers shall be no less than 80 characters in length, and there shall be at least two buffers. The system should be able to store two strings defined by sequential use of S" or S\". RAM-limited systems may have environmental restrictions on the number of buffers and their lifetimes.
When parsing from a text file using a space delimiter, control characters shall be treated the same as the space character.
Lines of at least 128 characters shall be supported. A program that requires lines of more than 128 characters has an environmental dependency.
See: 3.4.1 Parsing.
11.4 Additional documentation requirements
11.4.1 System documentation
126.96.36.199 Implementation-defined options
- file access methods used by
188.8.131.520 OPEN-FILE, 184.108.40.2064 R/O, 220.127.116.116 R/W and 18.104.22.1685 W/O;
- file exceptions;
- file line terminator (22.214.171.1240 READ-LINE);
- file name format (126.96.36.199 File names);
- information returned by 188.8.131.524 FILE-STATUS;
- input file state after an exception (184.108.40.2067 INCLUDE-FILE, 220.127.116.118 INCLUDED);
- maximum depth of file input nesting (11.3.3 Input source);
- maximum size of input line (11.3.5 Parsing);
- methods for mapping block ranges to files (11.3.2 Blocks in files);
- number of string buffers provided (11.3.4 Other transient regions);
- size of string buffer used by 11.3.4 Other transient regions.
18.104.22.168 Ambiguous conditions
- attempting to position a file outside its boundaries (22.214.171.1242 REPOSITION-FILE);
- attempting to read from file positions not yet written
- fileid is invalid (126.96.36.1997 INCLUDE-FILE);
- I/O exception reading or closing fileid (188.8.131.527 INCLUDE-FILE, 184.108.40.2068 INCLUDED);
- named file cannot be opened (220.127.116.118 INCLUDED);
- requesting an unmapped block number (11.3.2 Blocks in files);
- using 18.104.22.1688 SOURCE-ID when 7.6.1.0790 BLK is not zero;
- a file is required while it is being REQUIRED (22.214.171.1244.50) or INCLUDED (126.96.36.1998);
- a marker is defined outside and executed inside a file or vice versa, and the file is REQUIRED (188.8.131.524.50) again;
- the same file is required twice using different names (e.g., through symbolic links), or different files with the same name are provided to 184.108.40.2064.50 REQUIRED (by doing some renaming between the invocations of REQUIRED);
- the stack effect of including with 220.127.116.114.50 REQUIRED the file is not ( i * x -- i * x ).
18.104.22.168 Other system documentation
- no additional requirements.
11.4.2 Program documentation
22.214.171.124 Environmental dependencies
- requiring lines longer than 128 characters (11.3.5 Parsing);
- using more than eight levels of input-file nesting (11.3.3 Input source).
126.96.36.199 Other program documentation
- no additional requirements.
11.5 Compliance and labeling
11.5.1 Forth-2012 systemsThe phrase "Providing the File Access word set" shall be appended to the label of any Standard System that provides all of the File Access word set.
The phrase "Providing name(s) from the File Access Extensions word set" shall be appended to the label of any Standard System that provides portions of the File Access Extensions word set.
The phrase "Providing the File Access Extensions word set" shall be appended to the label of any Standard System that provides all of the File Access and File Access Extensions word sets.
11.5.2 Forth-2012 programsThe phrase "Requiring the File Access word set" shall be appended to the label of Standard Programs that require the system to provide the File Access word set.
The phrase "Requiring name(s) from the File Access Extensions word set" shall be appended to the label of Standard Programs that require the system to provide portions of the File Access Extensions word set.
The phrase "Requiring the File Access Extensions word set" shall be appended to the label of Standard Programs that require the system to provide all of the File Access and File Access Extensions word sets.
11.6.1 File Access words
- 11.6.1.0080 (
- 11.6.1.0765 BIN
- 11.6.1.0900 CLOSE-FILE
- 188.8.131.520 CREATE-FILE
- 184.108.40.2060 DELETE-FILE
- 220.127.116.110 FILE-POSITION
- 18.104.22.1682 FILE-SIZE
- 22.214.171.1247 INCLUDE-FILE
- 126.96.36.1998 INCLUDED
- 188.8.131.520 OPEN-FILE
- 184.108.40.2064 R/O
- 220.127.116.116 R/W
- 18.104.22.1680 READ-FILE
- 22.214.171.1240 READ-LINE
- 126.96.36.1992 REPOSITION-FILE
- 188.8.131.527 RESIZE-FILE
- 184.108.40.2065 S"
- 220.127.116.118 SOURCE-ID
- 18.104.22.1685 W/O
- 22.214.171.1240 WRITE-FILE
- 126.96.36.1995 WRITE-LINE
11.6.2 File-Access extension words
GeraldWodni Directory experiemental proposalProposal2016-12-12 15:42:57
In order to write cross platform and cross system libraries it is essential to have means to traverse a systems file structure. This proposal is based upon the only known (by the authors) widly adopted implementation in Gforth.
Authors: Ulrich Hoffmann & Gerald Wodni
Add new Type wdirid (or the like) to section 3.x
Words for traversal:
open-dir ( c-addr u – wdirid wior )
Open the directory specified by c-addr, u and return dir-id for futher access to it.
read-dir ( c-addr u1 wdirid – u2 flag wior )
Attempt to read the next entry from the directory specified by dir-id to the buffer of length u1 at address c-addr. If the attempt fails because there is no more entries, ior=0, flag=0, u2=0, and the buffer is unmodified. If the attempt to read the next entry fails because of any other reason, return ior<>0. If the attempt succeeds, store file name to the buffer at c-addr and return ior=0, flag=true and u2 equal to the size of the file name. If the length of the file name is greater than u1, store first u1 characters from file name into the buffer and indicate "name too long" with ior, flag=true, and u2=u1.
close-dir ( wdirid – wior )
Close the directory specified by dir-id.
mkdir ( c-addr u – wior )
create the directory c-addr u and all its parents Remark: renamed mkdir-parents to mkdir, removed unix-specific umask
Words for pathes:
Description take from the Node.js manual:
path-normalize ( c-addr-1 u1 -- c-addr-1 u-2 )
Normalize a string path, taking care of '..' and '.' parts. When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved.
path-basename ( c-addr-1 u1 -- c-addr-2 u-2 )
Return the last portion of a path. Similar to the Unix basename command.
path-dirname ( c-addr-1 u1 -- c-addr-2 u-2 )
Return the directory name of a path. Similar to the Unix dirname command.
path-extname ( c-addr-1 u1 -- c--addr-2 u-2 )
Return the extension of the path, from the last '.' to end of string in the last portion of the path. If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string.
path-absolute? ( c-addr-1 u1 -- f )
Determines whether path is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory.
path.join ( c-addr-1 u1 c-addr2 u2 -- c-addr-3 u3 )
Join all arguments together and normalize the resulting path. Arguments must be strings. Use implicit allocation?