User's manual. Section 3.

NAMES(3): file names and predicates

SYNOPSYS

        path,predicate

DESCRIPTION

Many commands accept file names as arguments. A path name is / to refer to the root of the name space followed by one or more components (naming directories, except the last which might name a file). Path names not starting with / are understood as suffixes of the current directory (.). The name .. refers to the parent of the previous path (or the current directory if none). The parent of / is / itself.

In most cases, file names given to commands are not just path names. Usually, they are a combination of a path name and a predicate separated by a comma (,) character.

This combination is understood as a spec to search for and find matching files; commands rely on the [clive/zx(2)] Finder interface to issue the find request, and most of the times, they do so using the [clive/cmd(2)] pakcage.

The file search always starts at the path name given before the comma, and proceeds within the subtree rooted there. All files matching the predicate are selected and processed by the command considered.

An empty predicate is considered true, which means it selects all files within the subtree. For example, 

        lf .,

lists all files under the current directory, including also all directories and the current directory.

If the predicate is not supplied (i.e., there is no comma "," character), then only the name supplied is selected. For example 

        lf . | ch 0775

changes the mode of the current directory, but 

        lf ., | ch 0775

changes the mode for all files rooted at ., including ..

An empty name is understood as ".". Thus, 

        lf , | ch 0775

is exactly the same command.

A predicate is a boolean expression operating on directory entry attributes written in textual format. Besides the directory attribute names, the special name depth can be used to refer to the file depth in the tree rooted at the path used in the query. See dir(3) for a description of directory attributes.

The following expressions can be used as predicates:

true
always evaluates to true
false
always evaluates to false
name=value
compares for equality the value of the attribute name with value as a string.
=value
the same thing using the path attribute if value starts with /, and the name attribute otherwise.
d
is understood as type=d, and the same goes for - and c.
name==value
compares the value of the attribute name with value as a number.
name!=value
compares for inequality the value of the attribute name with value as a string. Prunes the search if the attribute is name or path and matches the value.
name~exp
matches exp against the value of the attribute name using globbing.
~exp
the same thing using the path attribute if value contains /, and the name attribute otherwise.
name~~regexp
matches regexp against the value of the attribute name. Prunes the search if the attribute is name or path and matches the value.
~~regexp
the same thing using the path attribute if value starts with /, and the name attribute otherwise.
name>value
compares (as a number) for greater-than the value of the attribute name with value.
name>=value
compares (as a number) for greater-or-equal-to the value of the attribute name with value.
name<value
compares (as a number) for less-than the value of the attribute name with value.
name<=value
compares (as a number) for less-or-equal-to the value of the attribute name with value.
number
is understood as depth<=number
prune
fails and prunes the search when evaluated (child files are ignored).

Also, if p1 and p2 are predicates, the following expressions can be used:

p1&p2
true if both predicates are true. If the first is false the second is not evaluated.
p1|p2
true if one of the predicates is true. If the first is true the second is not evaluated.
!p1
true if the predicate is false. If p1 is comparing for equality or matching the name or path attributes and p1 is true, the search is pruned (and the predicate is false).
(p1)
exactly like p1 (but useful to change the evaluation order).

Some operators have other names (as aliases) as described now. Although the aliases are preferred over the original names to save quotes in the shell, the original names can always be typed easily in most keyboards.
  • The operator "," is an alias of "&".
  • The operator ":" is an alias of " | "
  • The operator "≈" is an alias of "~~".
  • The operator "≠" is an alias of "!=".
  • The operator "≡" is an alias of "==".
  • The operator "≤" is an alias of "<=".
  • The operator "≥" is an alias of ">=".

The not operation has the higher precedence, then and and then or. Evaluation is left to right.

EXAMPLES

Similar to ls /*/*/foo in UNIX: 

        l /,path~/*/*/foo

Similar to find . -name '*.go' in UNIX: 

        l ,~*.go

SEE ALSO

User's manual. Section 3.