Metro Data Model - Revision history

Drobbins at 16:02, 8 January 2012

2012-01-08T16:02:29Z

Drobbins: /* Metro Data Model */

2011-01-17T22:36:53Z

‎Metro Data Model

Drobbins at 22:36, 17 January 2011

2011-01-17T22:36:39Z

Brantgurga: I placed this in the Metro category.

2010-12-15T19:37:37Z

I placed this in the Metro category.

Drobbins at 04:24, 28 November 2010

2010-11-28T04:24:36Z

Drobbins at 04:24, 28 November 2010

2010-11-28T04:24:04Z

Drobbins at 04:23, 28 November 2010

2010-11-28T04:23:20Z

Drobbins at 04:22, 28 November 2010

2010-11-28T04:22:47Z

Drobbins at 04:22, 28 November 2010

2010-11-28T04:22:16Z

Brantgurga: I fixed up the document structure a bit.

2010-11-13T06:11:08Z

I fixed up the document structure a bit.

← Older revision		Revision as of 16:02, 8 January 2012
Line 123:		Line 123:
	echo Hi There :)		echo Hi There :)
	]</pre>		]</pre>
		+
		+	[[Category:Metro]]

← Older revision		Revision as of 22:36, 17 January 2011
Line 1:		Line 1:
−	~~= Metro Data Model =~~
−
	== Goals ==		== Goals ==

@@ Line 1: / Line 1: @@
 The Metro Data Model has been designed to provide you with an optimal way to organize build data.
@@ Line 16: / Line 20: @@
-= First Look =
+== First Look ==
 Here is some sample Metro data:
@@ Line 75: / Line 79: @@
 Above, we have used two new parser features. Inside <tt>[section path/mirror]</tt>, we can define the <tt>path/mirror</tt> element itself by using a blank element name, followed by a <tt>:</tt>. The next parser feature we see above is that we can use <tt>$[]</tt> to reference the value of the <tt>path/mirror</tt> value. <tt>$[]</tt> will always reference the value of the element specified in the section annotation. Also note that as of Metro 1.1, <tt>$[:]</tt> can be used as an alternate form of <tt>$[]</tt>. In addition, as of Metro 1.2.4, <tt>$[:foo]</tt> can be used as an alternate form of <tt>$[section-name/foo]</tt>.
-= Collect Annotations =
+== Collect Annotations ==
 Many scripting languages have the notion of an &quot;include&quot; file, or &quot;importing&quot; additional data from a remote file. Metro has this concept as well, but it is implemented in a somewhat different way. You can tell Metro to include data from another file by using a ''collect annotation''.
@@ Line 84: / Line 88: @@
 Now, we called these things &quot;collect annotations&quot; for a reason - in Metro, they work slightly differently than most languages implement <tt>include</tt> and <tt>import</tt>. The main difference is that in Metro, a collect annotation does not happen right away. Instead, Metro will add the file to be collected (in this case, that would be the file <tt>/usr/lib/metro/myfile.txt</tt>, or whatever <tt>$[path/metro]/myfile.txt</tt> evaluates to) to a ''collection queue''. This means that Metro will read in the contents of the file at some point in time, and the data in the file will be available to you by the time the parsing is complete. But because Metro doesn't care about the order in which data is defined, it doesn't have the same concept of &quot;read in the data - right now!&quot; that an include or import statement does in other languages.
-== Conditional Collect Annotations ==
+=== Conditional Collect Annotations ===
 Metro no longer officially supports conditional collect annotations; however, simple collect annotations can be used to make conditional decisions in Metro, as follows:
@@ Line 96: / Line 100: @@
 Using the <tt>:zap</tt> modifier, the entire collect argument will be replaced with the empty string if <tt>$[snapshot/type]</tt> is undefined. If Metro is asked to collect an empty string, it will not throw an exception. So this is a handy way to conditionally disable collection of a file. But please note that for all non-null values of <tt>$[snapshot/type]</tt>, a corresponding file must exist on disk in <tt>./snapshots/</tt> or Metro will throw an exception. <tt>:zap</tt> is explained in more detail in the &quot;Special Variable Expansion&quot; section, below.
