Index: doc/user/06_feature/query/index.html =================================================================== --- doc/user/06_feature/query/index.html (revision 32026) +++ doc/user/06_feature/query/index.html (revision 32027) @@ -15,6 +15,7 @@ This chapter describes the query language and its use. The chapter is split up to multiple sub-chapters:
Index: doc/user/06_feature/query/lang.html =================================================================== --- doc/user/06_feature/query/lang.html (nonexistent) +++ doc/user/06_feature/query/lang.html (revision 32027) @@ -0,0 +1,183 @@ + + + ++A DRC program is an unordered list of rules. Rules are evaluated and +violations reported. The advantage of a declarative language is that +intermediate results can be cached and reused. +
+The language is intended to be human readable and human writable, but +the main goal is to let programs and scripts (e.g. netlisters) to +generate it. +
+A rule consists of three parts: +
+Variables are named by the user and are local to the rule. TODO +Lists are ordered. +A list is consists of zero or more objects. An object is: +
+Objects have named properties (or fields): +
+Note: the language is case sensitive with keywords and builtins using +lowercase only. For better readability, in syntax description in this +document uppercase words are user chosen identifiers or fields. Whitespace +character sequences are usually treated as a single whitespace. (This +does not mean identifiers have to be uppercase in a program.) + +
+The syntax of a search statement is: +
+let LISTNAME EXPR ++ +
+It creates a list called LISTNAME and evaluates expression EXPR to all +available objects and adds the objects that match EXPR to the list. Each +matching object is added only once. The particular order of objects on +the list is random. Object "matches EXPR" when the EXPR evaluated on +the object yields true. + +
+The current object used in the iteration during the search is called @. + +
+An expression returns a value. A value can be: +
+A value is considered true if: +
+An expression is one of: + +
syntax | meaning + |
---|---|
(EXPR) | change precedence + |
EXPR || EXPR | logical OR (result: number) + |
EXPR && EXPR | logical AND (result: number) + |
EXPR1 thus EXPR2 | evaluate to EXPR2 if EXPR1 is true, else to void + |
EXPR + EXPR | add (number only) + |
EXPR - EXPR | subtract (number only) + |
EXPR * EXPR | multiply or ... (number only) + |
EXPR / EXPR | multiply or ... (number only) + |
EXPR == EXPR | the two values are equal + |
EXPR != EXPR | the two values are not equal + |
EXPR ~ string | regex match left EXPR using pattern right string + |
EXPR > EXPR | left EXPR is greater than right EXPR (number only) + |
EXPR >= EXPR | left EXPR is greater than or equal to right EXPR (number only) + |
EXPR < EXPR | left EXPR is less than right EXPR (number only) + |
EXPR <= EXPR | left EXPR is less than or equal to right EXPR (number only) + |
!EXPR | logical NOT (result: number, 0 or 1) + |
FUNC(EXPR, EXPR, ...) | call a function with 0 or more arguments + |
EXPR.field | evaluated to the value of an object field (see P45, P46) + |
+The syntax of an assertion is: +
+assert EXPR ++ +
+If the EXPR in an assert evaluates to false, a DRC violation is generated. + +
+If an assert EXPR is a list anywhere else than in a function argument, it is +evaluated for all valid members of the list (see P45, P46). For example +if there is a variable called FOO, which is a list of objects +(built using a search statement), expression +
+FOO.p.thickness ++
+is evaluated as many times as many objects are on the list, and the +full assert is checked each case. If there is another similar list +called BAR, an expression: +
+(FOO.p.thickness < BAR.p.thickness) ++
+will compare each possible pair of FOO and BAR objects. That is, if +FOO has 4 objects and BAR has 15 objects, that is 4*15 = 60 comparisons. +
+However, each list is iterated only once, even if it is referenced multiple +times in the same expression. For example, with the above lists: +
+(FOO.p.clearance > 10 mil) && (FOO.p.thickness < BAR.p.thickness) ++the potential number of iterations is still 4*15, and not 4*4*15 (FOO is +not iterated twice). In practice the engine leverages lazy evaluation so +if FOO.p.clearance is smaller than 10 mil, the right size is not evaluated. +See also: P45, P46. +
+A field reference is valid if the field exists. For example a line object +has a thickness attribute, thus the .p.thickness is valid, but a polygon +object does not have a thickness and .p.thickness on a polygon is invalid. +An user attribute reference (e.g. field .a.baz) is valid if the attribute +key exists in the given object. +
+Invalid fields are skipped in iterations. Thus if variable BLOBB is a list +that consists of 3 line, 2 arc and a layer objects, the following assert +will result in 2 comparisons only: +
+(BLOBB.p.width >= 10 mm) ++(because only arc objects have valid .p.width field). + +
+An invalid field in an expression is never considered an +error. In an assert statement it causes skipping an iteration. In a +search statement it evaluates to void. + +
+A void value is never equal to anything. A void value is not equal +even to another void value. + +
+Comments are lines starting with # + + +