language.sgml

ecos实时嵌入式操作系统

mentioning here. When the component framework generates a
configuration header file for a given package, by default it will use
a name derived from the package name (the &define-header; property can
be used to override this). The file name is constructed from the
package name by removing everything up to and including the first
underscore, converting the remainder of the name to lower case, and
appending a <literal>.h</literal> suffix. For example the kernel
package <varname>CYGPKG_KERNEL</varname> will involve a header file
<filename class="headerfile">pkgconf/kernel.h</filename>. If a
configuration contained some other package
<varname>XYZPKG_KERNEL</varname> then this would attempt to use the
same configuration header file, with unfortunate effects. Case
sensitivity could introduce problems as well, so a package
<varname>xyzpkg_kernel</varname> would involve the same problem. Even
if the header file names preserved the case of the package name, not
all file systems are case sensitive. There is no simple solution to
this problem. Changing the names of the generated configuration header
files would involve a major incompatible change to the interface, to
solve a problem which is essentially hypothetical in nature.
</para>

</sect1>

<!-- }}} -->
<!-- {{{ Introduction to Tcl    -->

<sect1 id="language.tcl">
<title>An Introduction to Tcl</title>

<para>
All &CDL; scripts are implemented as &Tcl; scripts, and are read in by
running the data through a standard &Tcl; interpreter, extended with a
small number of additional commands such as
<literal>cdl_option</literal> and <literal>cdl_component</literal>.
Often it is not necessary to know the full details of &Tcl; syntax.
Instead it is possible to copy an existing script, perform some copy
and paste operations, and make appropriate changes to names and to
various properties. However there are also cases where an
understanding of &Tcl; syntax is very desirable, for example:
</para>

<programlisting width=72>
cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
    display       "Externs for initialization"
    flavor        data
    default_value {"static char fpool1[ 2000 ], \\\n\
	                        fpool2[ 2000 ], \\\n\
	                        fpool3[ 2000 ];"}
    &hellip;
}
</programlisting>

<para>
This causes the &cdl-option; command to be executed, which in turn
evaluates its body in a recursive invocation of the &Tcl; interpreter.
When the &default-value; property is encountered the braces around the
value part are processed by the interpreter, stopping it from doing
further processing of the braced contents (except for backslash
processing at the end of a line, that is special). In particular it
prevents command substitution for
<literal>[&nbsp;2000&nbsp;]</literal>. A single argument will be
passed to the &default-value; command which expects a &CDL;
expression, so the expression parsing code is passed the following:
</para>

<screen width=72>
"static char fpool1[ 2000 ], \\\n fpool2[ 2000 ], \\\n fpool3[ 2000 ];"
</screen>

<para>
The &CDL; expression parsing code will treat this as a simple string
constant, as opposed to a more complicated expression involving other
options and various operators. The string parsing code will perform
the usual backslash substitutions so the actual default value will be:
</para>
<screen width=72>
static char fpool1[ 2000 ], \
 fpool2[ 2000 ], \
 fpool3[ 2000 ];
</screen>

<para>
If the user does not modify the option's value then the following
will be generated in the appropriate configuration header file:
</para>
<programlisting width=72>
#define CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS static char fpool1[ 2000 ], \
 fpool2[ 2000 ], \
 fpool3[ 2000 ];
</programlisting>

<para>
Getting this desired result usually requires an understanding of both
&Tcl; syntax and &CDL; expression syntax. Sometimes it is possible to
substitute a certain amount of trial and error instead, but this may
prove frustrating. It is also worth pointing out that many &CDL;
scripts do not involve this level of complexity. On the other hand,
some of the more advanced features of the &CDL; language involve
fragments of &Tcl; code, for example the &define-proc; property. To
use these component writers will need to know about the full &Tcl;
language as well as the syntax.
</para>
<para>
Although the current example may seem to suggest that &Tcl; is rather
complicated, it is actually a very simple yet powerful scripting
language: the syntax is defined by just eleven rules. On occasion this
simplicity means that Tcl's behavior is subtly different from other
languages, which can confuse newcomers.
</para>
<para>
When the Tcl interpreter is passed some data such as
<literal>puts&nbsp;Hello</literal>, it splits this data into a command
and its arguments. The command will be terminated by a newline or by a
semicolon, unless one of the quoting mechanisms is used. The command
and each of its arguments are separated by white space. So in the
following example:
</para>
<screen width=72>
puts Hello
set x 42
</screen>
<para>
This will result in two separate commands being executed. The first
command is <literal>puts</literal> and is passed a single argument,
<literal>Hello</literal>. The second command is <literal>set</literal>
and is passed two arguments, <literal>x</literal> and
<literal>42</literal>. The intervening newline character serves to
terminate the first command, and a semi-colon separator could be used
instead: 
</para>
<screen width=72>
puts Hello;set x 42
</screen>
<para>
Any white space surrounding the semicolon is just ignored because it
does not serve to separate arguments.
</para>
<para>
Now consider the following:
</para>
<screen width=72>
set x Hello world
</screen>
<para>
This is not valid &Tcl;. It is an attempt to invoke the
<literal>set</literal> command with three arguments:
<literal>x</literal>, <literal>Hello</literal>, and
<literal>world</literal>. The <literal>set</literal> only takes two
arguments, a variable name and a value, so it is necessary to combine
the data into a single argument by quoting:
</para>
<screen width=72>
set x "Hello world"
</screen>
<para>
When the &Tcl; interpreter encounters the first quote character it
treats all subsequent data up to but not including the closing quote
as part of the current argument. The quote marks are removed by the
interpreter, so the second argument passed to the
<literal>set</literal> command is just <literal>Hello world</literal>
without the quote characters. This can be significant in the context
of &CDL; scripts. For example:
</para>
<programlisting width=72>
cdl_option CYG_HAL_STARTUP {
    &hellip;
    default_value "RAM"
}
</programlisting>
<para>
The &Tcl; interpreter strips off the quote marks so the &CDL;
expression parsing code sees <literal>RAM</literal> instead of
<literal>"RAM"</literal>. It will treat this as a reference to
some unknown option <varname>RAM</varname> rather than as a string
constant, and the expression evaluation code will use a value of
<literal>0</literal> when it encounters an option that is not
currently loaded. Therefore the option
<varname>CYG_HAL_STARTUP</varname> ends up with a default value of
<literal>0</literal>. Either braces or backslashes should be used to
avoid this, for example
<literal>default_value&nbsp;{&nbsp;"RAM"&nbsp;}</literal>. 
</para>
<note>
<para>
There are long-term plans to implement some sort of &CDL; validation
utility <application class="software">cdllint</application> which
could catch common errors like this one.
</para>
</note>
<para>
A quoted argument continues until the closing quote character is
encountered, which means that it can span multiple lines. Newline or
semicolon characters do not terminate the current command in such
cases. &description; properties usually make use of this:
</para>
<programlisting width=72>
cdl_package CYGPKG_ERROR {
    description   "
        This package contains the common list of error and
        status codes. It is held centrally to allow
        packages to interchange error codes and status
        codes in a common way, rather than each package
        having its own conventions for error/status
        reporting. The error codes are modelled on the
        POSIX style naming e.g. EINVAL etc. This package
        also provides the standard strerror() function to
        convert error codes to textual representation."
    &hellip;
}
</programlisting>
<para>
The &Tcl; interpreter supports much the same forms of backslash
substitution as other common programming languages. Some backslash
sequences such as <literal>\n</literal> will be replaced by the
appropriate character. The sequence <literal>\\</literal> will be
replaced by a single backslash. A backslash at the very end of a line
will cause that backslash, the newline character, and any white space
at the start of the next line to be replaced by a single space. Hence
the following two Tcl commands are equivalent:
</para>
<programlisting width=72>
puts  "Hello\nworld\n"
puts \
"Hello
world
"
</programlisting>
<para>
If a &description; string needs to contain quote marks or other
special characters then backslash escapes can be used. In addition to
quote and backslash characters, the Tcl interpreter treats square
brackets, the <literal>$</literal> character, and braces specially.
Square brackets are used for command substitution, for example:
</para>
<screen width=72>
puts "The answer is [expr 6 * 9]"
</screen>
<para>
When the Tcl interpreter encounters the square brackets it will treat
the contents as another command that should be executed first, and the
result of executing that is used when continuing to process the
script. In this case the Tcl interpreter will execute the command
<literal>expr 6 * 9</literal>, yielding a result of 42
<footnote>
<para>
It is possible that some versions of the Tcl interpreter will instead
produce a result of 54 when asked to multiply six by nine. Appropriate
<ulink url="http://www.douglasadams.com/creations/hhgg.html">reference
documentation</ulink> should be consulted for more information on why
42 is in fact the correct answer.
</para>
</footnote>
and then the
Tcl interpreter will execute <literal>puts "The answer is 42"</literal>.
It should be noted that the interpreter performs only one level
of substitution: if the result of performing command substitution
performs further special characters such as square brackets then these
will not be treated specially.
</para>
<para>
Command substitution will not prove useful for many &CDL; scripts,
except for e.g. a &define-proc; property which involves a fragment of
&Tcl; code. Potentially there are some interesting uses, for example
to internationalize &display; strings. However care does have to be
taken to avoid unexpected command substitution, for example if an
option description involves square brackets then typically these would
require backslash-escapes.
</para>
<para>
The <literal>$</literal> character is used in Tcl scripts to perform
variable substitution:
</para>
<programlisting width=72>
set x [expr 6 * 9]
puts "The answer is $x"
</programlisting>
<para>
Variable substitution, like command substitution, is unlikely to
prove useful for many &CDL; scripts except in the context of
&Tcl; fragments. If it is necessary to have a <literal>$</literal>
character then a backslash escape may have to be used.
</para>
<para>
Braces are used to collect a sequence of characters into a single
argument, just like quotes. The difference is that variable, command
and backslash substitution do not occur inside braces (with the
sole exception of backslash substitution at the end of a line).
Therefore given a line in a &CDL; script such as:
</para>
<programlisting width=72>
default_value {"RAM"}
</programlisting>
<para>
The braces are stripped off by the &Tcl; interpreter, leaving
<literal>"RAM"</literal> which will be handled as a string constant by
the expression parsing code. The same effect could be achieved using
one of the following:
</para>
<programlisting width=72>
default_value \"RAM\"
default_value "\"RAM\""
</programlisting>
<para>
Generally the use of braces is less confusing. At this stage it is
worth noting that the basic format of &CDL; data makes use of
braces:
</para>
<programlisting width=72>
cdl_option &lt;name&gt; {
     &hellip;
};
</programlisting>
<para>
The &cdl-option; command is passed two arguments, a name and a body,
where the body consists of everything inside the braces but not the
braces themselves. This body can then be executed in a recursive
invocation of the &Tcl; interpreter. If a &CDL; script contains
mismatched braces then the interpreter is likely to get rather
confused and the resulting diagnostics may be difficult to understand. 
</para>
<para>
Comments in Tcl scripts are introduced by a hash character
<literal>#</literal>. However, a hash character only introduces a
comment if