diff options
Diffstat (limited to 'man/1/alphabet-fs')
| -rw-r--r-- | man/1/alphabet-fs | 425 |
1 files changed, 425 insertions, 0 deletions
diff --git a/man/1/alphabet-fs b/man/1/alphabet-fs new file mode 100644 index 00000000..c530ef3f --- /dev/null +++ b/man/1/alphabet-fs @@ -0,0 +1,425 @@ +.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) |