Index: trunk/doc/user/06_feature/query/z1_functions.html =================================================================== --- trunk/doc/user/06_feature/query/z1_functions.html (revision 30695) +++ trunk/doc/user/06_feature/query/z1_functions.html (nonexistent) @@ -1,215 +0,0 @@ - -
- --Functions listed below can be called from a query expression. - -
-Determine length of a list. -
-Arguments: -
-Return value: integer length of the list. - -
-Determine length of a list. -
-Arguments: -
-Variable number of objects. -
-Return value: a list built of the objects passed. - -
-Calculate the distance of two points. -
-Arguments: -
-Return value: floating point distance value in nanometers. - - -
-Build a DRC violation report. -
-Arguments (a variable number of pairs of instruction and value): -
-Instruction is one of the following constants: -
-Return value: a list suitable for the drc_query to process. - -
-Return the netlist. -
-Arguments: None. -
-Return value: an unordered list of all networks specified on the -edited netlist (which is the netlist the board is currently -using). Each item of the list is a net. - - -
-Return terminals of a network. -
-Arguments: -
-Return value: an unordered list of objects (each terminal of the network -as described by the edited netlist). - - -
-Return terminals and all copper objects galvanically connected to a network. -
-Arguments: -
-Return value: an unordered list of copper objects connected to the network. - - -
-Return a list of objects, one terminal object per disconnecte segment of -the network. -
-Arguments: -
-Return value: an unordered list of terminal objects, one picked randomly -from each disconnected segment of the net. - - -
-Start a search on a galvanically connected network segment starting from -an object (typically returned by netsegs()) and generate a DRC violation -if there are copper objects with overlap smaller than the minimum_overlap. -
-Arguments: -
-Return value: a list that represents a DRC violation (or empty list). - -
-Start a search on a galvanically connected network segment starting from -an object (typically returned by netsegs()) and generate a DRC violation -if there are disconnected copper objects with distance smaller than -the minimum_distance from the network. -
-Arguments: -
-Return value: a list that represents a DRC violation (or empty list). - -
-Return a list of objects that are within the subc. -
-Arguments: -
-Return value: an unordered list of objects. - -
-Execute a pcb-rnd action. -
-Arguments: variable nunmber of objects and constants. -
-Return value: invalid on error, or the return value of the action. - -
-Fetch the value of a config node -
-Arguments: -
-Return value: invalid if the config node doesn't exist, else the value of -the config node (converted to the most appropriate data type). - - -
-Return the number of layers on which the ring of a padstack is too thin. -
-Arguments: -
-Return value: negative on wrong arguments, 0 if the padstack does not violate -the minimum_ring_thickness requirement, positive integer (number of violations) -otherwise. - -
-Return the number of visible polygon islands. -
-Arguments: -
-Return value: 0 if the polygon has been cleared out of existnece, 1 for normal -polygons and a positive integer higher than 1 if the polygon has the FULLPOLY -flag and is sliced into multiple parts not naturally connected by the polygon -itself. - - -
-Returns 1 if obj1 and obj2 overlap (even if they are on different layers) -
-Arguments: -
-Return value: 1 for overlap, 0 for no overlap. - Index: trunk/doc/user/06_feature/query/z2_tutor_cli.html =================================================================== --- trunk/doc/user/06_feature/query/z2_tutor_cli.html (revision 30695) +++ trunk/doc/user/06_feature/query/z2_tutor_cli.html (nonexistent) @@ -1,168 +0,0 @@ - -
- --The current document is a walk through of the practical aspects of the -language. It starts with the simplest examples while working towards more -complex cases. -
-A limited version of the functionality is accessible through a GUI -wizard when using the GTK HID. A separate -tutorial is dealing with that feature. - -
-The symbol @ in the query represents the iterator, or in other words, -the current object we are checking. The engine iterates over all -copper objects, silk objects, pins, holes, layers and nets. A simple query -that selects all objects looks like this: -
-query(select, '@') --The actual query expression was a single @ in this case. This made -the iteration happen, got the expression evaluated one each object. The -result of each evaluation was the given object. Since these objects -were all existing, valid objects, they were taken as logical value TRUE, -thus for each the add-to-selection was performed. -
-Note: it's usually a good idea to write the expression in single quotes, because -it may contain commas, double quotes and parenthesis that pcb-rnd's action parser may -take as action syntax. -
-The same expression can ran with eval would print the result of each -evaluation: -
-query(eval, '@') --This is visible on the terminal pcb-rnd was started from - on X, it's a good -idea to start a terminal and run pcb-rnd from that instead from a menu or -icon. The rest of this tutorial will use the eval query because it's easier -to include the result of an eval than of a selection. Most examples will -specify the query expression only, without quotes - the reader should -add the query(eval, ' ') part. - -
-query(eval, '1') --This will calculate the value of 1 and prints it to the standard output. Since -there's no iteration, this can not result in changes in selection. However, -it makes it easy to demonstrate some basic concepts of the query language. -
-Note: if @ is present multiple times in the expression, it's still only -one loop over all objects. When evaluating the expression for a given object, -all instances of @ are substituted with the same object in that iteration. - - -
expression | result | explanation - |
---|---|---|
42 | 42 | the integer value 42 - |
3.14 | 3.14 | the floating point value 3.14 - |
10 mil | 254000 | a number with a unit suffix is converted to pcb-rnd's internal coordinate unit (nanometers) - |
1+2 | 3 | sum of 1 and 2 - |
2*4 | 8 | multiplication - |
47/4 | 11 | integer division (because both operands were integers) - |
47/4.0 | 11.75 | floating point division (because at least one of the operands was a float) - |
(1+2)*5 | 15 | parenthesis works as usual - |
1 && 0 | 0 | logical AND - the result is 1 if both operands were TRUE, 0 else - |
1 || 0 | 1 | logical OR - the result is 1 if either operand was TRUE, 0 else - |
!2 | 0 | logical NOT - 2 is non-zero, so it is TRUE, negate this to get the result (FALSE, which is 0) - |
4 > 2 | 1 | because four is greater than two; all the usual relational operators work: == is equal, != is not-equal, <, <=, > and >=. - |
- @.thickness --
-Next, we can already select all traces thicker than 10 mil: -
- query(select, '@.thickness > 10 mil') --
-Because logical expressions are available, it's easy to select all medium-thick -lines: -
- (@.thickness >= 10 mil) && (@.thickness <= 30 mil) --
-or any trace that's too thin or too thick: -
- (@.thickness < 10 mil) || (@.thickness > 30 mil) --
-or traces that don't match our preferred 8, 10 and 15 mil thickness values: -
- (@.thickness != 8 mil) && (@.thickness != 10 mil) && (@.thickness != 15 mil) -- -
-The answer is the invalid value, which is neither true nor false. If -a property does not exist in a given object, the result is the invalid value -or invalid for short. The invalid is treated specially: -
-The invalid value is generated only when the expression is valid but the -actual object doesn't have the feature needed. If the expression is wrong, -an error is generated and the expression stops evaluating immediately. - -
- @.layer.name --
-Referencing non-existing properties yields an error, e.g. @.thickness.layer -is an error - in contrast with @.layer, which may evaluate to the -invalid value (e.g. for vias or nets, because they don't have layers). -The difference is that thickness can not have a layer ever (thus is an error) -while @.layer is either applicable or not, but potentially could work, this -when it doesn't, it's only an invalid value. -
-Further useful property combinations: -TODO -
-There is a full list of all properties. Index: trunk/doc/user/06_feature/query/functions.html =================================================================== --- trunk/doc/user/06_feature/query/functions.html (nonexistent) +++ trunk/doc/user/06_feature/query/functions.html (revision 30696) @@ -0,0 +1,215 @@ + +
+ ++Functions listed below can be called from a query expression. + +
+Determine length of a list. +
+Arguments: +
+Return value: integer length of the list. + +
+Determine length of a list. +
+Arguments: +
+Variable number of objects. +
+Return value: a list built of the objects passed. + +
+Calculate the distance of two points. +
+Arguments: +
+Return value: floating point distance value in nanometers. + + +
+Build a DRC violation report. +
+Arguments (a variable number of pairs of instruction and value): +
+Instruction is one of the following constants: +
+Return value: a list suitable for the drc_query to process. + +
+Return the netlist. +
+Arguments: None. +
+Return value: an unordered list of all networks specified on the +edited netlist (which is the netlist the board is currently +using). Each item of the list is a net. + + +
+Return terminals of a network. +
+Arguments: +
+Return value: an unordered list of objects (each terminal of the network +as described by the edited netlist). + + +
+Return terminals and all copper objects galvanically connected to a network. +
+Arguments: +
+Return value: an unordered list of copper objects connected to the network. + + +
+Return a list of objects, one terminal object per disconnecte segment of +the network. +
+Arguments: +
+Return value: an unordered list of terminal objects, one picked randomly +from each disconnected segment of the net. + + +
+Start a search on a galvanically connected network segment starting from +an object (typically returned by netsegs()) and generate a DRC violation +if there are copper objects with overlap smaller than the minimum_overlap. +
+Arguments: +
+Return value: a list that represents a DRC violation (or empty list). + +
+Start a search on a galvanically connected network segment starting from +an object (typically returned by netsegs()) and generate a DRC violation +if there are disconnected copper objects with distance smaller than +the minimum_distance from the network. +
+Arguments: +
+Return value: a list that represents a DRC violation (or empty list). + +
+Return a list of objects that are within the subc. +
+Arguments: +
+Return value: an unordered list of objects. + +
+Execute a pcb-rnd action. +
+Arguments: variable nunmber of objects and constants. +
+Return value: invalid on error, or the return value of the action. + +
+Fetch the value of a config node +
+Arguments: +
+Return value: invalid if the config node doesn't exist, else the value of +the config node (converted to the most appropriate data type). + + +
+Return the number of layers on which the ring of a padstack is too thin. +
+Arguments: +
+Return value: negative on wrong arguments, 0 if the padstack does not violate +the minimum_ring_thickness requirement, positive integer (number of violations) +otherwise. + +
+Return the number of visible polygon islands. +
+Arguments: +
+Return value: 0 if the polygon has been cleared out of existnece, 1 for normal +polygons and a positive integer higher than 1 if the polygon has the FULLPOLY +flag and is sliced into multiple parts not naturally connected by the polygon +itself. + + +
+Returns 1 if obj1 and obj2 overlap (even if they are on different layers) +
+Arguments: +
+Return value: 1 for overlap, 0 for no overlap. + Index: trunk/doc/user/06_feature/query/tutor_cli.html =================================================================== --- trunk/doc/user/06_feature/query/tutor_cli.html (nonexistent) +++ trunk/doc/user/06_feature/query/tutor_cli.html (revision 30696) @@ -0,0 +1,168 @@ + +
+ ++The current document is a walk through of the practical aspects of the +language. It starts with the simplest examples while working towards more +complex cases. +
+A limited version of the functionality is accessible through a GUI +wizard when using the GTK HID. A separate +tutorial is dealing with that feature. + +
+The symbol @ in the query represents the iterator, or in other words, +the current object we are checking. The engine iterates over all +copper objects, silk objects, pins, holes, layers and nets. A simple query +that selects all objects looks like this: +
+query(select, '@') ++The actual query expression was a single @ in this case. This made +the iteration happen, got the expression evaluated one each object. The +result of each evaluation was the given object. Since these objects +were all existing, valid objects, they were taken as logical value TRUE, +thus for each the add-to-selection was performed. +
+Note: it's usually a good idea to write the expression in single quotes, because +it may contain commas, double quotes and parenthesis that pcb-rnd's action parser may +take as action syntax. +
+The same expression can ran with eval would print the result of each +evaluation: +
+query(eval, '@') ++This is visible on the terminal pcb-rnd was started from - on X, it's a good +idea to start a terminal and run pcb-rnd from that instead from a menu or +icon. The rest of this tutorial will use the eval query because it's easier +to include the result of an eval than of a selection. Most examples will +specify the query expression only, without quotes - the reader should +add the query(eval, ' ') part. + +
+query(eval, '1') ++This will calculate the value of 1 and prints it to the standard output. Since +there's no iteration, this can not result in changes in selection. However, +it makes it easy to demonstrate some basic concepts of the query language. +
+Note: if @ is present multiple times in the expression, it's still only +one loop over all objects. When evaluating the expression for a given object, +all instances of @ are substituted with the same object in that iteration. + + +
expression | result | explanation + |
---|---|---|
42 | 42 | the integer value 42 + |
3.14 | 3.14 | the floating point value 3.14 + |
10 mil | 254000 | a number with a unit suffix is converted to pcb-rnd's internal coordinate unit (nanometers) + |
1+2 | 3 | sum of 1 and 2 + |
2*4 | 8 | multiplication + |
47/4 | 11 | integer division (because both operands were integers) + |
47/4.0 | 11.75 | floating point division (because at least one of the operands was a float) + |
(1+2)*5 | 15 | parenthesis works as usual + |
1 && 0 | 0 | logical AND - the result is 1 if both operands were TRUE, 0 else + |
1 || 0 | 1 | logical OR - the result is 1 if either operand was TRUE, 0 else + |
!2 | 0 | logical NOT - 2 is non-zero, so it is TRUE, negate this to get the result (FALSE, which is 0) + |
4 > 2 | 1 | because four is greater than two; all the usual relational operators work: == is equal, != is not-equal, <, <=, > and >=. + |
+ @.thickness ++
+Next, we can already select all traces thicker than 10 mil: +
+ query(select, '@.thickness > 10 mil') ++
+Because logical expressions are available, it's easy to select all medium-thick +lines: +
+ (@.thickness >= 10 mil) && (@.thickness <= 30 mil) ++
+or any trace that's too thin or too thick: +
+ (@.thickness < 10 mil) || (@.thickness > 30 mil) ++
+or traces that don't match our preferred 8, 10 and 15 mil thickness values: +
+ (@.thickness != 8 mil) && (@.thickness != 10 mil) && (@.thickness != 15 mil) ++ +
+The answer is the invalid value, which is neither true nor false. If +a property does not exist in a given object, the result is the invalid value +or invalid for short. The invalid is treated specially: +
+The invalid value is generated only when the expression is valid but the +actual object doesn't have the feature needed. If the expression is wrong, +an error is generated and the expression stops evaluating immediately. + +
+ @.layer.name ++
+Referencing non-existing properties yields an error, e.g. @.thickness.layer +is an error - in contrast with @.layer, which may evaluate to the +invalid value (e.g. for vias or nets, because they don't have layers). +The difference is that thickness can not have a layer ever (thus is an error) +while @.layer is either applicable or not, but potentially could work, this +when it doesn't, it's only an invalid value. +
+Further useful property combinations: +TODO +
+There is a full list of all properties.