Index: doc/user/06_feature/query/z1_functions.html =================================================================== --- doc/user/06_feature/query/z1_functions.html (revision 30695) +++ doc/user/06_feature/query/z1_functions.html (nonexistent) @@ -1,215 +0,0 @@ - - - -

Query: advanced search, command line: function calls available

- -

-Functions listed below can be called from a query expression. - -

llen(lst)

-Determine length of a list. -

-Arguments: -

lst is the list (should be written as list(lst) to make sure no iteration is done) -

-Return value: integer length of the list. - -

mklist(args...)

-Determine length of a list. -

-Arguments: -

-Variable number of objects. -

-Return value: a list built of the objects passed. - -

distance(x1, y1, x2, y2)

-Calculate the distance of two points. -

-Arguments: -

x1: first point, X coordinate -
y1: first point, Y coordinate -
x2: second point, X coordinate -
y2: second point, Y coordinate -

-Return value: floating point distance value in nanometers. - - -

violation(i1, v1, ..., iN, vN)

-Build a DRC violation report. -

-Arguments (a variable number of pairs of instruction and value): -

i is an instruction, see below. -
v is a value (a constant or an object) -

-Instruction is one of the following constants: -

DRCGRP1 - the following v is an object, part of group 1 of offending objects -
DRCGRP2 - the following v is an object, part of group 2 of offending objects -
DRCEXPECT - the following v is a numeric value that represent the expected value -
DRCMEASURE - the following v is a numeric value that represent the measured value that mismatches the expected value -

-Return value: a list suitable for the drc_query to process. - -

netlist()

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

netterms(net)

-Return terminals of a network. -

-Arguments: -

net is a network of the netlist of the current board. -

-Return value: an unordered list of objects (each terminal of the network -as described by the edited netlist). - - -

netobjs(net)

-Return terminals and all copper objects galvanically connected to a network. -

-Arguments: -

net is a network of the netlist of the current board. -

-Return value: an unordered list of copper objects connected to the network. - - -

netsegs(net)

-Return a list of objects, one terminal object per disconnecte segment of -the network. -

-Arguments: -

net is a network of the netlist of the current board. -

-Return value: an unordered list of terminal objects, one picked randomly -from each disconnected segment of the net. - - -

netbreak(obj, minimum_overlap)

-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: -

obj is the starting object of the search -
minimum_overlap is the coordinate value that represents the minimum required ovlerap between copper objects (e.g. 0.5mm) -

-Return value: a list that represents a DRC violation (or empty list). - -

netshort(obj, minimum_distance)

-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: -

obj is the starting object of the search -
minimum_distance is the coordinate value that represents the minimum required distance from any non-connected copper objects (e.g. 0.5mm) -

-Return value: a list that represents a DRC violation (or empty list). - -

subcobjs(subc)

-Return a list of objects that are within the subc. -

-Arguments: -

subc is an object of type subcircuit -

-Return value: an unordered list of objects. - -

action(args...)

-Execute a pcb-rnd action. -

-Arguments: variable nunmber of objects and constants. -

-Return value: invalid on error, or the return value of the action. - -

getconf(path)

-Fetch the value of a config node -

-Arguments: -

path is a conf node path, e.g. editor/grid -

-Return value: invalid if the config node doesn't exist, else the value of -the config node (converted to the most appropriate data type). - - -

pstkring(pstk, minimum_ring_thickness)

-Return the number of layers on which the ring of a padstack is too thin. -

-Arguments: -

pstk is the padstack object -
minimum_ring_thickness is a coordinate value of the minimum ring thickness -

-Return value: negative on wrong arguments, 0 if the padstack does not violate -the minimum_ring_thickness requirement, positive integer (number of violations) -otherwise. - -

poly_num_islands(poly)

-Return the number of visible polygon islands. -

-Arguments: -

poly is the polygon object -

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

overlap(obj1, obj2)

-Returns 1 if obj1 and obj2 overlap (even if they are on different layers) -

-Arguments: -

obj1 and obj2 are objects. -

-Return value: 1 for overlap, 0 for no overlap. - Index: doc/user/06_feature/query/z2_tutor_cli.html =================================================================== --- doc/user/06_feature/query/z2_tutor_cli.html (revision 30695) +++ doc/user/06_feature/query/z2_tutor_cli.html (nonexistent) @@ -1,168 +0,0 @@ - - - -

Query: advanced search, command line tutorial: query language

