The mechanism for selecting points for measurements reaches its limits when

using frames to encapsulate building blocks, e.g., like macros or functions in
a programming language. Since measurements only know about the frame containing
a vector but not the frames containing that frame, invocations of this frame
from different places can only be distinguished within the min/next/max scheme.
(See the example in README.)

To eliminate this limitation, one needs a way to tell fped to consider a point
only if it has been instantiated through a certain path, e.g., by requiring
some other frames to be visited in its instantiation. This increases the number
of distinct points available for measurements.

The mechanism chosen is to qualify a measurement point with frames that lead to
it. This list of outer frames does not have to include all frames. Without
qualifying, the old behaviour results.

Note that this doesn't cover all possible ways in which a point can appear in
different roles. Multiple frame references can also result from repeating the
same frame reference in the same parent frame. The current qualification
mechanism does not allow such paths to be distinguished. However, one can 
always introduce intermediate frames for this purpose.

Furthermore, repetitions create multiple instances of a point, although in what
should be considered the same role.

- fpd.l: make scanner support free-format a little better by switching back to
  keyword mode after frame braces. This way, one can write a simple frame in a
  single line, which is useful for regression tests.
- fpd.l, fpd.y, README, test/dbg_meas: added %meas directive to print the 
  result of a measurement
- fpd.y, README: measurements can now be labeled. Note that, due to limitations
  of the grammar, the first measurement cannot be labeled.
- error.h, error.c (yywarn): new function for non-fatal diagnostics that always
  get reported to standard error
- bitset.h, bitset.c: functions to manipulate variable-size bit sets
- meas.h, fpd.y, README, test/meas_qual: added the means to specify qualifiers
  for points used in measurements
- dump.c (print_meas_base, print_meas): dump qualifiers
- delete.c (delete_references, test/del_frame): delete measurements that
  reference a frame being deleted in their qualifiers
- obj.h, obj.c (enumerate_frames, instantiate): enumerate all frames so that we
  have an index into the bit vector of visited frames
- meas.h, meas.c (reset_samples, meas_post), obj.c (generate_vecs,
  generate_frame, instantiate): record the set of frames visited for each
  sample
- meas.c (meas_post): only treat two instances of a point as equivalent if the
  set of frames visited of one of them is a superset of set of the other. In
  this case, keep the union of the two sets.
- meas.h, meas.c (meas_find_min, meas_find_next, meas_find_max),
  test/meas_qual: instantiate_meas_pkg only select points for which all frames
  in the qualification have been visited
- gui_meas.c (is_min, is_next, is_max, is_a_next): updated for above change
- inst.h, inst.c (curr_frame, propagate_bbox, add_inst, inst_begin_frame,
  inst_end_frame, inst_start): renamed curr_frame to frame_instantiating to
  avoid clash with curr_frame in fpd.y
- inst.h, inst.c (find_meas_hint): make global
- test/structure, test/del_vec, test/del_frame: fped now warns if a measurement
  is in an unlinked frame. Changed regressions tests to avoid this warning.
- test/Common: new function expect_grep to compare only part of the output



git-svn-id: http://svn.openmoko.org/trunk/eda/fped@5967 99fdad57-331a-0410-800a-d7fa5415bdb3

README

@@ -582,6 +582,60 @@ measx "width = " a >> b 0mm
 would print "width = 1mm"
 
 
+Additional qualifiers
+- - - - - - - - - - -
+
+When using frames as reusable building blocks, similar to functions or
+macros in many programming languages, one may need finer control over
+the points that are selected for measurements.
+
+For example, let us consider a frame "square" that draws a square
+centered at the frame's origin and with a side length given by the
+variable "size". This variable be set in the frame referencing
+"square".
+
+    frame square {
+	a: vec @(-size/2, -size/2)
+	b: vec @(size/2, size/2)
+	rect a b
+    }
+
+    frame small {
+	set size = 2mm
+	frame square @
+    }
+
+    frame big {
+	set size = 5mm
+	frame square @
+    }
+
+    frame small @
+    vec @(5mm, 0mm)
+    frame big .
+
+If we want to measure the size of each square, we could use
+
+measx square.a -> square.b
+
+Unfortunately, this only measures the small square. To reach the
+big frame, we need to tell fped to use only those points in "square"
+that have been placed when "square" was invoked from the big frame.
+
+This is accomplished by prefixing the points in question with the
+name(s) of the frames that need to be visited. The frame names are
+separated by slashes (/).
+
+measx big/square.a -> square.b
+
+For clarity, it's better to qualify both points, e.g.,
+
+measx big/square.a -> big/square.b
+
+If multiple frame names are given, they must be in the order in
+which they are invoked.
+
+
 Experimental: debugging directives
 ----------------------------------
 
@@ -592,6 +646,7 @@ most of which mimick the effect of GUI operations:
 %move <identifier> [<number>] <identifier>
 %frame <identifier> <qualified-base>
 %print <expression>
+%meas <identifier>
 %dump
 %exit
 %tsort { -<id> | +<id> | <id-before> <id-after> [<number>] ... }
@@ -622,6 +677,10 @@ parent frame's origin can be references as "@".
 %dump writes the footprint definition in the fped language to standard
 output. %exit immediately exits fped, without invoking the GUI.
 
+%print evaluates the expression and prints the result to standard output.
+%meas performs an instantiation and prints the value of the labeled
+measurement.
+
 %tsort is used to test-drive the topological sort algorithm. The items
 in the curly braces are declarations of nodes with (-<id>) or without
 (+<id>) decay or edges in the partial order. The optional number is