ALPHABET-FS(1)ALPHABET-FS(1)NAME
fs - file-hierarchy traversal
SYNOPSIS
load alphabet
typeset /fs
type /fs/fs
type /fs/entries
type /fs/gate
type /fs/selector
DESCRIPTION
Fs is a typeset for alphabet (see sh-alphabet(1)) which enables filter‐
ing of the contents of hierarchical filesystems. Fs defines four new
types:
fs The complete contents of a filesystem.
entries Information about the entries in a filesystem without their
content.
gate A condition that can be used with conditional verbs. A gate
is open to entries satisfying particular criteria.
selector A comparator which compares two entries and selects one, both
or neither of them.
In the following description of the verbs provided, an entry such as:
print entries -> status
describes a verb print, which takes one argument of type entries, and
the result of which is of type status. If the type is not one of those
described above, it should be taken to be of type string.
All types and modules names are taken to be relative to the typeset
root, /fs.
Modules defined within fs include:
and gate gate [gate...] -> gate
And is a gate that is open to an entry if all its arguments
are open.
bundle fs -> void
Bundle converts fs to an archival format and writes it to the
standard output.
compose [-d] op -> selector
Compose implements ``compositing''-style operators, useful
when merging filesystems. Op specifies the operator, taking
its name from the graphical Porter-Duff equivalent: AinB,
AinB, BinA, AoutB, BoutA, A, AoverB, AatopB, AxorB, B,
BoverA, or BatopA. For instance, AinB gives the intersection
of A and B; AatopB gives A whereever both A and B exist, and
B otherwise. When used as a selector for merge, operators
that exclude the union of A and B are not very useful, as
they will exclude all common directories at the top level.
Given the -d option, compose will allow through directories
that would otherwise be excluded in this way, making opera‐
tors such as AxorB (all that A does not hold in common with
B) more useful, although accurate only for regular files.
depth n -> gate
Depth is a gate open only to entries which are within n lev‐
els of the root of the filesystem.
entries fs -> entries
Entries produces all the entries contained within fs.
filter [-d] fsgate -> fs
The result of filter is a filesystem from which all entries
that will not pass through gate, and their descendents, have
been removed. If the -d flag is given, only files are fil‐
tered - directories bypass the gate.
ls [-um] entries -> void
Print each entry in the style of ls -l (see ls(1)). If the
-u flag is given, the file access time rather than the file
modification time will be printed. If the -m flag is given,
the name of the user that last modified the file is printed
too.
exec [-pP] [-t cmd] [-n n] entries cmd -> void
Run its argument cmd for each entry in entries . If the -n
flag is specified, exec will try to gather n entries together
before invoking the command (default 1). The environent
variable $file is set to the names of the entries that have
been gathered. If the -p flag is given, environment vari‐
ables are set giving information about the mode, owner, modi‐
fication time and size of the entry (they are named after the
equivalent field names in the Dir structure; see sys-
stat(2)). This option is only valid when n is 1. The -P
flag causes all the other fields in the Dir structure to be
included too. Note that the command is run in the same shell
context each time, so environment variable set on one execu‐
tion can be retrieved on the next. The -t flag can be used to
specify a command which will be executed just before termina‐
tion.
match [-ar] pattern -> gate
Match is a gate that is open if the entry's filename matches
the pattern. If the -a flag is given, the whole path will be
used for the match. If -r is specified, the pattern is eval‐
uated as a regular expression, otherwise it is a shell-style
pattern in the style of filepat(2).
merge [-1] [-c selector] fs fs [fs...] -> fs
Recursively merge the contents of its argument filesystems.
Selector is consulted to see which entries are chosen for the
result; if not given, entries are resolved in favour of the
first filesystem (equivalent to {compose AoverB}). If the -1
flag is given, merging takes place only in the top-level
directory.
mode spec -> gate
Mode is a gate that lets through entries whose file permis‐
sions satisfy spec, which is a string in the style of
chmod(1). If the op field is +, the specified permissions
must be present; if -, they must be absent, and if =, they
must be exactly as given. The directory and auth modes are
specified with the characters ``d'' and ``A'' respectively.
not gate -> gate
Not is a gate open to an entry if its argument is not.
or gate gate [gate...] -> gate
Or is a gate open to an entry if any argument is open.
path [-x] path... -> gate
Path is a gate open to an entry whose full pathname is an
ancestor or a descendent of any path. If -x is specified,
the gate is open to any path except descendents of the paths
given.
pipe [-1pP] fs cmd -> status
Pipe is similar to exec, except that the contents of all
files in fs are piped through cmd. Unless the -1 option is
given, cmd is started once for each file, with $file set to
its name, and other environment variables set according to
the -p or -P options, as for exec. If the -1 option is spec‐
ified, cmd is started once only - all file data is piped
through that.
print entries -> fd
Print the path name of each entry to fd.
proto [-r root] protofile -> fs
Evaluate protofile as a mkfs(8) proto file. If root is speci‐
fied, it will be used as the root of the resulting fs.
query cmd -> gate
Query is a gate that runs cmd to determine whether it is
open: an empty exit status from the command yields an open
gate. The environment variable $file is set for the command
to the path name of the entry that is being queried for.
run cmd -> string
Run runs cmd and substitutes the value of the environment
variable $s after its invocation. $s must have exactly one
element.
select gate entries -> entries
Select only those entries within entries that will pass
through gate. Descendents of elided entries are not
affected.
setroot [-c] fs path -> fs
Setroot sets the name of the root directory of fs. If the -c
flag is given, the elements in the root directory will be
made explicit in the hierarchy (i.e. the name of the top
directory will not contain any / characters).
size entries -> fd
Print the sum of the size of all entries, in bytes to fd.
unbundle fd -> fs
Unbundle reads an archive as produced by bundle from fd; its
result is the contents of the filesystem that was originally
bundled.
walk path -> fs
Walk produces a filesystem that is the result of traversing
all the files and directories underneath path.
write fs dir -> void
Write the contents of fs to the filesystem rooted at dir .
If dir is empty, fs will be written to the root directory
originally associated with fs.
EXAMPLES
The examples below assume the following alphabet declarations:
load alphabet
typeset /fs
type /string /fd /fs/fs /fs/entries /fs/gate
import /fs/size /fs/walk /fs/select /fs/mode /fs/merge
import /fs/compose /fs/exec /fs/bundle /fs/write /fs/unbundle
import /fs/print /fs/depth /fs/filter /fs/query
autoconvert string fs walk
autoconvert fs entries /fs/entries
autoconvert string gate /fs/match
autoconvert entries fd /fs/print
autoconvert fd /status {(/fd); /print $1 1}
Print the size of all files below the current directory:
-{size .}
Show the names of all files in x that aren't in y:
-{walk x | merge -c {compose -d AoutB} y | select {mode -d}}
Remove all files from /appl ending in .dis:
-{walk /appl | select '*.dis' | exec "{rm $file}}
Recursively copy the current directory to /tmp/foo.
-{write . /tmp/foo}
Interactively remove all regular files from one level of the current
directory:
-{walk . |
filter {depth 1} |
select {mode -d} |
select {
query "{echo -n $file:; ~ `{read} y yes}
} |
exec "{rm $file}
}
Create a new archive containing those files from below the current
directory that were held in an old archive:
-{merge -c {compose AinB} . {unbundle old.bundle} |
bundle |
/create new.bundle
}
SOURCE
/appl/alphabet/fs.b, /appl/alphabet/fstypes.b /appl/alpha‐
bet/auxi/fsfilter.b
/appl/cmd/fs/*.b
SEE ALSOsh-alphabet(1), alphabet-main(1), alphabet-fs(2), sh(1)ALPHABET-FS(1)
