1 07/30/86  Star Convention (general information)
  2 
  3 Many commands accept starnames to identify the entities to be examined
  4 or operated upon.  Starnames are names containing wildcard characters
  5 which can be used to specify sets of entities.  These wildcard
  6 characters can also be used as a typing aid to reduce the number of
  7 typed characters needed to identify a single file.  The star convention
  8 defines the wildcard characters and matching criteria.
  9 
 10 
 11 Starnames are constrained by the application.  Commands which use
 12 starnames to match file or directory names permit the final entryname
 13 in a pathname to be a starname.  In this case, the starname is also an
 14 entryname and is subject to the restrictions on entrynames such as the
 15 32 character limit.  Such a command would match the starname against
 16 the names of all of the entries in the directory (as determined from
 17 the pathname) and select those entries of appropriate type which have
 18 at least one matching name.
 19 
 20 
 21 A starname matches links if the command utilizing the star convention
 22 operates on the link itself.  In general, commands do not work upon the
 23 targets of links matching a starname.  Similarly, a starname matches
 24 every entryname of an entry if it operates on name attributes.
 25 Otherwise, an entry is generally selected only once even if it has
 26 several names matched by the starname.
 27 
 28 
 29 Rules for Constructing Starnames:
 30 
 31 1.  A starname is a character string.
 32 
 33 2.  A starname is made up of components.  The components are delimited
 34     by beginning and end of the name, and by the period (.) character,
 35     which is referred to as a dot.
 36 
 37 3.  Each question mark (?) character appearing in a starname is treated
 38     as a special character.
 39 
 40 4.  Each asterisk (*) character, which is referred to as a star,
 41     appearing in a starname is treated as a special character.
 42 
 43 
 44 5.  Each occurance of two consecutive asterisks (**), called a
 45     doublestar, appearing in a starname is treated specially.
 46 
 47 6.  Each component consisting only of a doublestar, called a doublestar
 48     component, is treated specially.
 49 
 50 7.  Three or more consecutive asterisks (***) are invalid.
 51 
 52 
 53 Interpreting Starnames: A starname is compared to a set of names.
 54 Those names which meet the following criteria are considered to match
 55 the starname.
 56 
 57 1.  If the starname contains no special characters (stars or question
 58     marks), then the rules for PL/I string comparison are used.
 59 
 60 2.  Trailing ASCII space characters are not significant.
 61 
 62 3.  Each nonspecial character matches itself literally.  The matching
 63     constructs must be in one to one correspondence between the
 64     starname and the matched name, in the same order.
 65 
 66 4.  Each question mark matches exactly one character within a
 67     component, so it matches any single character except dot.
 68 
 69 
 70 5.  Each star matches any number of characters within a component, so
 71     it matches any number (including zero) of any character except dot.
 72 
 73 6.  Each doublestar matches any number of characters, including zero.
 74 
 75 7.  Each doublestar component matches any number of entire components,
 76     including zero.  Note that the dot or dots delimiting the
 77     doublestar component match component boundaries, and if zero
 78     components are matched, they match the same boundary.  The boundary
 79     can be a dot or the beginning or end of the matched name.
 80 
 81 
 82 List of starname examples:  The following examples illustrate some
 83    common forms for starnames.
 84 !??????????????
 85    identifies all 15 character one-component entries beginning with !
 86    (called unique names because such names are generated by the
 87    unique_chars_ subroutine, described in the MPM Subroutines, and by
 88    the unique active function) in the user's working directory.
 89 ad?
 90    identifies all three-character one-component entries in the user's
 91    working directory that begin with ad.
 92 ad?*
 93    identifies all one-component entries in the user's working
 94    directory that begin with ad and have three or more characters.
 95 
 96 
 97 *
 98    identifies all one-component entries in the user's working
 99    directory.
100 *_data
101    identifies all one-component entries whose first component ends
102    with _data preceded by any number of other characters (including
103    none).
104 *.*
105    identifies all two-component entries in the user's working
106    directory.
107 *.pl1
108    identifies all two-component entries in the user's working
109    directory that have pl1 as their second component.
110 
111 
112 prog*.pl1
113    identifies all two-component entries whose first component begins
114    with the letters prog followed by any number of other characters
115    (including none), and whose second component is pl1.
116 sub_dir>my_prog.new.*
117    identifies all three-component entries in the directory sub_dir
118    (which is immediately inferior to the user's working directory)
119    that have my_prog.new as their first and second components.
120 interest_*_data.*.*
121    identifies all three-component entries whose first component
122    begins with interest_, ends with _data, and has any number of
123    characters (including none) in between.
124 
125 
126 *.**.my_seg
127    identifies all entries with two or more components of which the
128    last is my_seg.
129 **
130    identifies all entries in the user's working directory.
131 **.pl1
132    identifies all entries with pl1 as the last (and possibly only)
133    component.
134 my_prog.**
135    identifies all entries with my_prog as the first (and possibly
136    only) component.
137 
138 
139 sub_dir>prog?.**.pl1
140    identifies all entries in the directory sub_dir (which is
141    immediately inferior to the user's working directory) with two or
142    more components, of which the first component has exactly five
143    characters and begins with prog, and the last component is pl1.
144 *foo*
145    identifies any one-component entries in the user's working directory
146    that has the substring "foo" in their name.
147 **foo*
148    identifies any name in the user's working directory which has the
149    substring "foo" in its last component.
150 **foo**
151    identifies any name which contains the substring foo in any
152    component.
153 
154 
155 *.**.**.**
156    identifies all entries in the user's working directory.  Any name
157    which contains at most one single star component, at least one
158    doublestar component, and nothing else will match anything.