ref: e59ffed426f628794d4669f152eff9a6239b99db
dir: /man/1/fs/
.TH FS 1
.SH NAME
fs \- file-hierarchy traversal
.SH SYNOPSIS
.B fs
.I verb arg
...
.br
.SH DESCRIPTION
.B Fs
evaluates an expression whose values represent
the contents of a hierarchical filesystem.
There are six types of value:
.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.
.TP
.B string
A simple string literal, represented by itself,
or quoted according to the usual shell quoting rules.
.TP
.B command
A shell command, represented by an
.RB `` @ ''
character followed by a braced block
containing the shell commands.
.TP
.B void
No value. An expression of this type
cannot be used as an argument to any verb.
.PP
A value is represented either by a literal (a string or shell command),
or by a braced block,
.BI { verb
.RI [ arg ...]\f5}\fP,
whose value is the result of evaluating
.I verb
with the given arguments.
.PP
In the following description of the verbs provided,
an entry such as:
.TP 10
.B print \fIentries\fP \fR->\fP void
.PP
describes a verb
.BR print ,
which takes one argument of type
.IR entries ,
and the result of which is of type
.BR void .
If the type is not one of those described above,
it should be taken to be of type
.IR string .
.PP
With no arguments,
.I fs
prints a summary of the available verbs.
Verbs understood by
.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
\f5eval\fP \fIexpr\fP -> \fIany\fP
.B Eval
evaluates an
.I fs
expression and yields its result.
.TP
\f5filter\fP [\f5-d\fP]\fIgate fs\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 \fIcommand\fP] [\f5-n\fP \fIn\fP] \fIcommand entries\fP -> \fIvoid\fP
Run its argument
.I command
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] \fIcommand fs\fP -> \fIvoid\fP
.B Pipe
is similar to exec, except that the contents of all files
in
.I fs
are piped through
.IR command .
Unless the
.B -1
option is given,
.I command
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 command
is started once only \- all file data is piped through that.
.TP
\f5print\fP \fIentries\fP -> \fIvoid\fP
Print the path name of each entry.
.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 \fIcommand\fP -> \fIgate\fP
.B Query
is a gate that runs
.I command
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 \fIcommand\fP -> \fIstring\fP
.B Run
runs
.I command
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] \fIpath\fP \fIfs\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 -> \fIvoid\fP
Print the sum of the size of all entries, in bytes.
.TP
\f5unbundle\fP \fIfile\fP -> \fIfs\fP
.B Unbundle
reads an archive as produced by
.B bundle
from
.IR file ;
its result is the contents of the filesystem that was
originally bundled.
If
.I file
is
.IB `` - '',
the standard input is read.
.TP
\f5walk\fP \fIpath\fP -> \fIfs\fP
.B Walk
produces a filesystem that's the result of
traversing all the files and directories underneath
.IR path .
.TP
\f5write\fP \fIdir fs\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.
.PP
As a convenience,
.I fs
carries out some automatic type conversions
(conversions are applied recursively, so for instance,
an
.BR fs -valued
expression at the top level will converted
to void by applying
.B {print {entries
.IB fs }}\fR.
.TP
.BR string -> fs
The result is \f5{walk\fP \fIstring\f5}\fP.
.TP
.BR fs -> entries
The result is \f5{entries\fP \fIfs\f5}\fP.
.TP
.BR string -> gate
The result is \f5{match\fP \fIstring\f5}\fP.
.TP
.BR entries -> void
The result is \f5{print\fP \fIentries\f5}\fP.
.TP
.BR command -> string
The result is \f5{run\fP \fIcommand\f5}\fP.
.SH EXAMPLES
Print the size of all files below the current directory:
.EX
fs size .
.EE
Show the names of all files in x that aren't in y:
.EX
fs select {mode -d} {merge -c {compose -d AoutB} x y}
.EE
Remove all files from /appl ending in
.BR .dis :
.EX
fs exec @{rm $file} {select *.dis /appl}
.EE
Recursively copy the current directory to
.BR /tmp/foo .
.EX
fs bundle . | fs write /tmp/foo {unbundle -}
.EE
A simpler method of the above:
.EX
fs write /tmp/foo .
.EE
Interactively remove all regular files from one level of the current directory:
.IP
.EX
fs exec @{rm $file} {select {query
@{echo -n $file:; ~ `{read} y yes}}
{select {mode -d} {filter {depth 1} .}}}
.EE
.PP
Create a new archive containing those files from below the current directory
that were held in an old archive:
.EX
fs bundle {merge -c {compose AinB} . {unbundle old.bundle}} > new.bundle
.EE
.SH SOURCE
.B /appl/cmd/fs.b
.br
.B /appl/cmd/fs/*.b
.br
.B /appl/lib/fslib.b
.SH SEE ALSO
.IR sh (1)