.\"Created with GNOME Manpages Editor Wizard .\"http://sourceforge.net/projects/gmanedit2 .TH \fBgxyrs\fP 1 "Agosto 22, 2010" "" "\fBgxyrs\fP" .SH NAME \fBgxyrs\fP \- is a program to batch process XYRS files. .SH SYNOPSIS .B \fBgxyrs\fP .RI \fBfile\fP .RI [OPTIONS] .br .SH DESCRIPTION XYRS files are usually generated by PCB design programs, and are used by board assemblers. .PP Format of XYRS files is discussed in FILES section. .PP Processing of these files is often needed by board assemblers or designers to suit their process and tools flows. .PP \fBgxyrs\fP helps batch-processing these files. Rules and commands can be defined to make batch-processing easy. .PP \fBgxyrs\fP consists on a perl library providing the core functions, and a perl script providing some basic functionality. .PP It takes some arguments from the command line: input and output files, some modifiers, and an action-file or an action-string. .PP 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, and then writes the resulting line to the output file. .PP Since \fBgxyrs\fP is written in perl, actions are also written in this language. .SH OPTIONS .B .IP --help Display a usage message on standard output and exit successfully. .BI \--verbose Display more information messages when processing files. .TP .BI \--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. .TP .BI \--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. .TP .BI \--caseinsensitive Ignore case distinctions when comparing patterns. .TP .BI \--adjust "\| FILE\ " File with the commands to process the input file. .TP .BI \--eval "\| PATTERN\ " Interpret PATTERN as the commands to process the input file. .TP .BI \--output "\| FILE\ " Save the output to the specified FILE. If FILE string is "-" (without double quotes), then output is redirected to standard output STDOUT. .TP .BI \--output-delimiter "\| CHAR\ " Use the given CHAR as an output field delimiter. .SH "PREDEFINED VARIABLES" .PP gxyrs defines automatically the following variables: .PP .TP .B REF_COL column number (starting at 0) where the component reference is. .TP .B FOOTPRINT_COL column number (starting at 0) where the component footprint is. .TP .B X_COL column number (starting at 0) where the component's X location coordinate is. .TP .B Y_COL column number (starting at 0) where the component's Y location coordinate is. .TP .B ANGLE_COL column number (starting at 0) where the component rotation angle is. .TP .B LAYER_COL column number (starting at 0) where the component's layer side location is. .TP .B VALUE_COL column number (starting at 0) where the component's value is. Usually this is the component's part number. .TP .B LINE_NUMBER this is the line number of the input file that is being currently processed. .TP .B LINE array where each array element is a field or column of the input file's line being processed. .SH "BUILTIN COMMANDS" All the following commands accept a \fIchecklist\fP parameter. A \fIchecklist\fP is a list of one or more \fIcheck_items\fP. A \fIcheckitem\fP is a list of two single elements: .TP .B column_number is the data index number 'n' of the global variable \fBLINE\fP to be checked. The first element of the data has the number 1. .TP .B pattern is the regular expression to be matched. .PP The commands will only be executed on those lines that match all the \fIcheckitems\fP in the \fIchecklist\fP. .TP .B \fBdel_line\fP \fIchecklist\fP; Delete the line (global variable \fBLINE\fP) if \fIchecklist\fP is matched. Returns \-1 if error, 0 if not match, 1 if match and changed. .TP .B rotate_comp \fIangle_col\fP, \fIangle\fP, \fIchecklist\fP; rotate the component the degrees given in \fIangle\fP parameter, if \fIchecklist\fP is matched. The angle column number is \fIangle_col\fP. Returns 1 if match and changed, 0 if not match, \-1 if error. .TP .B subst_col_val \fIcol\fP, \fIvalue\fP, \fIchecklist\fP; Replace a column value by the new value \fIvalue\fP, if \fIchecklist\fP is matched. Returns 1 if match and changed, 0 if not match, \-1 if error. .TP .B change_col_units \fIunits\fP, \fIcolumn_numbers\fP; Change units of a given column number. More than one column number can be specified. \fIUnits\fP 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. .TP .B add_number_to_col \fIcol_number\fP, \fIvalue\fP, \fIchecklist\fP; 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. .TP .B translate_col_val \fIcol_number\fP, \fIstring\fP, \fIsubstitution\fP, \fIchecklist\fP; Translate a \fIstring\fP in the column \fIcol_number\fP if \fIchecklist\fP is matched. \fISubstitution\fP 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'. .TP .B mul_col_val \fIcol_number\fP, \fIfactor\fP, \fIchecklist\fP; Multiply the number in the specified column number \fIcol_number\fP by the given \fIfactor\fP, if \fIchecklist\fP 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. .TP .B swap_columns \fIcol_number1\fP, \fIcol_number2\fP, \fIchecklist\fP; Swap columns \fIcol_number1\fP and \fIcol_number2\fP if \fIchecklist\fP is matched. Returns \-1 if error, 0 if not match, 1 if match and changed. .TP .B insert_column \fIcol_number\fP, \fInew_column_value\fP; 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. Returns \-1 if error, 1 if the new column was inserted. .SH "RETURN VALUE" The return value of \fBgxyrs\fP is an integer with the following possible values: .TP 1 if the command found a match and the execution was successful .PP 0 if there was no match .PP \-1 if there was an error .PP \-2 if there was a warning .PP .SH FILES .TP .B 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. \fBgxyrs\fP tries to guess the file format, and column numbers, based on this header. Thus, the known column titles are the following: - for reference designator: \fIDesignator\fP, \fIRefDesignator\fP, \fIRefDes\fP. - for footprint: \fIFootprint\fP, \fITopCell\fP, \fIDescription\fP (only if there is no other "TopCell" column title). - for X coordinate: \fIMid X\fP, \fIX\fP. - for Y coordinate: \fIMid Y\fP, \fIY\fP. - for rotation angle: \fIRotation\fP, \fIrotation\fP, \fIRot\fP. - for location side: \fITB\fP, \fISide\fP, \fItop/bottom\fP. - for value: \fIComment\fP, \fIPartNumber\fP, \fIValue\fP. .TP .B 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 \fIgxyrs\fP. Each action file should end with the following line (with a carrier return at the end of the line): 1; .SH EXAMPLES .TP .B Run an action file: 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: gxyrs your_xyrs_file.txt \-\-adjust your_commands.txt \-\-output output_file.txt .PP .TP .B Run a command specified in the command line: 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: gxyrs your_xyrs_file.txt \-\-eval "your_commands" \-\-output output_file.txt .PP .TP .B Delete some lines matching a pattern. 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: gxyrs your_xyrs_file.txt \-\-eval "del 2, 'R[0\-9]+';" \-\-output output_file.txt .PP .TP .B Delete some lines matching a pattern, using the column number guessed by \fBgxyrs\fP. 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: gxyrs your_xyrs_file.txt \-\-eval "del \\$REF_COL, 'R[0\-9]+';" \-\-output output_file.txt .PP .TP .B Rotate some lines matching a pattern. 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: gxyrs your_xyrs_file.txt \-\-eval "rotate \\$ANGLE_COL, 90, \\$REF_COL, 'R[0\-9]+';" \-\-output output_file.txt .PP .TP .B Change all numbers to 'mm' units. 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: gxyrs your_xyrs_file.txt \-\-eval "change_units 'mm', 3, 5;" \-\-output output_file.txt .PP .TP .B Replace a value matching a pattern with another value. 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: gxyrs your_xyrs_file.txt \-\-eval "subst 3 , '100nF', 3, '0.1u'" \-\-output output_file.txt .PP .TP .B Change the reference of a component with a value matching a pattern. 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: gxyrs your_xyrs_file.txt \-\-eval "subst \\$REF_COL , 'D1', \\$VALUE_COL, '1n4148';" \-\-output output_file.txt .PP .TP .B Adds an offset to the X coordinate of a component with a reference having a R followed by a number. 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. 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 .PP .TP .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. 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. 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 .PP .TP .B Swap two columns. 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: gxyrs your_xyrs_file.txt \-\-eval "swap_columns 3, 4, 4, 'R[0\-9]+' ;" \-\-output output_file.txt .PP .TP .B 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 .PP .SH "SEE ALSO" .TP .B regex(7), GNU regular expression manual .PP