1 07/30/86 Equal Convention general information
2
3 Some commands that accept more than one pathname as their arguments
4 allow the entrynames of pathnames following the first, or source
5 pathname, to be equalnames. This is to be generally expected if the
6 command allows the source entryname to be a starname.
7
8
9 An equalname is a special entryname which is used with the source
10 entryname to construct the entryname actually used by the command. The
11 equalname contains special characters which are replaced by characters
12 from the source entryname. Use of the equal convention can reduce the
13 typing required for the subsequent pathnames, and is essential when a
14 starname is used, because the entrynames can't be determined from the
15 command line alone, but depend on the entrynames which match the
16 starname.
17
18
19 Constructing Equalnames: An equalname is constructed according to
20 the following rules.
21
22 1. An equalname is an entryname. Therefore, it is composed of a
23 string of 32 or fewer ASCII printing graphics or spaces, none of
24 which can be the greater-than > character. An equalname cannot
25 contain control characters such as backspace, tab, or newline.
26
27 2. An equalname is composed of one or more nonnull components. This
28 means that an equalname cannot begin or end with a period . and
29 cannot contain two or more consecutive periods.
30
31 3. Each percent sign % character appearing in an equalname component
32 is treated as a special character.
33
34
35 4. Each equal sign = appearing in an equalname component is treated
36 as a special character.
37
38 5. An equalname component consisting only of a double == or triple
39 equal sign === is treated as a special component.
40
41 6. An equalname containing four or more consecutive equal signs is
42 illegal.
43
44
45 Interpreting Equalnames: An equalname maps characters from the
46 entrynames that match the star name first entryname into the second
47 entryname of a pair according to the following rules.
48
49 1. Each percent sign % in an equalname component represents the
50 single character in the corresponding component and character
51 position of the corresponding entryname. An error occurs if the
52 corresponding character does not exist.
53
54
55 2. An equal sign = in an equalname component represents the
56 corresponding component of a corresponding entryname. An error
57 occurs if the corresponding component does not exist. An error
58 also occurs if an equal sign appears in a component that also
59 contains a percent character. Only one equal sign can appear in
60 each equalname component, except for a double or triple equal sign
61 component, as noted in the next two rules.
62
63
64 3. The double equal sign == component of an equalname represents all
65 components of an entryname that have no other corresponding
66 components in the equalname. Often, the double equal sign
67 component represents more than one component of the corresponding
68 entryname. If so, the number of components represented by the
69 entire equalname is the same as the number of components in the
70 entryname. When the equalname contains the same number of
71 components or more components than the entryname, a double equal
72 sign is meaningless and, therefore, ignored. See the examples
73 below. Only one double equal sign component can appear in an
74 equalname.
75
76
77 4. The triple equal sign === component of an equalname represents
78 the entire corresponding entryname. The triple equal sign
79 component is used to add components to a name see below. Only
80 one triple equal sign component may appear in an equalname and no
81 other component of that equalname may contain percent signs or
82 equal signs.
83
84
85 Notes: The rules above impose no restrictions on the form of the
86 entrynames identified by the equalname. For example, the entrynames
87 can contain null components. However, when the entrynames are present
88 in directories, they have usually been subject to validity tests for
89 entrynames, and thus are usually valid entrynames. For more
90 information about the star convention, see starname.gi.info. For more
91 information about entrynames, see entryname.gi.info.
92
93
94 The add_name and rename commands normally accept starnames and
95 equalnames, which they require to be valid entrynames. This helps to
96 protect files from being given invalid entrynames. However, if files
97 have invalid entrynames containing null components, control characters,
98 or characters reserved by the star, equal, archive or virtual pointer
99 or entry conventions, the -name control argument of the delete,
100 delete_name and rename commands can be used to remove the files or
101 their invalid names.
102
103
104 Examples of equalnames: The following examples illustrate how
105 equalnames might be used in rename and add_name commands.
106
107 First, the single equal sign. The command
108 rename random.data_base ordered.=
109 is equivalent to
110 rename random.data_base ordered.data_base
111 and the command
112 add_name world.data =.statistics =.census
113 is equivalent to
114 add_name world.data world.statistics world.census
115
116
117 The command
118 rename random.data.base =.=
119 is equivalent to
120 rename random.data.base random.data
121
122 The star convention is used in the command
123 rename *.data_base =.data
124 to rename all two-component entrynames with data_base as their second
125 component so these entrynames have, instead, a second component of
126 data.
127
128
129 The command
130 rename program.pl1 old_=.=
131 is equivalent to
132 rename program.pl1 old_program.pl1
133 and the command
134 add_name data first_=_set
135 is equivalent to
136 add_name data first_data_set
137
138
139 An error would be produced by the command
140 rename alpha beta.=.gamma
141 because the first entryname of the pair does not contain a component
142 corresponding to the equal sign in the second name.
143
144
145 Next, the double equal sign. In the two examples that follow, the
146 first entryname has components that correspond to the double equal sign
147 in the equalname of each pair. As a result, the number of components
148 represented by the equalname is the same as the number of components
149 in the first entryname.
150
151 The command
152 rename one.two.three 1.==
153 is equivalent to
154 rename one.two.three 1.two.three
155 and the command
156 add_name one.two.three.four.five 1.==.5
157 is equivalent to
158 add_name one.two.three.four.five 1.two.three.four.5
159
160
161 In the example that follows, the equalname contains the same number of
162 components as the entryname. Therefore, the double equal sign does not
163 correspond to any components of the entryname and is ignored. The
164 commands
165 rename alpha.beta ==.x.y
166 rename alpha.beta x.y.==
167 rename alpha.beta x.==.y
168 are all equivalent to
169 rename alpha.beta x.y
170
171
172 In the next example, since the equalname contains more components than
173 the entryname, the double equal sign corresponds to no components of
174 the entryname and is ignored. The command
175 add_name able ==.baker.charlie
176 is equivalent to
177 add_name able baker.charlie
178
179
180 The command
181 add_name **.ec ==.absin
182 uses the star convention to add a name to each entry with an entryname
183 whose last or only component is ec. The last component of this new
184 name is absin instead of ec, and the first components if any are the
185 same as those of the original name ending in ec e.g. the name
186 alpha.absin would be added to the entry named alpha.ec.
187
188 The command
189 rename foo.test.pl1 ==.old
190 is equivalent to
191 rename foo.test.pl1 foo.test.old
192
193
194 With the triple equal sign, this command becomes
195 rename foo.test.pl1 ===.old
196 and is equivalent to
197 rename foo.test.pl1 foo.test.pl1.old
198 because the triple equal sign represents the entire corresponding
199 entryname. For the same reason, the command
200 add_name alpha.** ===.1
201 adds the name "alpha.1" to "alpha", "alpha.pl1.1" to "alpha.pl1", etc.
202
203
204 Note that a triple sign component in an entryname implies that the new
205 name will have more components than the old name. This is different
206 from a double equal sign component as can be seen if the command
207 add_name alpha.** ==.1
208 is used instead. The latter command has a different effect. For
209 example, it attempts to add the name "alpha.1" to both "alpha.pl1" and
210 "alpha.list", leading to a name duplication error.
211
212
213 The command
214 rename ???*.data %%%.=
215 renames all two-component entrynames that have a last component of data
216 and a first component containing three or more characters so that the
217 first component is truncated to the first three characters and the
218 second component is data e.g. alpha.data would be renamed alp.data.
219 The command
220 rename *.data %%%.=
221 results in an error if the first component of any name matching *.data
222 has fewer than three characters.
223
224
225 Archive-Component Pathnames and Equalnames:
226 Some commands that accept multiple pathnames as their arguments allow
227 any of the pathnames to be archive component pathnames. Pathnames
228 after the first may contain equalnames. This is particularly to be
229 expected if the first pathname is permitted to contain starnames.
230
231
232 In an archive pathname, there are two entrynames, with the archive name
233 appearing before the double colon "::" and the component name after
234 the double colon. The star and equal conventions handle the two names
235 separately. The rules for constructing and interpreting equalnames in
236 the two portions of an archive component pathname are identical to
237 those for ordinary equalnames described earlier.
238
239
240 Either or both of the archive and component names may be equalnames in
241 pathnames subsequent to the first pathname. This usage makes it easy
242 for the user to request an operation on sets of segments or archive
243 components, where segment or archive entrynames and component names are
244 derived using the equal convention.
245
246
247 The following rules are used to determine whether to apply a given
248 equalname to the archive or component name specified in the first
249 source pathname when constructing subsequent target pathnames.
250
251 1. If neither the source nor target pathnames are archive component
252 pathnames, an equalname in the target pathname is applied to the
253 source pathname just as described in the previous section on
254 equalnames.
255
256 2. If the source pathname is not an archive component pathname, but
257 the target pathname is an archive component pathname, an equalname
258 in the target component name is applied to the source entryname; an
259 equalname is not permitted in the target archive name in this case.
260
261
262 3. If the source pathname is an archive component pathname, but the
263 target pathname is not an archive component pathname, an equalname
264 in the target entryname is applied to the source component name,
265 not the source archive entryname.
266
267 4. If both the source and target pathnames are archive component
268 pathnames, an equalname in the target archive entryname is applied
269 to the source archive entryname, and an equalname in the target
270 component name is applied to the source component name. When
271 applying the equalname to the source archive entryname, the
272 ".archive" suffix is first removed from the archive entryname.
273
274
275 Examples of archive component equalnames: The following examples
276 illustrate the use of archive component pathnames and the compare_ascii
277 command.
278
279 The command
280 compare_ascii test.pl1 source::old.===
281 is equivalent to
282 compare_ascii test.pl1 source::old.test.pl1
283 and compares the segment "test.pl1" with the component "old.test.pl1"
284 in the archive "source.archive".
285
286
287 The command
288 compare_ascii source.s::print_data.pl1 ===.ud::===
289 is equivalent to
290 compare_ascii source.s::print_data.pl1 source.s.ud::print_data.pl1
291 and compares the components named "print_data.pl1" in the two archives,
292 "source.s.archive" and "source.s.ud.archive".
293
294 The command
295 compare_ascii my_prog.pl1 ===::his_prog.==
296 is invalid because there is no archive name in the source pathname
297 corresponding to the "===" in the target pathname.
298
299
300 Finally, the command
301 compare_ascii tools::my_prog.pl1 his_prog.==
302 is equivalent to
303 compare_ascii tools::my_prog.pl1 his_prog.pl1