utils/docs/gxyrs.1

   1 .\"Created with GNOME Manpages Editor Wizard
   2 .\"http://sourceforge.net/projects/gmanedit2
   3 .TH \fBgxyrs\fP 1 "Agosto 22, 2010" "" "\fBgxyrs\fP"
   4
   5 .SH NAME
   6 \fBgxyrs\fP \- is a program to batch process XYRS files.
   7
   8 .SH SYNOPSIS
   9 .B \fBgxyrs\fP
  10 .RI \fBfile\fP
  11 .RI [OPTIONS]
  12 .br
  13
  14 .SH DESCRIPTION
  15 XYRS files are usually generated by PCB design programs, and are used by board assemblers.
  16 .PP\r
  17 Format of XYRS files is discussed in FILES section.
  18 .PP
  19 Processing of these files is often needed by board assemblers or designers to suit their \r
  20 process and tools flows.\r
  21 .PP
  22 \fBgxyrs\fP helps batch-processing these files. Rules and commands can be defined to make \r
  23 batch-processing easy.\r
  24 .PP\r
  25 \fBgxyrs\fP consists on a perl library providing the core functions, and a perl script providing some basic functionality.\r
  26 .PP
  27 It takes some arguments from the command line: input and output files, some modifiers, and an action-file or an action-string.\r
  28 .PP
  29 The action-file or action-script contains some commands. For every line of the input file, \fBgxyrs\fP executes those commands, which can modify the contents of the line, \r
  30 and then writes the resulting line to the output file.\r
  31 .PP\r
  32 Since \fBgxyrs\fP is written in perl, actions are also written in this language.\r
  33
  34 .SH OPTIONS
  35 .B
  36 .IP       --help
  37 Display  a  usage  message  on standard output and exit successfully.\r
  38 .BI      \--verbose
  39 Display more information messages when processing files.
  40 .TP\r
  41 .BI      \--process-comments
  42 By default, gxyrs doesn't process lines starting with '*' and '#' characters.
  43
  44 It just copies these lines to the output, without further processing.\r
  45
  46 With this option, it processes these lines as well.\r
  47 .TP\r
  48 .BI      \--tabulate
  49 Give each field in the output file a fixed length, enough to contain the longest string.\r
  50                 Using this option make the output file easier to read by humans.\r
  51 .TP\r
  52 .BI      \--caseinsensitive
  53 Ignore case distinctions when comparing patterns.\r
  54 .TP\r
  55 .BI      \--adjust "\| FILE\ "
  56 File with the commands to process the input file.\r
  57 .TP\r
  58 .BI      \--eval "\| PATTERN\ "
  59 Interpret PATTERN as the commands to process the input file.\r
  60 .TP\r
  61 .BI      \--output "\| FILE\ "
  62 Save the output to the specified FILE.
  63
  64 If FILE string is "-" (without double quotes), then output is redirected to standard output STDOUT.\r
  65 .TP\r
  66 .BI      \--output-delimiter "\| CHAR\ "
  67 Use the given CHAR as an output field delimiter.\r
  68
  69 .SH "PREDEFINED VARIABLES"
  70 .PP
  71 gxyrs defines automatically the following variables:
  72 .PP
  73 .TP
  74 .B REF_COL
  75 column number (starting at 0) where the component reference is.\r
  76 .TP
  77 .B FOOTPRINT_COL
  78 column number (starting at 0) where the component footprint is.\r
  79 .TP
  80 .B X_COL
  81 column number (starting at 0) where the component's X location coordinate is.\r
  82 .TP
  83 .B Y_COL
  84 column number (starting at 0) where the component's Y location coordinate is.\r
  85 .TP
  86 .B ANGLE_COL
  87 column number (starting at 0) where the component rotation angle is.\r
  88 .TP
  89 .B LAYER_COL
  90 column number (starting at 0) where the component's layer side location is.\r
  91 .TP
  92 .B VALUE_COL
  93 column number (starting at 0) where the component's value is. Usually this is the component's part number.\r
  94 .TP
  95 .B LINE_NUMBER
  96 this is the line number of the input file that is being currently processed.\r
  97 .TP
  98 .B LINE
  99 array where each array element is a field or column of the input file's line being processed.\r
 100 .SH "BUILTIN COMMANDS"
 101 All the following commands accept a \fIchecklist\fP parameter.
 102 A \fIchecklist\fP is a list of one or more \fIcheck_items\fP.
 103 A \fIcheckitem\fP is a list of two single elements:
 104 .TP
 105 .B column_number
 106 is the data index number 'n' of the global variable \fBLINE\fP to be checked.
 107 The first element of the data has the number 1.
 108 .TP
 109 .B pattern
 110 is the regular expression to be matched.
 111 .PP
 112 The commands will only be executed on those lines that match all the \fIcheckitems\fP in the \fIchecklist\fP.
 113
 114 .TP
 115 .B \fBdel_line\fP \fIchecklist\fP;
 116 Delete the line (global variable \fBLINE\fP) if \fIchecklist\fP is matched.\r
 117 \r
 118 Returns -1 if error, 0 if not match, 1 if match and changed.\r
 119 .TP\r
 120 .B rotate_comp \fIangle_col\fP, \fIangle\fP, \fIchecklist\fP;
 121 rotate the component the degrees given in \fIangle\fP parameter, if \fIchecklist\fP is matched.
 122
 123 The angle column number is \fIangle_col\fP.\r
 124 \r
 125 Returns 1 if match and changed, 0 if not match, -1 if error.\r
 126 .TP\r
 127 .B subst_col_val \fIcol\fP, \fIvalue\fP, \fIchecklist\fP;\r
 128 Replace a column value by the new value \fIvalue\fP, if \fIchecklist\fP is matched.\r
 129 \r
 130 Returns 1 if match and changed, 0 if not match, -1 if error.\r
 131 \r
 132 .TP
 133 .B change_col_units \fIunits\fP, \fIcolumn_numbers\fP;
 134 Change units of a given column number. More than one column number can be specified.
 135
 136 \fIUnits\fP is a string with the desired units. Only "mm" (milimeters), "in" (inches) and "mil" (thousands of an inch) are supported.
 137
 138 It is required that numbers to be converted are followed their units (see supported units above). Otherwise, the number is not changed.
 139
 140 .TP
 141 .B add_number_to_col \fIcol_number\fP, \fIvalue\fP, \fIchecklist\fP;
 142 Adds a number to the value in a given column number.
 143 Note: offset and the value to be changed can be in different units.
 144
 145 Returns -1 if error, -2 if warning, and 1 if success.
 146
 147 .TP
 148 .B translate_col_val \fIcol_number\fP, \fIstring\fP, \fIsubstitution\fP, \fIchecklist\fP;
 149 Translate a \fIstring\fP in the column \fIcol_number\fP if \fIchecklist\fP is matched.
 150
 151 \fISubstitution\fP is an expression with the new string. Old column value can be used here.
 152
 153 Returns -1 if error, 0 if not match, 1 if match and changed.
 154
 155 Example:
 156   translate 2, '^([0-9]+)n$','sprintf("%dnF",$1)', 3, 'C[0-9]+';
 157     if the value in column 3 is C followed by a number, then
 158     if the value in column 2 is a number followed by 'n', translate it to the same value followed by 'nF'.
 159     If there is 'C10' in column 3 and '10n' in column 2,
 160     change '10n' to '10nF'.
 161
 162 .TP
 163 .B mul_col_val \fIcol_number\fP, \fIfactor\fP, \fIchecklist\fP;
 164 Multiply the number in the specified column number \fIcol_number\fP by the given \fIfactor\fP, if \fIchecklist\fP is matched.
 165
 166 The number in the specified column number may have units at the end.
 167
 168 Returns -1 if error, 0 if not match, 1 if match and changed.
 169
 170 .TP
 171 .B swap_columns \fIcol_number1\fP, \fIcol_number2\fP, \fIchecklist\fP;
 172 Swap columns \fIcol_number1\fP and \fIcol_number2\fP if \fIchecklist\fP is matched.
 173
 174 Returns -1 if error, 0 if not match, 1 if match and changed.
 175
 176 .TP
 177 .B insert_column \fIcol_number\fP, \fInew_column_value\fP;
 178 Insert a new column in the given \fIcol_number\fP position (0 if it's going to be the first column), with the value \fInew_column_value\fP.
 179
 180 Returns -1 if error, 1 if the new column was inserted.
 181
 182 .SH "RETURN VALUE"
 183 The return value of \fBgxyrs\fP is an integer with the following possible values:
 184 .TP
 185         1 if the command found a match and the execution was succesful
 186 .PP
 187         0 if there was no match
 188 .PP
 189         -1 if there was an error
 190 .PP
 191         -2 if there was a warning
 192 .PP
 193
 194 .SH FILES
 195 .TP
 196 .B       XYRS files
 197 The format of these files is not standard, and depends on the application used to generate it.
 198
 199 The data stored in these files is usually a header, and one line per component of the board.\r
 200
 201 For each component, at least the following information is needed by assemblers:\r
 202
 203         - Reference\r
 204
 205         - Coordinates (X and Y)\r
 206
 207         - Rotation angle\r
 208
 209         - Side where the component is located (top or bottom)\r
 210
 211 There can be more information, such as description, footprint, but this depends on the \r
 212 design program an its configuration.\r
 213 \r
 214 This information is organized in lines, one line per component, and each line is divided in as much fields or columns as needed.\r
 215 Field delimiters are used between columns, but field delimiters are not standardized and they depend on the program used to generate the XYRS file.\r
 216
 217 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.
 218
 219 \fBgxyrs\fP tries to guess the file format, and column numbers, based on this header. Thus, the known column titles are the following:
 220
 221         - for reference designator: \fIDesignator\fP, \fIRefDesignator\fP, \fIRefDes\fP.
 222
 223         - for footprint: \fIFootprint\fP, \fITopCell\fP, \fIDescription\fP (only if there is no other "TopCell" column title).
 224
 225         - for X coordinate: \fIMid X\fP, \fIX\fP.
 226
 227         - for Y coordinate: \fIMid Y\fP, \fIY\fP.
 228
 229         - for rotation angle: \fIRotation\fP, \fIrotation\fP, \fIRot\fP.
 230
 231         - for location side: \fITB\fP, \fISide\fP, \fItop/bottom\fP.
 232
 233         - for value: \fIComment\fP, \fIPartNumber\fP, \fIValue\fP.
 234
 235 .TP
 236 .B       Action files
 237 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 \fIgxyrs\fP.
 238
 239 Each action file should end with the following line (with a carrier return at the end of the line):
 240
 241         1;
 242
 243 .SH EXAMPLES
 244 .TP
 245 .B Run an action file:
 246 Run the action file \fIyour_comands.txt\fP with the XYRS file \fIyour_xyrs_file.txt\fP and write the output result to the file \fIoutput_file.txt\fP:
 247
 248         gxyrs  your_xyrs_file.txt --adjust your_commands.txt --output output_file.txt
 249 .PP
 250 .TP
 251 .B Run a command specified in the command line:
 252 Run the commands \fIyour_commands\fP wiith the XYRS file \fIyour_xyrs_file.txt\fP and write the output result to the file \fIoutput_file.txt\fP:
 253
 254         gxyrs  your_xyrs_file.txt --eval "your_commands" --output output_file.txt
 255 .PP
 256
 257 .TP
 258 .B Delete some lines matching a pattern.
 259 Parse the XYRS file \fIyour_xyrs_file.txt\fP, delete all lines having a R followed by a number in column number 2, and write the output result to the file \fIoutput_file.txt\fP:
 260
 261         gxyrs your_xyrs_file.txt --eval "del 2, 'R[0-9]+';" --output output_file.txt\r
 262 .PP\r
 263 .TP
 264 .B Delete some lines matching a pattern, using the column number guessed by \fBgxyrs\fP.
 265 Parse the XYRS file \fIyour_xyrs_file.txt\fP, delete all lines having a R followed by a number in reference designator column, and write the output result to the file \fIoutput_file.txt\fP:
 266
 267         gxyrs your_xyrs_file.txt --eval "del \\$REF_COL, 'R[0-9]+';" --output output_file.txt\r
 268 .PP\r
 269 .TP
 270 .B Rotate some lines matching a pattern.
 271 Parse the XYRS file \fIyour_xyrs_file.txt\fP, rotate by 90º all lines having a R followed by a number in reference designator column, and write the output result to the file \fIoutput_file.txt\fP. Use the rotation  and reference column number guessed by \fIgxyrs\fP:
 272
 273         gxyrs your_xyrs_file.txt --eval "rotate \\$ANGLE_COL, 90, \\$REF_COL, 'R[0-9]+';" --output output_file.txt\r
 274 .PP\r
 275 .TP
 276 .B Change all numbers to 'mm' units.\r
 277 Parse the XYRS file \fIyour_xyrs_file.txt\fP, convert all numbers in column 3 and 5 to its equivalent in mm, and write the output result to the file \fIoutput_file.txt\fP:
 278
 279         gxyrs your_xyrs_file.txt --eval "change_units 'mm', 3, 5;" --output output_file.txt
 280 .PP
 281 .TP
 282 .B Replace a value matching a pattern with another value.\r
 283 Parse the XYRS file \fIyour_xyrs_file.txt\fP, if the value in column 3 is "0.1u", then replace it with "100nF", and write the output result to the file \fIoutput_file.txt\fP:
 284
 285         gxyrs your_xyrs_file.txt --eval "subst 3 , '100nF', 3, '0.1u'" --output output_file.txt
 286 .PP
 287 .TP
 288 .B Change the reference of a component with a value matching a pattern.
 289 Parse the XYRS file \fIyour_xyrs_file.txt\fP, if the value in value column is "1n4148", then replace reference column with "D1", and write the output result to the file \fIoutput_file.txt\fP:
 290
 291         gxyrs your_xyrs_file.txt --eval "subst \\$REF_COL , 'D1', \\$VALUE_COL, '1n4148';" --output output_file.txt
 292 .PP
 293
 294 .TP
 295 .B Adds an offset to the X coordinate of a component  with a reference having a R followed by a number.
 296 Parse the XYRS file \fIyour_xyrs_file.txt\fP, 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 \fIoutput_file.txt\fP.
 297
 298 Value in column 3 can be in other units (for example: '640mil'):
 299
 300         gxyrs your_xyrs_file.txt --eval "offset \\$X_COL, '102.5mm', \\$REF_COL, 'R[0-9]+' ;" --output output_file.txt
 301 .PP
 302 \r
 303 .TP
 304 .B 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.
 305 Parse the XYRS file \fIyour_xyrs_file.txt\fP, 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 \fIoutput_file.txt\fP.
 306
 307 Value in column 3 can be in other units (for example: '640mil'):
 308
 309         gxyrs your_xyrs_file.txt --eval "mul_col_val \\$X_COL, 2.5, \\$REF_COL, 'R[0-9]+' ;" --output output_file.txt
 310 .PP
 311
 312 .TP
 313 .B Swap two columns.
 314 Parse the XYRS file \fIyour_xyrs_file.txt\fP, 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 \fIoutput_file.txt\fP:
 315
 316         gxyrs your_xyrs_file.txt --eval "swap_columns 3, 4, 4, 'R[0-9]+' ;" --output output_file.txt
 317 .PP
 318
 319 .TP
 320 .B Insert a column.
 321 Insert a column in the first position, displacing all existing columns to the right. Column value is 'new_column_value':
 322
 323         gxyrs your_xyrs_file.txt --eval "insert_column 0, 'new_column_value';" --output output_file.txt
 324 .PP
 325
 326 .SH "SEE ALSO"
 327 .TP
 328 .B
 329 regex(7), GNU regular expression manual
 330 .PP