Index: doc/user/06_feature/query/functions.html
===================================================================
--- doc/user/06_feature/query/functions.html (revision 33117)
+++ doc/user/06_feature/query/functions.html (revision 33118)
@@ -235,6 +235,79 @@
+ Advanced layer access
+
+ layer_setup(obj, directive [, res])
+
+ Takes an object and executes a directive on the layer setup of the object.
+ If the directive matches, retruns either a measure (if result is specified)
+ or returns true.
+
+ Directive is a comma separated list of requirements; the directive matches
+ only if all requirements matched. A requirement is specified in the form
+ of key:value.
+
+ Key is a dash separated list of:
+
+ - above - match a layer group that is above the object's layer (location modifier)
+
- below - match a layer group that is below the object's layer (location modifier)
+
- on - match the layer group of the object (location modifier)
+
- type - match a layer group type; value is a layer group type
+
- net - objects belonging to a specific net on an adjacent copper layer group that covers the current object; value is the name of a net
+
- netmargin - supplement for the net key: require the cover to extend the specified; value is a size (coord)
+
+
+ Examples requirements:
+
+ - above-type:copper - there is an adjacent copper layer group above the object's layer
+
- below-type:!copper - there is no adjacent copper layer group below the object's layer
+
- above-net:vcc - there are copper objects connected to the net called "vcc" on the adjacent copper layer group above the current object
+
- above-net:vcc,above-netmargin:1.3mm - there are copper objects connected to the net called "vcc" on the adjacent copper layer group above the current object; coverage calculated +1.3mm around the object; defaults to 0 if not specified
+
+
+ "Above" and "below" are not in the board's coordinate system, but are
+ relative to the object. In other words, the function first assumes
+ above is upward and below is downward, then runs all requirements on the object.
+ If there is no match, above/below directions are reversed and the test is ran
+ again.
+
+ Example directive:
+
above-type:!copper,below-net:gnd,below-netmargin:125mil
+
This directive requires:
+
+ - there's no copper layer group above the object (so that the object is on the top or bottom copper layer group)
+
- the object is fully covered on the adjacent copper layer group "below" by copper objects belonging to the network named "gnd"
+
- plus this coverage extends beyond the object to 125mil in every direction
+
+
+ Normally the return value is integer 0 (no match) or 1 (match).
+
+ If the optional res parameter is specified, it must be a requirement
+ where key is result. Alternatively the result requirement can
+ be specified in the directive parameter. When a result is
+ specified, the return value of layer_setup() will not be a 0/1 boolean but
+ a readout specified by the result requirement (or the invalid value
+ is returned on no match). The value of a
+ result requirement is one of:
+
+ - above - use a layer group that is above the object's layer (location modifier)
+
- below - use a layer group that is below the object's layer (location modifier)
+
- on - use the layer group of the object (location modifier)
+
- substrate - return the substrate layer group (using the location)
+
- uncovered - return the area (in square nanometers) that are not covered by the "net" directive; note: the total area is the area of the original object bloated by netmargin
+
+
+ Complex query script example:
+
layer_setup(OBJ, "above-type:!copper,below-net:gnd", "result:below-substrate").a."thickness"
+
+ OBJ will match if it is on the top or bottom copper layer and is fully
+ covered by gnd copper on the adjacent copper layer group on the next internal
+ copper layer group. When matched, the return value of layer_setup is the
+ substrate layer group between the object's layer and that adjacent
+ internal layer group. The .a."thickness" part retrieves the value of
+ the thickness attribute of this substrate layer. On mismatch, the whole expression
+ evaluates to the invalid value.
+
Misc
action(args...)