- -

scope

- -pcb-rnd from version 1.1.3 features a flexible advanced search that helps -the user selecting/unselecting objects that match a given logical expression. -The core of the feature is the pcb-rnd query language. The same language -is used in the programmable DRC (see also: -a more formal description of the language). -

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

Actions

-The query(act, expr) action creates the list called "@", which contains all -objects of the design. Then it iterates over this list (if needed) and -evaluates the query expression on each object. For each evaluation "act" -is performed; "act" is one of: -

select - add the matching object to the selections if expr evaluated to true -
unselect - remove the matching object from the selections if expr evaluated to true -
eval - print the result of the expression to stdout -
dump - this inhibits evaluating; it compiles the expression and dumps the parse tree (useful for debugging) -

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

iteration vs. evaluate once

-If an expression does not reference the @ object, no iteration is performed -and the expression is ran only once: -

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

grammar: arithmetics and logics

-For example the integer and floating point numbers and the usual -arithmetic and logical operators work as expected: - - -

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 >=. -

- -

grammar: object properties

-Object have named properties, e.g. the thickness of a line (or arc, or -trace in general) is called ".thickness", so the thickness of -the current object is: -

-	@.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)
-

- -

grammar: invalid value

-But how comes an expression like '@.thickness > 10 mil' works while -@ iterates over non-trace objects, like layers, nets or subcircuits that -clearly have no thickness? -

-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: -

in arithmetic operations it propagates: if either operand is invalid, the result is invalid, e.g. 1+invalid = invalid; this affects +, -, *, / and all the relational operators -
in binary logic operations (&& and ||), it is ignored: it is assumed to be true in a && and false in a || so the outcome depends on the other operand -
in logical NOT (!), TODO -

-When @ refers to a non-trace object, @.thickness is invalid and -'@.thickness > 10 mil' is evaluated t invalid. If the result is not TRUE, -the requested action is not performed. -

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

grammar: more properties

-Some properties are a single numeric value, like thickness, or the -.name of a layer (which is a string) but others are objects. For -example the .layer property of a line or arc refers to the layer -object the given line or arc is drawn on. These in turn can be combined, -and the "name of the layer the current object is on": -

-	@.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: doc/user/06_feature/query/functions.html =================================================================== --- doc/user/06_feature/query/functions.html (nonexistent) +++ doc/user/06_feature/query/functions.html (revision 30696) @@ -0,0 +1,215 @@ + + + +

Query: advanced search, command line: function calls available

+ +

+Functions listed below can be called from a query expression. + +

llen(lst)

+Determine length of a list. +

+Arguments: +

lst is the list (should be written as list(lst) to make sure no iteration is done) +

+Return value: integer length of the list. + +

mklist(args...)

+Determine length of a list. +

+Arguments: +

+Variable number of objects. +

+Return value: a list built of the objects passed. + +

distance(x1, y1, x2, y2)

+Calculate the distance of two points. +

+Arguments: +

x1: first point, X coordinate +
y1: first point, Y coordinate +
x2: second point, X coordinate +
y2: second point, Y coordinate +

+Return value: floating point distance value in nanometers. + + +

violation(i1, v1, ..., iN, vN)

+Build a DRC violation report. +

+Arguments (a variable number of pairs of instruction and value): +

i is an instruction, see below. +
v is a value (a constant or an object) +

+Instruction is one of the following constants: +

DRCGRP1 - the following v is an object, part of group 1 of offending objects +
DRCGRP2 - the following v is an object, part of group 2 of offending objects +
DRCEXPECT - the following v is a numeric value that represent the expected value +
DRCMEASURE - the following v is a numeric value that represent the measured value that mismatches the expected value +

+Return value: a list suitable for the drc_query to process. + +

netlist()

+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. + + +

netterms(net)

+Return terminals of a network. +

+Arguments: +

net is a network of the netlist of the current board. +

+Return value: an unordered list of objects (each terminal of the network +as described by the edited netlist). + + +

netobjs(net)

+Return terminals and all copper objects galvanically connected to a network. +

+Arguments: +

net is a network of the netlist of the current board. +

+Return value: an unordered list of copper objects connected to the network. + + +

netsegs(net)

+Return a list of objects, one terminal object per disconnecte segment of +the network. +

+Arguments: +

net is a network of the netlist of the current board. +

+Return value: an unordered list of terminal objects, one picked randomly +from each disconnected segment of the net. + + +

