doc/html/cdl-guide/ref.define-format.html

   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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >define_format</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="CDL Language Specification"
  23 HREF="reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="define"
  26 HREF="ref.define.html"><LINK
  27 REL="NEXT"
  28 TITLE="define_header"
  29 HREF="ref.define-header.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="ref.define.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 ></TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="ref.define-header.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><H1
  84 ><A
  85 NAME="REF.DEFINE-FORMAT"><SPAN
  86 CLASS="PROPERTY"
  87 >define_format</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4073"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >define_format</SPAN
  99 >&nbsp;--&nbsp;Control how an option's value will appear in the
 100 configuration header file.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN4077"><H2
 105 >Synopsis</H2
 106 ><TABLE
 107 BORDER="5"
 108 BGCOLOR="#E0E0F0"
 109 WIDTH="70%"
 110 ><TR
 111 ><TD
 112 ><PRE
 113 CLASS="SYNOPSIS"
 114 >cdl_option &lt;name&gt; {
 115     define_format &lt;format string&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN4079"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 130 >For active options with the <TT
 131 CLASS="LITERAL"
 132 >data</TT
 133 > flavor, and for
 134 active and enabled options with the <TT
 135 CLASS="LITERAL"
 136 >booldata</TT
 137 >
 138 flavor, the configuration tools will normally generate two
 139 <TT
 140 CLASS="LITERAL"
 141 >#define's</TT
 142 > in the package's configuration header
 143 file. These take the following forms:</P
 144 ><TABLE
 145 BORDER="5"
 146 BGCOLOR="#E0E0F0"
 147 WIDTH="70%"
 148 ><TR
 149 ><TD
 150 ><PRE
 151 CLASS="PROGRAMLISTING"
 152 >#define &lt;name&gt; &lt;value&gt;
 153 #define &lt;name&gt;_&lt;value&gt;</PRE
 154 ></TD
 155 ></TR
 156 ></TABLE
 157 ><P
 158 >The <SPAN
 159 CLASS="PROPERTY"
 160 >define_format</SPAN
 161 > property can be used to control exactly what
 162 appears as the value for the first of these
 163 <TT
 164 CLASS="LITERAL"
 165 >#define's</TT
 166 >. For example, the following can be used
 167 to output some configuration data as a C string:</P
 168 ><TABLE
 169 BORDER="5"
 170 BGCOLOR="#E0E0F0"
 171 WIDTH="70%"
 172 ><TR
 173 ><TD
 174 ><PRE
 175 CLASS="PROGRAMLISTING"
 176 >cdl_option &lt;name&gt; {
 177     &#8230;
 178     define -format="\\\"%s\\\"" &lt;symbol&gt;
 179 }</PRE
 180 ></TD
 181 ></TR
 182 ></TABLE
 183 ><P
 184 >The implementation of <SPAN
 185 CLASS="PROPERTY"
 186 >define_format</SPAN
 187 > involves concatenating the Tcl
 188 command <TT
 189 CLASS="LITERAL"
 190 >format</TT
 191 >, the format string, and the string
 192 representation of the option's value, and evaluating this in a Tcl
 193 interpreter. Therefore the format string will be processed twice by a
 194 Tcl parser, and appropriate care has to be taken with quoting.</P
 195 ><P
 196 >The second <TT
 197 CLASS="LITERAL"
 198 >#define</TT
 199 > will be generated only if is a
 200 valid C preprocessor macro symbol, and is not affected by the
 201 <SPAN
 202 CLASS="PROPERTY"
 203 >define_format</SPAN
 204 > property. Also, the property is only relevant for
 205 options with the <TT
 206 CLASS="LITERAL"
 207 >data</TT
 208 > or
 209 <TT
 210 CLASS="LITERAL"
 211 >booldata</TT
 212 > flavor, and cannot be used in
 213 conjunction with the <SPAN
 214 CLASS="PROPERTY"
 215 >no_define</SPAN
 216 > property since it makes no sense to
 217 specify the format if no <TT
 218 CLASS="LITERAL"
 219 >#define</TT
 220 > is generated.</P
 221 ><DIV
 222 CLASS="CAUTION"
 223 ><P
 224 ></P
 225 ><TABLE
 226 CLASS="CAUTION"
 227 BORDER="1"
 228 WIDTH="100%"
 229 ><TR
 230 ><TD
 231 ALIGN="CENTER"
 232 ><B
 233 >Caution</B
 234 ></TD
 235 ></TR
 236 ><TR
 237 ><TD
 238 ALIGN="LEFT"
 239 ><P
 240 >Because the Tcl interpreter's <TT
 241 CLASS="LITERAL"
 242 >format</TT
 243 > command is
 244 used, this property is subject to any problems with the implementation
 245 of this in the Tcl library. Generally there should be no problems with
 246 string data or with integers up to 32 bits, but there may well be
 247 problems if 64-bit data is involved. This issue may be addressed in a
 248 future release.</P
 249 ></TD
 250 ></TR
 251 ></TABLE
 252 ></DIV
 253 ></DIV
 254 ><DIV
 255 CLASS="REFSECT1"
 256 ><A
 257 NAME="AEN4103"
 258 ></A
 259 ><H2
 260 >Example</H2
 261 ><TABLE
 262 BORDER="5"
 263 BGCOLOR="#E0E0F0"
 264 WIDTH="70%"
 265 ><TR
 266 ><TD
 267 ><PRE
 268 CLASS="PROGRAMLISTING"
 269 >cdl_option CYGNUM_UITRON_VER_ID     {
 270     display       "OS identification"
 271     flavor        data
 272     legal_values  0 to 0xFFFF
 273     default_value 0
 274     define_format "0x%04x"
 275     description   "
 276         This value is returned in the 'id'
 277         field of the T_VER structure in
 278         response to a get_ver() system call."
 279 }</PRE
 280 ></TD
 281 ></TR
 282 ></TABLE
 283 ></DIV
 284 ><DIV
 285 CLASS="REFSECT1"
 286 ><A
 287 NAME="AEN4106"
 288 ></A
 289 ><H2
 290 >See Also</H2
 291 ><P
 292 >Properties <A
 293 HREF="ref.define.html"
 294 ><SPAN
 295 CLASS="PROPERTY"
 296 >define</SPAN
 297 ></A
 298 >,
 299 <A
 300 HREF="ref.define-header.html"
 301 ><SPAN
 302 CLASS="PROPERTY"
 303 >define_header</SPAN
 304 ></A
 305 >,
 306 <A
 307 HREF="ref.define-proc.html"
 308 ><SPAN
 309 CLASS="PROPERTY"
 310 >define_proc</SPAN
 311 ></A
 312 >,
 313 <A
 314 HREF="ref.if-define.html"
 315 ><SPAN
 316 CLASS="PROPERTY"
 317 >if_define</SPAN
 318 ></A
 319 > and
 320 <A
 321 HREF="ref.no-define.html"
 322 ><SPAN
 323 CLASS="PROPERTY"
 324 >no_define</SPAN
 325 ></A
 326 >.</P
 327 ></DIV
 328 ><DIV
 329 CLASS="NAVFOOTER"
 330 ><HR
 331 ALIGN="LEFT"
 332 WIDTH="100%"><TABLE
 333 SUMMARY="Footer navigation table"
 334 WIDTH="100%"
 335 BORDER="0"
 336 CELLPADDING="0"
 337 CELLSPACING="0"
 338 ><TR
 339 ><TD
 340 WIDTH="33%"
 341 ALIGN="left"
 342 VALIGN="top"
 343 ><A
 344 HREF="ref.define.html"
 345 ACCESSKEY="P"
 346 >Prev</A
 347 ></TD
 348 ><TD
 349 WIDTH="34%"
 350 ALIGN="center"
 351 VALIGN="top"
 352 ><A
 353 HREF="cdl-guide.html"
 354 ACCESSKEY="H"
 355 >Home</A
 356 ></TD
 357 ><TD
 358 WIDTH="33%"
 359 ALIGN="right"
 360 VALIGN="top"
 361 ><A
 362 HREF="ref.define-header.html"
 363 ACCESSKEY="N"
 364 >Next</A
 365 ></TD
 366 ></TR
 367 ><TR
 368 ><TD
 369 WIDTH="33%"
 370 ALIGN="left"
 371 VALIGN="top"
 372 ><SPAN
 373 CLASS="PROPERTY"
 374 >define</SPAN
 375 ></TD
 376 ><TD
 377 WIDTH="34%"
 378 ALIGN="center"
 379 VALIGN="top"
 380 ><A
 381 HREF="reference.html"
 382 ACCESSKEY="U"
 383 >Up</A
 384 ></TD
 385 ><TD
 386 WIDTH="33%"
 387 ALIGN="right"
 388 VALIGN="top"
 389 ><SPAN
 390 CLASS="PROPERTY"
 391 >define_header</SPAN
 392 ></TD
 393 ></TR
 394 ></TABLE
 395 ></DIV
 396 ></BODY
 397 ></HTML
 398 >