-= Multi-line elements =
+== Multi-line elements ==
 Metro supports multi-line elements and they are the foundation of Metro's ''template'' engine. A multi-line element can be defined as follows, by using square brackets to delimit multi-line data:
@@ Line 121: / Line 125: @@
 echo Hi There :)
 ]</pre>

← Older revision		Revision as of 19:37, 15 December 2010
Line 213:		Line 213:

	In general, it's recommended that you use strict parsing behavior whenever possible, as it will allow Metro to detect potential error conditions. Use <tt>[option parse/lax]</tt> and (with Metro 1.2+) the finer-grained <tt>:lax</tt> suffix to enable lax parsing behavior only when necessary.		In general, it's recommended that you use strict parsing behavior whenever possible, as it will allow Metro to detect potential error conditions. Use <tt>[option parse/lax]</tt> and (with Metro 1.2+) the finer-grained <tt>:lax</tt> suffix to enable lax parsing behavior only when necessary.
		+
		+	[[Category:Metro]]

← Older revision		Revision as of 04:24, 28 November 2010
Line 196:		Line 196:
	nside <tt>foo</tt>. When Metro is in "lax" mode and a single-line variable is not defined, it is replaced with a dummy string, which will look something like a		nside <tt>foo</tt>. When Metro is in "lax" mode and a single-line variable is not defined, it is replaced with a dummy string, which will look something like a
	literal <tt>[BLANK var=varname]</tt>.		literal <tt>[BLANK var=varname]</tt>.
		+
		+	== Metro 1.2+ Extensions ==
		+
		+	Metro 1.2 has an extension which allows one to avoid using the coarse-grained <tt>[option parse/lax]</tt> annotation. Rather than using the <tt>[option parse/lax]</tt> and <tt>[option parse/strict]</tt> annotations to delimit variables that contain optionally undefined data, one can use the <tt>:lax</tt> suffix instead, to indicate that the parser should apply "lax" parsing rules when expanding that particular element. For example, the code in the section above could be written as follows in Metro 1.2:
		+
		+	<pre>foo: [
		+	#!/bin/bash
		+	if [ "$[path/mirror?]" = "yes" ]
		+	then
		+	echo "$[path/mirror:lax]"
		+	fi
		+	]</pre>
		+	This code will not throw an exception, even if <tt>path/mirror</tt> is not defined. In the case that <tt>path/mirror</tt> is not defined, <tt>$[path/mirror]</tt> will be replaced with a dummy value.
		+
		+	=== Using Strict Parsing ===
		+
		+	In general, it's recommended that you use strict parsing behavior whenever possible, as it will allow Metro to detect potential error conditions. Use <tt>[option parse/lax]</tt> and (with Metro 1.2+) the finer-grained <tt>:lax</tt> suffix to enable lax parsing behavior only when necessary.

← Older revision		Revision as of 04:24, 28 November 2010
Line 170:		Line 170:
	]</pre>		]</pre>
	Above, if <tt>portage/CFLAGS</tt> is defined, then the variable will expand to the value of <tt>portage/CFLAGS</tt>. However, if <tt>portage/CFLAGS</tt> is not defined, then the ''entire line'' will be omitted from the output.		Above, if <tt>portage/CFLAGS</tt> is defined, then the variable will expand to the value of <tt>portage/CFLAGS</tt>. However, if <tt>portage/CFLAGS</tt> is not defined, then the ''entire line'' will be omitted from the output.
		+
		+	== Controlling Parser Behavior ==
		+
		+	Normally, the following code would cause the parser to throw an exception if <tt>path/mirror</tt> were undefined:
		+
		+	<pre>foo: [
		+	#!/bin/bash
		+	if [ "$[path/mirror?]" = "yes" ]
		+	then echo "$[path/mirror]"fi
		+	]</pre>
		+	The first variable expansion, <tt>$[path/mirror?]</tt>, would not throw an exception if <tt>path/mirror</tt> was not defined - instead, the variable would expand to <tt>n
		+	o</tt>. However, on the second expansion, <tt>$[path/mirror]</tt>, Metro will abort with an error because the variable has not been defined. In the above code, this is pr
		+	obably not what you want, so we can temporarily put Metro's parser into "lax" mode as follows:
		+
		+	<pre>[option parse/lax]
		+
		+	foo: [
		+	#!/bin/bash
		+	if [ "$[path/mirror?]" = "yes" ]
		+	then
		+	echo "$[path/mirror]"
		+	fi]
		+	[option parse/strict]</pre>
		+	The <tt>[option parse/lax]</tt> and <tt>[option parse/strict]</tt> annotations will temporarily enable "lax" parsing mode when expanding the variables defined i
		+	nside <tt>foo</tt>. When Metro is in "lax" mode and a single-line variable is not defined, it is replaced with a dummy string, which will look something like a
		+	literal <tt>[BLANK var=varname]</tt>.