netbreak(obj, minimum_overlap)

+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: +

obj is the starting object of the search +
minimum_overlap is the coordinate value that represents the minimum required ovlerap between copper objects (e.g. 0.5mm) +

+Return value: a list that represents a DRC violation (or empty list). + +

netshort(obj, minimum_distance)

+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: +

obj is the starting object of the search +
minimum_distance is the coordinate value that represents the minimum required distance from any non-connected copper objects (e.g. 0.5mm) +

+Return value: a list that represents a DRC violation (or empty list). + +

subcobjs(subc)

+Return a list of objects that are within the subc. +

+Arguments: +

subc is an object of type subcircuit +

+Return value: an unordered list of objects. + +

action(args...)

+Execute a pcb-rnd action. +

+Arguments: variable nunmber of objects and constants. +

+Return value: invalid on error, or the return value of the action. + +

getconf(path)

+Fetch the value of a config node +

+Arguments: +

path is a conf node path, e.g. editor/grid +

+Return value: invalid if the config node doesn't exist, else the value of +the config node (converted to the most appropriate data type). + + +

pstkring(pstk, minimum_ring_thickness)

+Return the number of layers on which the ring of a padstack is too thin. +

+Arguments: +

pstk is the padstack object +
minimum_ring_thickness is a coordinate value of the minimum ring thickness +

+Return value: negative on wrong arguments, 0 if the padstack does not violate +the minimum_ring_thickness requirement, positive integer (number of violations) +otherwise. + +

poly_num_islands(poly)

+Return the number of visible polygon islands. +

+Arguments: +

poly is the polygon object +

+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. + + +

overlap(obj1, obj2)

+Returns 1 if obj1 and obj2 overlap (even if they are on different layers) +

+Arguments: +

obj1 and obj2 are objects. +

+Return value: 1 for overlap, 0 for no overlap. + Index: doc/user/06_feature/query/tutor_cli.html =================================================================== --- doc/user/06_feature/query/tutor_cli.html (nonexistent) +++ doc/user/06_feature/query/tutor_cli.html (revision 30696) @@ -0,0 +1,168 @@ + + + +

Query: advanced search, command line tutorial: query language

+ +

scope

+ +pcb-rnd from version 1.1.3 features a flexible advanced search that helps +the user selecting/unselecting objects that match a given logical expression. +The core of the feature is the pcb-rnd query language. The same language +is used in the programmable DRC (see also: +a more formal description of the language). +

+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. + +

Actions

+The query(act, expr) action creates the list called "@", which contains all +objects of the design. Then it iterates over this list (if needed) and +evaluates the query expression on each object. For each evaluation "act" +is performed; "act" is one of: +

select - add the matching object to the selections if expr evaluated to true +
unselect - remove the matching object from the selections if expr evaluated to true +
eval - print the result of the expression to stdout +
dump - this inhibits evaluating; it compiles the expression and dumps the parse tree (useful for debugging) +

+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. + +

iteration vs. evaluate once

+If an expression does not reference the @ object, no iteration is performed +and the expression is ran only once: +

+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. + + +

grammar: arithmetics and logics

+For example the integer and floating point numbers and the usual +arithmetic and logical operators work as expected: + + +

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 >=. +

+ +

grammar: object properties

+Object have named properties, e.g. the thickness of a line (or arc, or +trace in general) is called ".thickness", so the thickness of +the current object is: +

+	@.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)
+

+ +

grammar: invalid value

+But how comes an expression like '@.thickness > 10 mil' works while +@ iterates over non-trace objects, like layers, nets or subcircuits that +clearly have no thickness? +

+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: +

in arithmetic operations it propagates: if either operand is invalid, the result is invalid, e.g. 1+invalid = invalid; this affects +, -, *, / and all the relational operators +
in binary logic operations (&& and ||), it is ignored: it is assumed to be true in a && and false in a || so the outcome depends on the other operand +
in logical NOT (!), TODO +

+When @ refers to a non-trace object, @.thickness is invalid and +'@.thickness > 10 mil' is evaluated t invalid. If the result is not TRUE, +the requested action is not performed. +

+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. + +

grammar: more properties

+Some properties are a single numeric value, like thickness, or the +.name of a layer (which is a string) but others are objects. For +example the .layer property of a line or arc refers to the layer +object the given line or arc is drawn on. These in turn can be combined, +and the "name of the layer the current object is on": +

+	@.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.