gxyrs(1) - f29

gxyrs(1) gxyrs gxyrs(1)

2
3
4

NAME

6       gxyrs - is a program to batch process XYRS files.
7
8

SYNOPSIS

10       gxyrs file [OPTIONS]
11
12

DESCRIPTION

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

OPTIONS

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

PREDEFINED VARIABLES

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

BUILTIN COMMANDS

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

RETURN VALUE

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

FILES

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

EXAMPLES

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