Index: index.html =================================================================== --- index.html (revision 30429) +++ index.html (revision 30430) @@ -23,7 +23,7 @@

stroke (mouse gestures) Index: query/tutor_cli.html =================================================================== --- query/tutor_cli.html (revision 30429) +++ query/tutor_cli.html (nonexistent) @@ -1,168 +0,0 @@ - - - -

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: query/functions.html =================================================================== --- query/functions.html (revision 30429) +++ query/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: query/index.html =================================================================== --- query/index.html (nonexistent) +++ query/index.html (revision 30430) @@ -0,0 +1,20 @@ + + + +
Query: data query language
+
+The query language is a powerful domain specific, declarative scripting +language that can: +
+
list drawing objects, layers and networks +
iterate over them +
evaluate complex logical expressions using them +
selecting/unselecting/printing or drc-reporting objects depending on the result of the evaluation. +
+
+This chapter describes the query language and its use. The chapter is +split up to multiple sub-chapters: +
+
query functions +
CLI/scripting tutorial +
Index: query/z1_functions.html =================================================================== --- query/z1_functions.html (nonexistent) +++ query/z1_functions.html (revision 30430) @@ -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: query/z2_tutor_cli.html =================================================================== --- query/z2_tutor_cli.html (nonexistent) +++ query/z2_tutor_cli.html (revision 30430) @@ -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.

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