1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >An Introduction to Tcl</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="The CDL Language"
23 HREF="language.html"><LINK
25 TITLE="Option Naming Convention"
26 HREF="language.naming.html"><LINK
28 TITLE="Values and Expressions"
29 HREF="language.values.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="language.naming.html"
68 >Chapter 3. The CDL Language</TD
74 HREF="language.values.html"
88 NAME="LANGUAGE.TCL">An Introduction to Tcl</H1
93 > scripts are implemented as <SPAN
96 > scripts, and are read in by
97 running the data through a standard <SPAN
100 > interpreter, extended with a
101 small number of additional commands such as
109 Often it is not necessary to know the full details of <SPAN
113 Instead it is possible to copy an existing script, perform some copy
114 and paste operations, and make appropriate changes to names and to
115 various properties. However there are also cases where an
116 understanding of <SPAN
119 > syntax is very desirable, for example:</P
127 CLASS="PROGRAMLISTING"
128 >cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
129 display "Externs for initialization"
131 default_value {"static char fpool1[ 2000 ], \\\n\
132 fpool2[ 2000 ], \\\n\
143 > command to be executed, which in turn
144 evaluates its body in a recursive invocation of the <SPAN
151 > property is encountered the braces around the
152 value part are processed by the interpreter, stopping it from doing
153 further processing of the braced contents (except for backslash
154 processing at the end of a line, that is special). In particular it
155 prevents command substitution for
158 >[ 2000 ]</TT
159 >. A single argument will be
163 > command which expects a <SPAN
167 expression, so the expression parsing code is passed the following:</P
176 >"static char fpool1[ 2000 ], \\\n fpool2[ 2000 ], \\\n fpool3[ 2000 ];"</PRE
184 > expression parsing code will treat this as a simple string
185 constant, as opposed to a more complicated expression involving other
186 options and various operators. The string parsing code will perform
187 the usual backslash substitutions so the actual default value will be:</P
196 >static char fpool1[ 2000 ], \
203 >If the user does not modify the option's value then the following
204 will be generated in the appropriate configuration header file:</P
212 CLASS="PROGRAMLISTING"
213 >#define CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS static char fpool1[ 2000 ], \
220 >Getting this desired result usually requires an understanding of both
227 > expression syntax. Sometimes it is possible to
228 substitute a certain amount of trial and error instead, but this may
229 prove frustrating. It is also worth pointing out that many <SPAN
233 scripts do not involve this level of complexity. On the other hand,
234 some of the more advanced features of the <SPAN
241 > code, for example the <SPAN
245 use these component writers will need to know about the full <SPAN
249 language as well as the syntax.</P
251 >Although the current example may seem to suggest that <SPAN
255 complicated, it is actually a very simple yet powerful scripting
256 language: the syntax is defined by just eleven rules. On occasion this
257 simplicity means that Tcl's behavior is subtly different from other
258 languages, which can confuse newcomers.</P
260 >When the Tcl interpreter is passed some data such as
264 >, it splits this data into a command
265 and its arguments. The command will be terminated by a newline or by a
266 semicolon, unless one of the quoting mechanisms is used. The command
267 and each of its arguments are separated by white space. So in the
268 following example:</P
283 >This will result in two separate commands being executed. The first
287 > and is passed a single argument,
291 >. The second command is <TT
295 and is passed two arguments, <TT
302 >. The intervening newline character serves to
303 terminate the first command, and a semi-colon separator could be used
313 >puts Hello;set x 42</PRE
318 >Any white space surrounding the semicolon is just ignored because it
319 does not serve to separate arguments.</P
321 >Now consider the following:</P
330 >set x Hello world</PRE
335 >This is not valid <SPAN
338 >. It is an attempt to invoke the
342 > command with three arguments:
357 arguments, a variable name and a value, so it is necessary to combine
358 the data into a single argument by quoting:</P
367 >set x "Hello world"</PRE
375 > interpreter encounters the first quote character it
376 treats all subsequent data up to but not including the closing quote
377 as part of the current argument. The quote marks are removed by the
378 interpreter, so the second argument passed to the
382 > command is just <TT
386 without the quote characters. This can be significant in the context
390 > scripts. For example:</P
398 CLASS="PROGRAMLISTING"
399 >cdl_option CYG_HAL_STARTUP {
410 > interpreter strips off the quote marks so the <SPAN
414 expression parsing code sees <TT
421 >. It will treat this as a reference to
422 some unknown option <TT
425 > rather than as a string
426 constant, and the expression evaluation code will use a value of
430 > when it encounters an option that is not
431 currently loaded. Therefore the option
435 > ends up with a default value of
439 >. Either braces or backslashes should be used to
440 avoid this, for example
443 >default_value { "RAM" }</TT
452 >There are long-term plans to implement some sort of <SPAN
460 could catch common errors like this one.</P
464 >A quoted argument continues until the closing quote character is
465 encountered, which means that it can span multiple lines. Newline or
466 semicolon characters do not terminate the current command in such
470 > properties usually make use of this:</P
478 CLASS="PROGRAMLISTING"
479 >cdl_package CYGPKG_ERROR {
481 This package contains the common list of error and
482 status codes. It is held centrally to allow
483 packages to interchange error codes and status
484 codes in a common way, rather than each package
485 having its own conventions for error/status
486 reporting. The error codes are modelled on the
487 POSIX style naming e.g. EINVAL etc. This package
488 also provides the standard strerror() function to
489 convert error codes to textual representation."
499 > interpreter supports much the same forms of backslash
500 substitution as other common programming languages. Some backslash
501 sequences such as <TT
504 > will be replaced by the
505 appropriate character. The sequence <TT
509 replaced by a single backslash. A backslash at the very end of a line
510 will cause that backslash, the newline character, and any white space
511 at the start of the next line to be replaced by a single space. Hence
512 the following two Tcl commands are equivalent:</P
520 CLASS="PROGRAMLISTING"
521 >puts "Hello\nworld\n"
533 > string needs to contain quote marks or other
534 special characters then backslash escapes can be used. In addition to
535 quote and backslash characters, the Tcl interpreter treats square
539 > character, and braces specially.
540 Square brackets are used for command substitution, for example:</P
549 >puts "The answer is [expr 6 * 9]"</PRE
554 >When the Tcl interpreter encounters the square brackets it will treat
555 the contents as another command that should be executed first, and the
556 result of executing that is used when continuing to process the
557 script. In this case the Tcl interpreter will execute the command
561 >, yielding a result of 42
568 Tcl interpreter will execute <TT
570 >puts "The answer is 42"</TT
572 It should be noted that the interpreter performs only one level
573 of substitution: if the result of performing command substitution
574 performs further special characters such as square brackets then these
575 will not be treated specially.</P
577 >Command substitution will not prove useful for many <SPAN
581 except for e.g. a <SPAN
584 > property which involves a fragment of
588 > code. Potentially there are some interesting uses, for example
589 to internationalize <SPAN
592 > strings. However care does have to be
593 taken to avoid unexpected command substitution, for example if an
594 option description involves square brackets then typically these would
595 require backslash-escapes.</P
600 > character is used in Tcl scripts to perform
601 variable substitution:</P
609 CLASS="PROGRAMLISTING"
611 puts "The answer is $x"</PRE
616 >Variable substitution, like command substitution, is unlikely to
617 prove useful for many <SPAN
620 > scripts except in the context of
624 > fragments. If it is necessary to have a <TT
628 character then a backslash escape may have to be used.</P
630 >Braces are used to collect a sequence of characters into a single
631 argument, just like quotes. The difference is that variable, command
632 and backslash substitution do not occur inside braces (with the
633 sole exception of backslash substitution at the end of a line).
634 Therefore given a line in a <SPAN
645 CLASS="PROGRAMLISTING"
646 >default_value {"RAM"}</PRE
651 >The braces are stripped off by the <SPAN
654 > interpreter, leaving
658 > which will be handled as a string constant by
659 the expression parsing code. The same effect could be achieved using
660 one of the following:</P
668 CLASS="PROGRAMLISTING"
669 >default_value \"RAM\"
670 default_value "\"RAM\""</PRE
675 >Generally the use of braces is less confusing. At this stage it is
676 worth noting that the basic format of <SPAN
688 CLASS="PROGRAMLISTING"
689 >cdl_option <name> {
699 > command is passed two arguments, a name and a body,
700 where the body consists of everything inside the braces but not the
701 braces themselves. This body can then be executed in a recursive
702 invocation of the <SPAN
705 > interpreter. If a <SPAN
709 mismatched braces then the interpreter is likely to get rather
710 confused and the resulting diagnostics may be difficult to understand. </P
712 >Comments in Tcl scripts are introduced by a hash character
716 >. However, a hash character only introduces a
717 comment if it occurs where a command is expected. Consider the
726 CLASS="PROGRAMLISTING"
728 puts "Hello" # world</PRE
733 >The first line is a valid comment, since the hash character occurs
734 right at the start where a command name is expected. The second line
735 does not contain a comment. Instead it is an attempt to invoke the
739 > command with three arguments:
750 >. These are not valid arguments for the
754 > command so an error will be raised.
755 If the second line was rewritten as:</P
763 CLASS="PROGRAMLISTING"
764 >puts "Hello"; # world</PRE
769 >then this is a valid Tcl script. The semicolon identifies the end of
770 the current command, so the hash character occurs at a point where the
771 next command would start and hence it is interpreted as the start of a
774 >This handling of comments can lead to subtle behavior. Consider the
783 CLASS="PROGRAMLISTING"
784 >cdl_option WHATEVER {
785 # This is a comment }
793 >Consider the way the Tcl interpreter processes this. The command name
794 and the first argument do not pose any special difficulties. The
795 opening brace is interpreted as the start of the next argument, which
796 continues until a closing brace is encountered. In this case the
797 closing brace occurs on the second line, so the second argument passed
804 >\n # This is a comment</TT
805 >. This second argument is processed in a recursive
806 invocation of the Tcl interpreter and does not contain any commands,
807 just a comment. Top-level script processing then resumes, and the next
808 command that is encountered is <TT
812 the parser is not currently processing a configuration option this is
813 an error. Later on the Tcl interpreter would encounter a closing brace
814 by itself, which is also an error.</P
816 >For component writers who need more information about <SPAN
820 especially about the language rather than the syntax, various
821 resources are available. A reasonable starting point is the
823 HREF="http://www.tcl.tk/scripting/"
843 HREF="language.tcl.html#AEN1270"
851 >It is possible that some versions of the Tcl interpreter will instead
852 produce a result of 54 when asked to multiply six by nine. Appropriate
854 HREF="http://www.douglasadams.com/creations/hhgg.html"
858 > should be consulted for more information on why
859 42 is in fact the correct answer.</P
868 SUMMARY="Footer navigation table"
879 HREF="language.naming.html"
888 HREF="cdl-guide.html"
897 HREF="language.values.html"
907 >Option Naming Convention</TD
921 >Values and Expressions</TD
projects / karo-tx-redboot.git / blob