Provided by: geda-utils_1.8.2-5_amd64 bug

gxyrs(1)                                      gxyrs                                      gxyrs(1)

NAME

       gxyrs - is a program to batch process XYRS files.

SYNOPSIS

       gxyrs 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 language.

OPTIONS

       --help Display   a   usage   message  on standard output and exit successfully.  --verbose
              Display more information messages when processing files.

       --process-comments
              By default, gxyrs doesn't process lines starting with '*' and '#' characters.

              It just copies these lines to the output, without further processing.

              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 VARIABLES

       gxyrs 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 currently 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 number can be
              specified.

              Units is a string with the desired units. Only "mm" (milimeters), "in" (inches) and
              "mil" (thousands of an inch) are supported.

              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: offset 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', translate 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 generate 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 carrier 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 output_file.txt:

                   gxyrs  your_xyrs_file.txt --adjust your_commands.txt --output 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 output_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 output result to the file output_file.txt:

                   gxyrs your_xyrs_file.txt --eval "del 2, 'R[0-9]+';" --output 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 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 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_column_value';"
              --output output_file.txt

SEE ALSO

       regex(7), GNU regular expression manual

                                         Agosto 22, 2010                                 gxyrs(1)