gxyrs(1)gxyrsgxyrs(1)NAMEgxyrs - is a program to batch process XYRS files.
SYNOPSISgxyrs file [OPTIONS]
DESCRIPTION
XYRS files are usually generated by PCB design programs, and are used
by board assemblers.
Format of XYRS files is discussed in FILES section.
Processing of these files is often needed by board assemblers or
designers to suit their process and tools flows.
gxyrs helps batch-processing these files. Rules and commands can be
defined to make batch-processing easy.
gxyrs consists on a perl library providing the core functions, and a
perl script providing some basic functionality.
It takes some arguments from the command line: input and output files,
some modifiers, and an action-file or an action-string.
The action-file or action-script contains some commands. For every line
of the input file, gxyrs executes those commands, which can modify the
contents of the line, and then writes the resulting line to the output
file.
Since gxyrs is written in perl, actions are also written in this lan‐
guage.
OPTIONS--help Display a usage message on standard output and exit success‐
fully. --verbose Display more information messages when pro‐
cessing files.
--process-comments
By default, gxyrs doesn't process lines starting with '*' and
'#' characters.
It just copies these lines to the output, without further pro‐
cessing.
With this option, it processes these lines as well.
--tabulate
Give each field in the output file a fixed length, enough to
contain the longest string. Using this option make
the output file easier to read by humans.
--caseinsensitive
Ignore case distinctions when comparing patterns.
--adjust FILE
File with the commands to process the input file.
--eval PATTERN
Interpret PATTERN as the commands to process the input file.
--output FILE
Save the output to the specified FILE.
If FILE string is "-" (without double quotes), then output is
redirected to standard output STDOUT.
--output-delimiter CHAR
Use the given CHAR as an output field delimiter.
PREDEFINED VARIABLESgxyrs defines automatically the following variables:
REF_COL
column number (starting at 0) where the component reference is.
FOOTPRINT_COL
column number (starting at 0) where the component footprint is.
X_COL column number (starting at 0) where the component's X location
coordinate is.
Y_COL column number (starting at 0) where the component's Y location
coordinate is.
ANGLE_COL
column number (starting at 0) where the component rotation angle
is.
LAYER_COL
column number (starting at 0) where the component's layer side
location is.
VALUE_COL
column number (starting at 0) where the component's value is.
Usually this is the component's part number.
LINE_NUMBER
this is the line number of the input file that is being cur‐
rently processed.
LINE array where each array element is a field or column of the input
file's line being processed.
BUILTIN COMMANDS
All the following commands accept a checklist parameter. A checklist
is a list of one or more check_items. A checkitem is a list of two
single elements:
column_number
is the data index number 'n' of the global variable LINE to be
checked. The first element of the data has the number 1.
pattern
is the regular expression to be matched.
The commands will only be executed on those lines that match all the
checkitems in the checklist.
del_line checklist;
Delete the line (global variable LINE) if checklist is matched.
Returns -1 if error, 0 if not match, 1 if match and changed.
rotate_comp angle_col, angle, checklist;
rotate the component the degrees given in angle parameter, if
checklist is matched.
The angle column number is angle_col.
Returns 1 if match and changed, 0 if not match, -1 if error.
subst_col_val col, value, checklist;
Replace a column value by the new value value, if checklist is
matched.
Returns 1 if match and changed, 0 if not match, -1 if error.
change_col_units units, column_numbers;
Change units of a given column number. More than one column num‐
ber can be specified.
Units is a string with the desired units. Only "mm" (milime‐
ters), "in" (inches) and "mil" (thousands of an inch) are sup‐
ported.
It is required that numbers to be converted are followed their
units (see supported units above). Otherwise, the number is not
changed.
add_number_to_col col_number, value, checklist;
Adds a number to the value in a given column number. Note: off‐
set and the value to be changed can be in different units.
Returns -1 if error, -2 if warning, and 1 if success.
translate_col_val col_number, string, substitution, checklist;
Translate a string in the column col_number if checklist is
matched.
Substitution is an expression with the new string. Old column
value can be used here.
Returns -1 if error, 0 if not match, 1 if match and changed.
Example:
translate 2, '^([0-9]+)n$','sprintf("%dnF",$1)', 3, 'C[0-9]+';
if the value in column 3 is C followed by a number, then
if the value in column 2 is a number followed by 'n', trans‐
late it to the same value followed by 'nF'.
If there is 'C10' in column 3 and '10n' in column 2,
change '10n' to '10nF'.
mul_col_val col_number, factor, checklist;
Multiply the number in the specified column number col_number by
the given factor, if checklist is matched.
The number in the specified column number may have units at the
end.
Returns -1 if error, 0 if not match, 1 if match and changed.
swap_columns col_number1, col_number2, checklist;
Swap columns col_number1 and col_number2 if checklist is
matched.
Returns -1 if error, 0 if not match, 1 if match and changed.
insert_column col_number, new_column_value;
Insert a new column in the given col_number position (0 if it's
going to be the first column), with the value new_column_value.
Returns -1 if error, 1 if the new column was inserted.
RETURN VALUE
The return value of gxyrs is an integer with the following possible
values:
1 if the command found a match and the execution was successful
0 if there was no match
-1 if there was an error
-2 if there was a warning
FILES
XYRS files
The format of these files is not standard, and depends on the
application used to generate it.
The data stored in these files is usually a header, and one line
per component of the board.
For each component, at least the following information is needed
by assemblers:
- Reference
- Coordinates (X and Y)
- Rotation angle
- Side where the component is located (top or bottom)
There can be more information, such as description, footprint,
but this depends on the design program an its configuration.
This information is organized in lines, one line per component,
and each line is divided in as much fields or columns as needed.
Field delimiters are used between columns, but field delimiters
are not standardized and they depend on the program used to gen‐
erate the XYRS file.
The program that generates the XYRS file usually write a header
(usually the first two or thre lines in the file) with a column
title.
gxyrs tries to guess the file format, and column numbers, based
on this header. Thus, the known column titles are the following:
- for reference designator: Designator, RefDesignator,
RefDes.
- for footprint: Footprint, TopCell, Description (only if
there is no other "TopCell" column title).
- for X coordinate: Mid X, X.
- for Y coordinate: Mid Y, Y.
- for rotation angle: Rotation, rotation, Rot.
- for location side: TB, Side, top/bottom.
- for value: Comment, PartNumber, Value.
Action files
An action file contains a list of commands, using perl language,
that can include any call to a built-in function or use any
variable defined by gxyrs.
Each action file should end with the following line (with a car‐
rier return at the end of the line):
1;
EXAMPLES
Run an action file:
Run the action file your_comands.txt with the XYRS file
your_xyrs_file.txt and write the output result to the file out‐
put_file.txt:
gxyrs your_xyrs_file.txt --adjust your_commands.txt --out‐
put output_file.txt
Run a command specified in the command line:
Run the commands your_commands wiith the XYRS file
your_xyrs_file.txt and write the output result to the file out‐
put_file.txt:
gxyrs your_xyrs_file.txt --eval "your_commands" --output
output_file.txt
Delete some lines matching a pattern.
Parse the XYRS file your_xyrs_file.txt, delete all lines having
a R followed by a number in column number 2, and write the out‐
put result to the file output_file.txt:
gxyrs your_xyrs_file.txt --eval "del 2, 'R[0-9]+';" --out‐
put output_file.txt
Delete some lines matching a pattern, using the column number guessed
by gxyrs.
Parse the XYRS file your_xyrs_file.txt, delete all lines having
a R followed by a number in reference designator column, and
write the output result to the file output_file.txt:
gxyrs your_xyrs_file.txt --eval "del \$REF_COL, 'R[0-9]+';"
--output output_file.txt
Rotate some lines matching a pattern.
Parse the XYRS file your_xyrs_file.txt, rotate by 90º all lines
having a R followed by a number in reference designator column,
and write the output result to the file output_file.txt. Use the
rotation and reference column number guessed by gxyrs:
gxyrs your_xyrs_file.txt --eval "rotate \$ANGLE_COL, 90,
\$REF_COL, 'R[0-9]+';" --output output_file.txt
Change all numbers to 'mm' units.
Parse the XYRS file your_xyrs_file.txt, convert all numbers in
column 3 and 5 to its equivalent in mm, and write the output
result to the file output_file.txt:
gxyrs your_xyrs_file.txt --eval "change_units 'mm', 3, 5;"
--output output_file.txt
Replace a value matching a pattern with another value.
Parse the XYRS file your_xyrs_file.txt, if the value in column 3
is "0.1u", then replace it with "100nF", and write the output
result to the file output_file.txt:
gxyrs your_xyrs_file.txt --eval "subst 3 , '100nF', 3,
'0.1u'" --output output_file.txt
Change the reference of a component with a value matching a pattern.
Parse the XYRS file your_xyrs_file.txt, if the value in value
column is "1n4148", then replace reference column with "D1", and
write the output result to the file output_file.txt:
gxyrs your_xyrs_file.txt --eval "subst \$REF_COL , 'D1',
\$VALUE_COL, '1n4148';" --output output_file.txt
Adds an offset to the X coordinate of a component with a reference hav‐
ing a R followed by a number.
Parse the XYRS file your_xyrs_file.txt, if the text in reference
column is R followed by a number, then adds 102.5mm to the value
in X coordinate column, and write the output result to the file
output_file.txt.
Value in column 3 can be in other units (for example: '640mil'):
gxyrs your_xyrs_file.txt --eval "offset \$X_COL, '102.5mm',
\$REF_COL, 'R[0-9]+' ;" --output output_file.txt
Multiply the value of the X coordinate of a component by a number, if
the component reference is having a R followed by a number.
Parse the XYRS file your_xyrs_file.txt, if the text in reference
column is R followed by a number, then multiply the value in X
coordinate column by 2.5, and write the output result to the
file output_file.txt.
Value in column 3 can be in other units (for example: '640mil'):
gxyrs your_xyrs_file.txt --eval "mul_col_val \$X_COL, 2.5,
\$REF_COL, 'R[0-9]+' ;" --output output_file.txt
Swap two columns.
Parse the XYRS file your_xyrs_file.txt, swap columns 3 and 4 if
the text in column number 4 is R followed by a number, and write
the output result to the file output_file.txt:
gxyrs your_xyrs_file.txt --eval "swap_columns 3, 4, 4,
'R[0-9]+' ;" --output output_file.txt
Insert a column.
Insert a column in the first position, displacing all existing
columns to the right. Column value is 'new_column_value':
gxyrs your_xyrs_file.txt --eval "insert_column 0, 'new_col‐
umn_value';" --output output_file.txt
SEE ALSOregex(7), GNU regular expression manual
Agosto 22, 2010 gxyrs(1)
