2
3
4
6 gxyrs - is a program to batch process XYRS files.
7
8
10 gxyrs file [OPTIONS]
11
12
14 XYRS files are usually generated by PCB design programs, and are used
15 by board assemblers.
16
17 Format of XYRS files is discussed in FILES section.
18
19 Processing of these files is often needed by board assemblers or
20 designers to suit their process and tools flows.
21
22 gxyrs helps batch-processing these files. Rules and commands can be
23 defined to make batch-processing easy.
24
25 gxyrs consists on a perl library providing the core functions, and a
26 perl script providing some basic functionality.
27
28 It takes some arguments from the command line: input and output files,
29 some modifiers, and an action-file or an action-string.
30
31 The action-file or action-script contains some commands. For every line
32 of the input file, gxyrs executes those commands, which can modify the
33 contents of the line, and then writes the resulting line to the output
34 file.
35
36 Since gxyrs is written in perl, actions are also written in this lan‐
37 guage.
38
39
41 --help Display a usage message on standard output and exit success‐
42 fully. --verbose Display more information messages when pro‐
43 cessing files.
44
45 --process-comments
46 By default, gxyrs doesn't process lines starting with '*' and
47 '#' characters.
48
49 It just copies these lines to the output, without further pro‐
50 cessing.
51
52 With this option, it processes these lines as well.
53
54 --tabulate
55 Give each field in the output file a fixed length, enough to
56 contain the longest string. Using this option make
57 the output file easier to read by humans.
58
59 --caseinsensitive
60 Ignore case distinctions when comparing patterns.
61
62 --adjust FILE
63 File with the commands to process the input file.
64
65 --eval PATTERN
66 Interpret PATTERN as the commands to process the input file.
67
68 --output FILE
69 Save the output to the specified FILE.
70
71 If FILE string is "-" (without double quotes), then output is
72 redirected to standard output STDOUT.
73
74 --output-delimiter CHAR
75 Use the given CHAR as an output field delimiter.
76
77
79 gxyrs defines automatically the following variables:
80
81 REF_COL
82 column number (starting at 0) where the component reference is.
83
84 FOOTPRINT_COL
85 column number (starting at 0) where the component footprint is.
86
87 X_COL column number (starting at 0) where the component's X location
88 coordinate is.
89
90 Y_COL column number (starting at 0) where the component's Y location
91 coordinate is.
92
93 ANGLE_COL
94 column number (starting at 0) where the component rotation angle
95 is.
96
97 LAYER_COL
98 column number (starting at 0) where the component's layer side
99 location is.
100
101 VALUE_COL
102 column number (starting at 0) where the component's value is.
103 Usually this is the component's part number.
104
105 LINE_NUMBER
106 this is the line number of the input file that is being cur‐
107 rently processed.
108
109 LINE array where each array element is a field or column of the input
110 file's line being processed.
111
113 All the following commands accept a checklist parameter. A checklist
114 is a list of one or more check_items. A checkitem is a list of two
115 single elements:
116
117 column_number
118 is the data index number 'n' of the global variable LINE to be
119 checked. The first element of the data has the number 1.
120
121 pattern
122 is the regular expression to be matched.
123
124 The commands will only be executed on those lines that match all the
125 checkitems in the checklist.
126
127
128 del_line checklist;
129 Delete the line (global variable LINE) if checklist is matched.
130
131 Returns -1 if error, 0 if not match, 1 if match and changed.
132
133 rotate_comp angle_col, angle, checklist;
134 rotate the component the degrees given in angle parameter, if
135 checklist is matched.
136
137 The angle column number is angle_col.
138
139 Returns 1 if match and changed, 0 if not match, -1 if error.
140
141 subst_col_val col, value, checklist;
142 Replace a column value by the new value value, if checklist is
143 matched.
144
145 Returns 1 if match and changed, 0 if not match, -1 if error.
146
147
148 change_col_units units, column_numbers;
149 Change units of a given column number. More than one column num‐
150 ber can be specified.
151
152 Units is a string with the desired units. Only "mm" (milime‐
153 ters), "in" (inches) and "mil" (thousands of an inch) are sup‐
154 ported.
155
156 It is required that numbers to be converted are followed their
157 units (see supported units above). Otherwise, the number is not
158 changed.
159
160
161 add_number_to_col col_number, value, checklist;
162 Adds a number to the value in a given column number. Note: off‐
163 set and the value to be changed can be in different units.
164
165 Returns -1 if error, -2 if warning, and 1 if success.
166
167
168 translate_col_val col_number, string, substitution, checklist;
169 Translate a string in the column col_number if checklist is
170 matched.
171
172 Substitution is an expression with the new string. Old column
173 value can be used here.
174
175 Returns -1 if error, 0 if not match, 1 if match and changed.
176
177 Example:
178 translate 2, '^([0-9]+)n$','sprintf("%dnF",$1)', 3, 'C[0-9]+';
179 if the value in column 3 is C followed by a number, then
180 if the value in column 2 is a number followed by 'n', trans‐
181 late it to the same value followed by 'nF'.
182 If there is 'C10' in column 3 and '10n' in column 2,
183 change '10n' to '10nF'.
184
185
186 mul_col_val col_number, factor, checklist;
187 Multiply the number in the specified column number col_number by
188 the given factor, if checklist is matched.
189
190 The number in the specified column number may have units at the
191 end.
192
193 Returns -1 if error, 0 if not match, 1 if match and changed.
194
195
196 swap_columns col_number1, col_number2, checklist;
197 Swap columns col_number1 and col_number2 if checklist is
198 matched.
199
200 Returns -1 if error, 0 if not match, 1 if match and changed.
201
202
203 insert_column col_number, new_column_value;
204 Insert a new column in the given col_number position (0 if it's
205 going to be the first column), with the value new_column_value.
206
207 Returns -1 if error, 1 if the new column was inserted.
208
209
211 The return value of gxyrs is an integer with the following possible
212 values:
213
214 1 if the command found a match and the execution was successful
215
216 0 if there was no match
217
218 -1 if there was an error
219
220 -2 if there was a warning
221
223 XYRS files
224 The format of these files is not standard, and depends on the
225 application used to generate it.
226
227 The data stored in these files is usually a header, and one line
228 per component of the board.
229
230 For each component, at least the following information is needed
231 by assemblers:
232
233 - Reference
234
235 - Coordinates (X and Y)
236
237 - Rotation angle
238
239 - Side where the component is located (top or bottom)
240
241 There can be more information, such as description, footprint,
242 but this depends on the design program an its configuration.
243
244 This information is organized in lines, one line per component,
245 and each line is divided in as much fields or columns as needed.
246 Field delimiters are used between columns, but field delimiters
247 are not standardized and they depend on the program used to gen‐
248 erate the XYRS file.
249
250 The program that generates the XYRS file usually write a header
251 (usually the first two or thre lines in the file) with a column
252 title.
253
254 gxyrs tries to guess the file format, and column numbers, based
255 on this header. Thus, the known column titles are the following:
256
257 - for reference designator: Designator, RefDesignator,
258 RefDes.
259
260 - for footprint: Footprint, TopCell, Description (only if
261 there is no other "TopCell" column title).
262
263 - for X coordinate: Mid X, X.
264
265 - for Y coordinate: Mid Y, Y.
266
267 - for rotation angle: Rotation, rotation, Rot.
268
269 - for location side: TB, Side, top/bottom.
270
271 - for value: Comment, PartNumber, Value.
272
273
274 Action files
275 An action file contains a list of commands, using perl language,
276 that can include any call to a built-in function or use any
277 variable defined by gxyrs.
278
279 Each action file should end with the following line (with a car‐
280 rier return at the end of the line):
281
282 1;
283
284
286 Run an action file:
287 Run the action file your_comands.txt with the XYRS file
288 your_xyrs_file.txt and write the output result to the file out‐
289 put_file.txt:
290
291 gxyrs your_xyrs_file.txt --adjust your_commands.txt --out‐
292 put output_file.txt
293
294 Run a command specified in the command line:
295 Run the commands your_commands wiith the XYRS file
296 your_xyrs_file.txt and write the output result to the file out‐
297 put_file.txt:
298
299 gxyrs your_xyrs_file.txt --eval "your_commands" --output
300 output_file.txt
301
302 Delete some lines matching a pattern.
303 Parse the XYRS file your_xyrs_file.txt, delete all lines having
304 a R followed by a number in column number 2, and write the out‐
305 put result to the file output_file.txt:
306
307 gxyrs your_xyrs_file.txt --eval "del 2, 'R[0-9]+';" --out‐
308 put output_file.txt
309
310 Delete some lines matching a pattern, using the column number guessed
311 by gxyrs.
312 Parse the XYRS file your_xyrs_file.txt, delete all lines having
313 a R followed by a number in reference designator column, and
314 write the output result to the file output_file.txt:
315
316 gxyrs your_xyrs_file.txt --eval "del \$REF_COL, 'R[0-9]+';"
317 --output output_file.txt
318
319 Rotate some lines matching a pattern.
320 Parse the XYRS file your_xyrs_file.txt, rotate by 90º all lines
321 having a R followed by a number in reference designator column,
322 and write the output result to the file output_file.txt. Use the
323 rotation and reference column number guessed by gxyrs:
324
325 gxyrs your_xyrs_file.txt --eval "rotate \$ANGLE_COL, 90,
326 \$REF_COL, 'R[0-9]+';" --output output_file.txt
327
328 Change all numbers to 'mm' units.
329 Parse the XYRS file your_xyrs_file.txt, convert all numbers in
330 column 3 and 5 to its equivalent in mm, and write the output
331 result to the file output_file.txt:
332
333 gxyrs your_xyrs_file.txt --eval "change_units 'mm', 3, 5;"
334 --output output_file.txt
335
336 Replace a value matching a pattern with another value.
337 Parse the XYRS file your_xyrs_file.txt, if the value in column 3
338 is "0.1u", then replace it with "100nF", and write the output
339 result to the file output_file.txt:
340
341 gxyrs your_xyrs_file.txt --eval "subst 3 , '100nF', 3,
342 '0.1u'" --output output_file.txt
343
344 Change the reference of a component with a value matching a pattern.
345 Parse the XYRS file your_xyrs_file.txt, if the value in value
346 column is "1n4148", then replace reference column with "D1", and
347 write the output result to the file output_file.txt:
348
349 gxyrs your_xyrs_file.txt --eval "subst \$REF_COL , 'D1',
350 \$VALUE_COL, '1n4148';" --output output_file.txt
351
352 Adds an offset to the X coordinate of a component with a reference hav‐
353 ing a R followed by a number.
354 Parse the XYRS file your_xyrs_file.txt, if the text in reference
355 column is R followed by a number, then adds 102.5mm to the value
356 in X coordinate column, and write the output result to the file
357 output_file.txt.
358
359 Value in column 3 can be in other units (for example: '640mil'):
360
361 gxyrs your_xyrs_file.txt --eval "offset \$X_COL, '102.5mm',
362 \$REF_COL, 'R[0-9]+' ;" --output output_file.txt
363
364 Multiply the value of the X coordinate of a component by a number, if
365 the component reference is having a R followed by a number.
366 Parse the XYRS file your_xyrs_file.txt, if the text in reference
367 column is R followed by a number, then multiply the value in X
368 coordinate column by 2.5, and write the output result to the
369 file output_file.txt.
370
371 Value in column 3 can be in other units (for example: '640mil'):
372
373 gxyrs your_xyrs_file.txt --eval "mul_col_val \$X_COL, 2.5,
374 \$REF_COL, 'R[0-9]+' ;" --output output_file.txt
375
376 Swap two columns.
377 Parse the XYRS file your_xyrs_file.txt, swap columns 3 and 4 if
378 the text in column number 4 is R followed by a number, and write
379 the output result to the file output_file.txt:
380
381 gxyrs your_xyrs_file.txt --eval "swap_columns 3, 4, 4,
382 'R[0-9]+' ;" --output output_file.txt
383
384 Insert a column.
385 Insert a column in the first position, displacing all existing
386 columns to the right. Column value is 'new_column_value':
387
388 gxyrs your_xyrs_file.txt --eval "insert_column 0, 'new_col‐
389 umn_value';" --output output_file.txt
390
392 regex(7), GNU regular expression manual
393
394 Agosto 22, 2010 gxyrs(1)