path: root/man/1/alphabet-fs

.TH ALPHABET-FS 1
.SH NAME
fs \- file-hierarchy traversal
.SH SYNOPSIS
.EX
load alphabet
typeset /fs
type /fs/fs
type /fs/entries
type /fs/gate
type /fs/selector
.EE
.SH DESCRIPTION
.B Fs
is a typeset for
.I alphabet
(see
.IR sh-alphabet (1))
which enables filtering of the contents of hierarchical filesystems.
.I Fs
defines four new types:
.TP 10
.B fs
The complete contents of a filesystem.
.TP
.B entries
Information about the entries in a filesystem without
their content.
.TP
.B gate
A condition that can be used with conditional verbs.
A gate is open to entries satisfying particular
criteria.
.TP
.B selector
A comparator which compares two entries
and selects one, both or neither of them.
.PP
In the following description of the verbs provided,
an entry such as:
.TP 10
.B print \fIentries\fP \fR->\fP status
.PP
describes a verb
.BR print ,
which takes one argument of type
.IR entries ,
and the result of which is of type
.BR status .
If the type is not one of those described above,
it should be taken to be of type
.IR string .
.PP
All types and modules names are taken to be relative to
the typeset root,
.BR /fs .
.PP
Modules defined within
.I fs
include:
.TP 10
\f5and\fP \fIgate gate\fP [\fIgate\fP...] -> \fIgate\fP
.B And
is a gate that is open to an entry if all its arguments are open.
.TP
\f5bundle\fP \fIfs\fP -> \fIvoid\fP
.B Bundle
converts
.I fs
to an archival format and writes it to the standard output.
.TP
\f5compose\fP [\f5-d\fP] \fIop\fP -> \fIselector\fP
.B Compose
implements ``compositing''-style operators, useful when
merging filesystems.
.I Op
specifies the operator, taking its name from
the graphical Porter-Duff equivalent:
.BR AinB ,
.BR AinB ,
.BR BinA ,
.BR AoutB ,
.BR BoutA ,
.BR A ,
.BR AoverB ,
.BR AatopB ,
.BR AxorB ,
.BR B ,
.BR BoverA ,
or
.BR BatopA.
For instance,
.B AinB
gives the intersection of A and B;
.B AatopB
gives A whereever both A and B exist, and B otherwise.
When used as a selector for
.BR 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
.B -d
option, compose will allow through directories that
would otherwise be excluded in this way, making
operators such as
.B AxorB
(all that A does not hold in common with B)
more useful, although accurate only for regular files.
.TP
\f5depth\fP \fIn\fP -> \fIgate\fP
.B Depth
is a gate open only to entries which are within
.I n
levels of the root of the filesystem.
.TP
\f5entries\fP \fIfs\fP -> \fIentries\fP
.B Entries
produces all the entries contained within
.IR fs .
.TP
\f5filter\fP  [\f5-d\fP] \fIfs\fP\fIgate\fP -> \fIfs\fP
The result of
.B filter
is a filesystem from which all entries that will
not pass through
.IR gate ,
and their descendents, have been removed.
If the
.B -d
flag is given, only files are filtered \- directories bypass the gate.
.TP
\f5ls\fP [\f5-um\fP] \fIentries\fP -> \fIvoid\fP
Print each entry in the style of
.B ls -l
(see
.IR ls (1)).
If the
.B -u
flag is given, the file access time rather than the file modification time
will be printed. If the
.B -m
flag is given, the name of the user that last modified the file
is printed too.
.TP
\f5exec\fP [\f5-pP\fP] [\f5-t\fP \fIcmd\fP] [\f5-n\fP \fIn\fP] \fIentries cmd\fP -> \fIvoid\fP
Run its argument
.I cmd
for each entry in
.I entries .
If the
.B -n
flag is specified,
.B exec
will try to gather
.I n
entries together before invoking the command (default 1).
The environent variable
.B $file
is set to the names of the entries that have been gathered.
If the
.B -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
.B Dir
structure; see
.IR sys-stat (2)).
This option is only valid when
.I n
is 1.
The
.B -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 execution can
be retrieved on the next. The
.B -t
flag can be used to specify a command which will be executed
just before termination.
.TP
\f5match\fP [\f5-ar\fP] \fIpattern\fP -> \fIgate\fP
.B Match
is a gate that is open if the entry's filename
matches the
.IR pattern .
If the
.B -a
flag is given, the whole path will be used
for the match.
If
.B -r
is specified, the pattern is evaluated as a regular expression,
otherwise it is a shell-style pattern in the style of
.IR filepat (2).
.TP
\f5merge\fP [\f5-1\fP] [\f5-c\fP \fIselector\fP] \fIfs fs\fP [\fIfs\fP...] -> \fIfs\fP
Recursively merge the contents of its argument
filesystems.
.I 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
.BR "{compose AoverB}").
If the
.B -1
flag is given, merging takes place only in the top-level directory.
.TP
\f5mode\fP \fIspec\fP -> \fIgate\fP
.B Mode
is a gate that lets through entries whose file permissions
satisfy
.IR spec ,
which is a string in the style of
.IR chmod (1).
If the
.I op
field is
.BR + ,
the specified permissions must be present; if
.BR - ,
they must be absent, and if
.BR = ,
they must be exactly as given.
The directory and auth modes are specified with
the characters ``\f5d\fP'' and ``\f5A\fP''
respectively.
.TP
\f5not\fP \fIgate\fP -> \fIgate\fP
.B Not
is a gate open to an entry if its argument is not.
.TP
\f5or\fP \fIgate gate\fP [\fIgate\fP...] -> \fIgate\fP
.B Or
is a gate open to an entry if any argument is open.
.TP
\f5path\fP [\f5-x\fP] \fIpath\fP... -> \fIgate\fP
.B Path
is a gate open to an entry whose full pathname
is an ancestor or a descendent of any
.IR path.
If
.B -x
is specified, the gate is open to any path
.I except
descendents of the paths given.
.TP
\f5pipe\fP [\f5-1pP\fP] \fIfs cmd\fP -> \fIstatus\fP
.B Pipe
is similar to exec, except that the contents of all files
in
.I fs
are piped through
.IR cmd .
Unless the
.B -1
option is given,
.I cmd
is started once for each file, with
.B $file
set to its name, and other environment variables
set according to the
.B -p
or
.B -P
options, as for
.BR exec .
If the
.B -1
option is specified,
.I cmd
is started once only \- all file data is piped through that.
.TP
\f5print\fP \fIentries\fP -> \fIfd\fP
Print the path name of each entry to
.IR fd .
.TP
\f5proto\fP [\f5-r\fP \fIroot\fP] \fIprotofile\fP -> \fIfs\fP
Evaluate
.I protofile
as a
.IR mkfs (8)
.I proto
file. If
.I root
is specified, it will be used as the root of the resulting
.IR fs .
.TP
\f5query\fP \fIcmd\fP -> \fIgate\fP
.B Query
is a gate that runs
.I cmd
to determine whether it is open: an empty
exit status from the command yields an open gate.
The environment variable
.B $file
is set for the command to the path name of the entry that is being queried for.
.TP
\f5run\fP \fIcmd\fP -> \fIstring\fP
.B Run
runs
.I cmd
and substitutes the value of the environment variable
.B $s
after its invocation.
.B $s
must have exactly one element.
.TP
\f5select\fP \fIgate entries\fP -> \fIentries\fP
Select only those entries within
.I entries
that will pass through
.IR gate .
Descendents of elided entries are not affected.
.TP
\f5setroot\fP [\f5-c\fP] \fIfs\fP \fIpath\fP -> \fIfs\fP
.B Setroot
sets the name of the root directory of
.IR fs .
If the
.B -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
.B /
characters).
.TP
\f5size\fP \fIentries\fP -> \fIfd\fP
Print the sum of the size of all entries, in bytes to
.IR fd .
.TP
\f5unbundle\fP \fIfd\fP -> \fIfs\fP
.B Unbundle
reads an archive as produced by
.B bundle
from
.IR fd ;
its result is the contents of the filesystem that was
originally bundled.
.TP
\f5walk\fP \fIpath\fP -> \fIfs\fP
.B Walk
produces a filesystem that is the result of
traversing all the files and directories underneath
.IR path .
.TP
\f5write\fP \fIfs dir\fP -> \fIvoid\fP
Write the contents of
.I fs
to the filesystem rooted at
.I dir .
If
.I dir
is empty,
.I fs
will be written to the root directory originally associated with fs.
.SH EXAMPLES
The examples below assume the following
.I alphabet
declarations:
.EX
	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}
