Index: 07_io/3_3_export_bom/index.html =================================================================== --- 07_io/3_3_export_bom/index.html (nonexistent) +++ 07_io/3_3_export_bom/index.html (revision 38030) @@ -0,0 +1,124 @@ + + +
++Export_bom is a configurable template based export plugin that prints +the BoM (Bill of Materials) list in a text file. The plugin classifies +subcircuits by a templatable ID and count how many instances of each ID +has on the board. The output contains an optional file header, then an optional +block (typically a single line) for each unique ID and an optional file +footer. +
+In pseudo-code: +
+print header_template +foreach subc in subcircuits { + id = template_render(subc, sort_id_template) + items[id]++ +} +sort(items[] by id) +foreach i in items[] { + print item_template_for_i +} +print footer_template ++
+ +
+Each bom export format has an user assigned NAME (which is the short name of the format). +There is a list of strings in the config tree under plugins/export_xy/templates; +each item is named as NAME.something where something is: +
+Templates are text strings; they are printed as is, keeping all newlines and +whitespace. Portions in between % signs are substituted, depending on the +context. + +
+
keyword | description + |
---|---|
%UTC% | current date and time in UTC + |
%author% | board author + |
%title% | board title + |
%count% | integer value, number of subcircuits in the current item group + |
%subc.a.KEY% | take a subcircuit (randomly) from the current item group and print its attribute value of the attribute whose name matches KEY; print empty string for non-existing attributes (but this can be controlled by the | suffix operator) + |
%subc.prefix% | print the sequence of left side alhpanumeric characters of subc.a.refdes; e.g. "R" for "R14" and "CONN" for "CONN1"; typically sort_id starts with this so that the output us sorted by "component type" (as deduced from refdes prefix) first + |
+Any of these may get an escape. prefix, , e.g. %escape.author% will print +the author with characters escaped. That means the resulting string +is checked for needs_escape character and are escaped using the +escape character. For example if the template contains: +
+value="%subc.a.value%" ++
+and needs_escape contains the double quote character and escape +is a backslash and the subc's value attribute is 1/4" bolt, the following +string is printed: +
+value="1/4\" bolt" ++
+Or if escape is not specified: +
+value="1/4_ bolt" ++
+Any substitution (e.g. "%foo%") may get an optional suffix operator: +
%foo|unk% | same as %foo% but print "unk" if foo evaluated to empty + |
%foo?yes% | same as %foo% but print "yes" if the value of foo represents true, "n/a" otherwise + |
%foo?yes:nope% | same as %foo% but print "yes" if the value of foo represents true, "nope" otherwise + |
+For example %subc.a.hand_solder?hand solder:reflow% will look at the +valueof the subcircuit's hand_solder attribute; if it's true, yes, on or +1, "hand solder" is printed, else "reflow" is printed. + +
+When subcircuits are first iterated, they are sorted into item groups by +their sort_id template. For each item group, only one subcircuit is +remembered, and only one block of info is printed. +
+In practice this means: +
+The last is a requirement because if there is an attribute, e.g. foo, and +there are two subcircuits with different foo values and sort_id +does not contain %subc.a.foo%, the two subcircuits may end up in the same item +group. Then if item contains %subc.a.foo%, it can print only one value, +so it will choose one of the two randomly. +
+However if %subc.a.foo% is on the sort_id template, the two +subcircuits will yield different ID which means they never end up in the +same item group. This also means any item group will have only one value for +subc.a.foo in this case, so printing %subc.a.foo% from item will be +deterministic. + + +