From d774e7b23ea6b03e5999bc6ebdf3245efac8dd83 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Tue, 6 Apr 2021 22:27:57 -0400 Subject: File functions (partial) --- docs/spec/system.html | 178 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 154 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/spec/system.html b/docs/spec/system.html index 978a5610..d8a1e26d 100644 --- a/docs/spec/system.html +++ b/docs/spec/system.html @@ -7,7 +7,36 @@

Specification: BQN system-provided values

This portion of the spec is still potentially subject to major changes.

The • symbol is used to access values other than primitives provided by BQN.

-

All system values described in the BQN specification are optional: an implementation does not have to include any of them. However, if a system value with one of the names given below is included, then it must have the specified behavior.

+

All system values described in the BQN specification are optional: an implementation does not have to include any of them. However, if a system value with one of the names given below is included, then it must have the specified behavior. For namespaces this rule applies to individual fields as well: a namespace may be provided with only some of the fields, but a field with one of the given names must behave as specified.

+

Execution and scope manipulation

+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameSummary
•BQNEvaluate the argument string in an isolated scope
•EvalEvaluate the argument string in the current scope
•ScopedEvalEvaluate the argument string in a child scope
•UsingImport all values from the argument namespace
+

The effect of •Eval should be the same as if its argument were written as source code in the scope where •Eval appears. It can define variables, and modify those in the current scope or a parent.

+

•ScopedEval creates as new scope for evaluation as it is loaded. Other than its syntactic role, it is effectively equivalent to {•Eval}. Parent scopes are visible from the created scope; to make a scope without this property use •BQN"•Eval" or •BQN"•ScopedEval".

Scripts

@@ -40,7 +69,12 @@

•args is the arguments passed as the file was invoked, either from the command line or •Import. For command line calls it is a list of strings.

•path simply gives the path of the file in which it appears. It includes a trailing slash but not the name of the file itself.

•name gives the name, including the extension, of the file in which it appears. It doesn't include the path.

-

File access

+

Files

+

The system namespace value •file deals with file operations. For the purposes of •file, paths in the filesystem are always strings. As with •Import, file paths may be relative or absolute, and relative paths are relative to •path, except in •file.At which allows 𝕨 to specify an alternate base directory. The value •path used for a particular instance of •file is determined by the file that contains that instance.

+

When a •file function returns a file path or portion of a path, the path is always absolute and canonical, with . and .. components removed.

+

Possible fields of •file are given in the subsections below.

+

File paths

+

The following functions manipulate paths and don't access files. Each takes a relative or absolute path 𝕩, and At may also take a base directory 𝕨.

@@ -50,55 +84,151 @@ - - + + - - + + - - + + + + + + + + + + + + + + + + + +
•FCharsRead from or write to an entire file, as characterspathPath of this source file, that is, •path
•FLinesRead from or write to an entire file, as linesAtAbsolute path of file, with optional base 𝕨
•FBytesRead from or write to an entire file, as bytesNameFile name including extension
ParentPath of the containing directory, with trailing backslash
BaseNameFile name, with dot and extension removed
ExtensionFile extension, including leading dot
PartsList of parent, base name, and extension
-

As with •Import, file paths may be relative or absolute, and relative paths are relative to •path.

-

Functions •FChars, •FLines, and •FBytes are all ambivalent. If only one argument is given, then it must be the name of a file, and the result is the contents of the file in the appropriate format. If there are two arguments, then the left argument is the filename and the right is the desired contents. These are written to the file, overwriting its contents, and the filename 𝕨 is returned. The three formats are:

+

File metadata

+

Metadata functions may query information about a file or directory but do not read to or write from it. Each takes a path 𝕩, and Permissions also allows new data in 𝕨. The returned data in any case is the specified property.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSummary
Exists1 if the file exists and 0 otherwise
Type"none", "file", or "dir"
CreatedTime created
AccessedTime of last access
ModifiedTime of last modification
SizeTotal size in bytes
PermissionsQuery or set file permissions
+

Times are Unix timestamps, that is, seconds since the Unix epoch, as used by time system values.

+

File access

+

File access functions read or write files, either by manipulating files as a whole or interacting with the contents. Whole-file functions cannot overwrite target files: that is, Rename and Copy must give an error if a file exists at 𝕨, while Chars, Lines, and Bytes can overwrite the contents of an existing file 𝕨. However, these three functions must give an error if 𝕨 exists and is a directory.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSummary
OpenReturn an open file object based on 𝕩
RenameRename file 𝕩 with path 𝕨
CopyCopy file 𝕩 to path 𝕨
RemoveDelete file 𝕩
RemoveDirRecursively delete directory 𝕩 and all contents
CharsRead from or write to entire file, as characters
LinesRead from or write to entire file, as lines
BytesRead from or write to entire file, as bytes
+

Rename and Copy return the path of the new file. Remove and RemoveDir return 1 to indicate successful removal (and error otherwise).

+

Functions Chars, Lines, and Bytes are all ambivalent. If only 𝕩 is given, then it is a filename, and the result is the contents of the file in the appropriate format. If there are two arguments, then 𝕨 is the filename and 𝕩 is the desired contents. These are written to the file, overwriting its contents, and the absolute filename 𝕨 is returned. The three formats are:

-

Execution and scope manipulation

+

The following short names can also be provided for file access. They can be provided, and use the definitions from above even if •file is not provided.

- + - - - - - - + + - - + + - - + +
NameSummaryEquivalent
•BQNEvaluate the argument string in an isolated scope
•EvalEvaluate the argument string in the current scope•FChars•file.Chars
•ScopedEvalEvaluate the argument string in a child scope•FLines•file.Lines
•UsingImport all values from the argument namespace•FBytes•file.Bytes
-

The effect of •Eval should be the same as if its argument were written as source code in the scope where •Eval appears. It can define variables, and modify those in the current scope or a parent.

-

•ScopedEval creates as new scope for evaluation as it is loaded. Other than its syntactic role, it is effectively equivalent to {•Eval}. Parent scopes are visible from the created scope; to make a scope without this property use •BQN"•Eval" or •BQN"•ScopedEval".

+

Open file object

Input and output

-- cgit v1.2.3