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 filtering of the contents of hierarchical filesys-
tems. 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 par-
ticular 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.
Page 1 Plan 9 (printed 4/23/24)
ALPHABET-FS(1) ALPHABET-FS(1)
compose [-d] op -> selector
Compose implements ``compositing''-style opera-
tors, useful when merging filesystems. Op speci-
fies the operator, taking its name from the graph-
ical Porter-Duff equivalent: AinB, AinB, BinA,
AoutB, BoutA, A, AoverB, AatopB, AxorB, B, BoverA,
or BatopA. For instance, AinB gives the intersec-
tion 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 operators 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 levels 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 filtered - directo-
ries 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 com-
mand (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
variables are set giving information about the
mode, owner, modification time and size of the
entry (they are named after the equivalent field
names in the Dir structure; see sys-stat(2)). This
Page 2 Plan 9 (printed 4/23/24)
ALPHABET-FS(1) ALPHABET-FS(1)
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 environ-
ment variable set on one execution can be
retrieved on the next. The -t flag can be used to
specify a command which will be executed just
before termination.
match [-ar] pattern -> gate
Match is a gate that is open if the entry's file-
name 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 evaluated as a regu-
lar expression, otherwise it is a shell-style pat-
tern 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 permissions 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 path-
name 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
Page 3 Plan 9 (printed 4/23/24)
ALPHABET-FS(1) ALPHABET-FS(1)
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
specified, 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 specified, 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 con-
tain 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
Page 4 Plan 9 (printed 4/23/24)
ALPHABET-FS(1) ALPHABET-FS(1)
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 declara-
tions:
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/alphabet/auxi/fsfilter.b
/appl/cmd/fs/*.b
Page 5 Plan 9 (printed 4/23/24)
ALPHABET-FS(1) ALPHABET-FS(1)
SEE ALSO
sh-alphabet(1), alphabet-main(1), alphabet-fs(2), sh(1)
Page 6 Plan 9 (printed 4/23/24)