← Older revision		Revision as of 04:23, 28 November 2010
Line 150:		Line 150:
	]</pre>		]</pre>
	In the above example, the <tt>$[packages]</tt> reference will expand to the single-line value <tt>sys-apps/portage sys-devel/gcc dev-util/git</tt>.		In the above example, the <tt>$[packages]</tt> reference will expand to the single-line value <tt>sys-apps/portage sys-devel/gcc dev-util/git</tt>.
		+
		+	== Special Variable Expansion ==
		+
		+	As of Metro 1.1, Metro's template engine has a few new features related to variable expansion. The first is the ability to expand a single-line variable using a <tt>?</tt>, as follows:
		+
		+	<pre>foo: [
		+	#!/bin/bash
		+	if [ "$[path/mirror?]" = "yes" ]
		+	then
		+	echo "path/mirror is defined"
		+	fi
		+	]</pre>
		+	With a trailing <tt>?</tt>, a single-line variable will evaluate to a literal <tt>yes</tt> if it is defined, and a literal <tt>no</tt> if it is not defined.
		+
		+	Another special variable expansion uses a trailing <tt>:zap</tt> suffix for any single-line variable, and is used as follows:
		+
		+	<pre>foo: [
		+	CFLAGS=$[portage/CFLAGS:zap]
		+	]</pre>
		+	Above, if <tt>portage/CFLAGS</tt> is defined, then the variable will expand to the value of <tt>portage/CFLAGS</tt>. However, if <tt>portage/CFLAGS</tt> is not defined, then the ''entire line'' will be omitted from the output.

← Older revision		Revision as of 04:22, 28 November 2010
Line 134:		Line 134:

	In contrast, single line element references will always be expanded wherever they are found in the multi-line element, even if they are "commented out" in the script.		In contrast, single line element references will always be expanded wherever they are found in the multi-line element, even if they are "commented out" in the script.
		+
		+
		+	=== Multi-Line Element as Single-Line References ===
		+
		+	In Metro 1.3.1, it is possible to reference a multi-line element using the standard "<tt>$[ ]</tt>" reference. When this is done, the multi-line element is transformed into a single-line element by concatenating lines together, separated by whitespace. This allows multi-line elements to be used to define single-line data, as follows:
		+
		+	<pre>packages: [
		+	sys-apps/portage
		+	sys-devel/gcc
		+	dev-util/git
		+	]
		+
		+	myscript: [
		+	emerge -C $[packages]
		+	]</pre>
		+	In the above example, the <tt>$[packages]</tt> reference will expand to the single-line value <tt>sys-apps/portage sys-devel/gcc dev-util/git</tt>.

← Older revision		Revision as of 04:22, 28 November 2010
Line 121:		Line 121:
	echo Hi There :)		echo Hi There :)
	]</pre>		]</pre>
		+
		+	=== Commenting out Multi-Line Element References ===
		+
		+	If you want to disable a multi-line reference, simply prefix it with some text, such as <tt>#</tt>:
		+
		+	<pre>myscript: [
		+	#!/bin/bash
		+	# disabling this for now: $[[steps/setup]]
		+	echo Hi There :)
		+	]</pre>
		+	This comes in handy when you are commenting out a portion of code. If the multi-line reference has any non-whitespace text on the same line, then it will not be expanded and will be passed to the output as literal text.
		+
		+	In contrast, single line element references will always be expanded wherever they are found in the multi-line element, even if they are "commented out" in the script.