Format Directives

The format directives are described below:

Directive -- Argument Type -- Textual Format

The last format directive (%m) is specific to GwydionDylan. See the below examples for using some of the format directives.

Simple Example

Here we use three format directives to print the following message:

Hello, my name is Doug Auclair, and I'm 33 years old.

The code to generate the above message is:

format(*standard-output*, "Hello, my name is %s, and I'm %d years old.%c",
       "Doug Auclair", 33, '\n');

Note: sending the new-line character ('\n') works as expected on supported platforms, but some systems that require a "\r\n" or a "\n\r" pair for a new-line command may have problems. The preferred way to write the above code is:

format(*standard-output*, "Hello, my name is %s, and I'm %d years old.\n",
       "Doug Auclair", 33);

Examples Using the %m Directive

Below are two examples that use the %m directive (and others) to format messages for display.

Simple Example Using the %m Directive

Instead of feeding the (in some cases, troublesome) '\n' character to the %c directive, let us explicitly use the new-line (a function in the Streams library) in concert with the %m directive, like this:

format(*standard-output*, "Hello, my name is %s, and I'm %d years old.%m",
       "Doug Auclair", 33, new-line);

The above code produces the same output as the simple example given previously.

Interestingly, Dylan automatically converts '\n' characters in the control string to calls to new-line. (So, neither "%m" => new-line nor "%c" => '\n' mappings are necessary ... Dylan takes care of that).

Complex Example Using the %m Directive

Here we generate almost the same message, this time with a little more information (the current time in Washington D.C.) using the "%m" format directive. The new message is:

Hello, my name is Doug Auclair, and as of
now, November 17, 2000 09:28 PM, I'm 33 years old.

To get the above message, we must first create a function that manipulates a <decoded-time> (See the Section called The Time Module in Chapter 13 and the Section called The Time-IO Module in Chapter 13) as we desire for the output:

define function human-readable-time(stream :: <stream>,  
                                    time :: <decoded-time>)
 => ()
    format-time(stream, "%B %d, %Y %H:%M %p", time);
end function human-readable-time;

Then we use that function as an argument to the %m directive to produce the message:

format(*standard-output*, "Hello, my name is %s, and as of\n"
                          "now, %m, I'm %d years old\n",
       "Doug Auclair", 
       rcurry(human-readable-time, get-current-time(timezone: 5 * 3600)),

There are several things of note in the above example.

  • First, a short-hand for format(*standard-output*, ... is the format-out function found in the Section called The Format-Out Module in Chapter 6.

  • Second, two strings placed side-by-side (no commas) are concatenated, so

    format(*standard-output*, "%s " "was " "here.\n", "Doug");

    is the same as

    format(*standard-output*, "%s was here.\n", "Doug");
  • Third, rcurry is a function that takes a function and various arguments to create a new function. A description of it is available in the Dylan Reference Manual (page 349). In this case, rcurry takes the function we created (human-readable-time) and the result of get-current-time (a function in the Time module, that, here, sets the timezone to Z+5 (hours), or Eastern Standard Time) as an argument that creates a new function that expects a <stream> instance to do its work.

  • Fourth, note that in the control string I use '\n' characters. This is the preferred, and simplest, way to request a new-line.

With the above points in mind, one can use the %m directive to integrate complex stream manipulation with the format function.