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.

     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

     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

     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

     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

     ALPHABET-FS(1)                                     ALPHABET-FS(1)

     SEE ALSO
          sh-alphabet(1), alphabet-main(1), alphabet-fs(2), sh(1)