.EE
Print the size of all files below the current directory:
.EX
	-{size .}
.EE
Show the names of all files in x that aren't in y:
.EX
	-{walk x | merge -c {compose -d AoutB} y | select {mode -d}}
.EE
Remove all files from /appl ending in
.BR .dis :
.EX
	-{walk /appl | select '*.dis' | exec "{rm $file}}
.EE
Recursively copy the current directory to
.BR /tmp/foo .
.EX
	-{write . /tmp/foo}
.EE
Interactively remove all regular files from one level of the current directory:
.IP
.EX
	-{walk . |
		filter {depth 1} |
		select {mode -d} |
		select {
			query "{echo -n $file:; ~ `{read} y yes}
		} |
		exec "{rm $file}
	}
.EE
.PP
Create a new archive containing those files from below the current directory
that were held in an old archive:
.EX
	-{merge -c {compose AinB} . {unbundle old.bundle} |
		bundle |
		/create new.bundle
	}
.EE
.SH SOURCE
.BR /appl/alphabet/fs.b ,
.BR /appl/alphabet/fstypes.b
.BR /appl/alphabet/auxi/fsfilter.b
.br
.B /appl/cmd/fs/*.b
.br
.SH SEE ALSO
.IR sh-alphabet (1),
.IR alphabet-main (1),
.IR alphabet-fs (2),
.IR sh (1)