Target Language Compiler

Modify read-guide.tlc

Now that you have studied read-guide.tlc, it's time to get under the hood and tinker with it. In this hands-on exercise, we introduce two important TLC facilities, file control and scoping control. Your challenge is to implement both within the read-guide.tlc script.

File Control Basics

TLC scripts almost invariably produce output in the form of streams of characters. Outputs are normally directed to one or more buffers and files (a buffer is a volatile file stored in RAM), collectively called streams. So far, output from read-guide.tlc has been directed to the MATLAB command window, because you told it to do so by including the -v switch on the command line. Prove this by omitting -v when you run read-guide.tlc. Type

• tlc -r guide.rtw read-guide.tlc
  

Nothing appears to happen. In fact, the script was executed, but all output was directed to a null device (sometimes called the "bit bucket").

There is always one active output file, even if it is null. To specify, open, and close files, use the following TLC directives:

• %openfile streamid [="filename"] [, mode]
  %closefile streamid
  %selectfile streamid
  

If no filename is given, subsequent output flows to the memory buffer named by streamid. If no mode is specified, the file is opened for writing, and any existing content in it will be deleted (subject to system-level file protection mechanisms). Valid mode identifiers are "a" (append), "r" (readonly, seldom used) and "w" (write, the default). Enclose these characters in quotes.

The %openfile directive creates a file/buffer (in "w" mode), or opens an existing one (in "a" or "r" mode). Note required equals sign for file specification. Any number of streams can be open for writing, but only one can be active at one time. To switch output streams, use the %selectfile directive. Open files do not need to be closed until you are done with them.

The default output stream (which you can respecify with streamid NULL_FILE) is null. Another built-in stream is STDOUT. When activated using %selectfile, STDOUT directs output to the MATLAB command window.

Note    The streams NULL_FILE and STDOUT are always open. Specifying them with %openfile generate errors. Use %selectfile to activate them.

The directive %closefile closes the current output file or buffer. Until an %openfile or a %selectfile directive is encountered, output will go to the previously opened stream (or, if none exists, to null). Use %selectfile to designate an open stream for reading or writing. In practice, many TLC scripts write pieces of output data to separate buffers, which are then selected in a sequence and their contents spooled to one or more files.

File When Ready

In your working /guide directory is a file called read-guide-file-src.tlc, a version of read-guide.tlc with comments and three lines of text added. Edit this file to implement output file control, as follows:

1. Open read-guide-file-src.tlc in your text editor.
2. Note five comment lines that commence with "%% ->".

1. Under each of these comments, insert a TLC directive as indicated.

3. Save the edited file as read-guide-file.tlc.
4. Execute read-guide-file.tlc with the following command:

• tlc -r guide.rtw read-guide-file.tlc
  

1. If you succeeded, a file called guidetext.txt will be created containing the expected output, and the command window will display:

   • *** Output being directed to file: guidetext.txt
     *** We're almost done . . .
     *** Processing completed.
     

If you did not see these messages, or if no text file was produced, review the material and try again. If problems persist, inspect read-guide-file.tlc in the /solutions subdirectory to see how you should have specified file control.

The Scoop on Scopes

The Structure of Record Files explained the hierarchical organization of records. Each record exists within a scope defined by the record(s) in which it is nested. Our example file, guide.rtw, contains the following scopes:

• Top
  Top.Employee
  Top.Project[0]
  Top.Project[1]
  Top.Project[2]
  

To refer to a field or a record, it is normally necessary to specify its scoping, even if there is no other context that contains the identifier. For example, in guide.rtw the field FirstName exists only in the scope Top.Employee, yet it must be referred to as Top.Employee.FirstName whenever it is accessed.

When models present scopes that are deeply nested, this can lead to extremely long identifiers that are tedious and error prone to type. For example,

• CompiledModel.BlockOutputs.BlockOutput.ReusedBlockOutput
  

is a scope in the f14a.rtw file used in a later exercise.

The %with / %endwith directive eases the burden of correctly coding TLC scripts and to clarify their flow of control. Syntax is

• %with RecordName
    [TLC statements]
  %endwith
  

Every %with is eventually followed by an %endwith, and these pairs may be nested (but not overlapping). If RecordName is below the top level, the top-level scope need not be included in its description. For example, to make the current scope of a model.rtw file CompiledModel.DataTypes, you can specify

• %with DataTypes
    [TLC statements]
  %endwith
  

Naturally, "%with CompiledModel.DataTypes is also valid syntax. Once bracketed by %with / %endwith, record identifiers in TLC statements no longer require their outer scope to be specified. However, two conditions should be noted:

• Records outside of the current %with scope can be accessed, but must be fully qualified, as usual.
• Whenever assignments to records are made inside a %with directive (i.e., they are produced as lvalues), their names must be fully qualified.

Get %with It

In the last segment of this exercise, you modify the TLC script by adding a %with / %endwith directive. You also need to edit record identifier names (but not those of local variables) to account for the changes of scope resulting from the %with directives:

1. Open the TLC script read-guide-scope-src.tlc in your text editor.
2. Note comment lines that commence with "%% ->".

1. Under each of these comments, insert a TLC directive or modify statements already present, as indicated.

3. Save the edited file as read-guide-scope.tlc.
4. Execute read-guide-scope.tlc with the following command:

• tlc -v -r guide.rtw read-guide-scope.tlc
  

The output should be exactly the same as from read-guide.tlc, except possibly for white space that you may have introduced by indenting sections of code inside %with / %endwith or by eliminating blank lines.

Note that fully specifying a scope inside a %with context is not an error, it is simply unnecessary. However, failing to fully specify its scope when assigning to a record (for example, %assign GrossRate = wageCost) is illegal.

If errors result from running the script, review the discussion of scoping above and re-edit read-guide-scope.tlc to eliminate them. As a last resort, inspect read-guide-scope.tlc in the /solutions subdirectory to see how you should have handled scoping in this exercise.

The next exercise, Processing model.rtw Files with TLC Scripts,also uses %with ... %endwith scoping, in the context of processing an actual model.rtw file.

For additional information, see Using Scopes in the model.rtw File and Variable Scoping in this document.

Anatomy of a TLC Script

Processing model.rtw Files with TLC Scripts