HOWTO - Editing Freetext
Macrocoder literal strings, as it happens in most programming languages, are subject to some syntax rules: they must be enclosed in quotation marks and be subject to escape characters. For example, the string My C:\ directory is on a 3.5" disk must be expressed as "My C:\\ directory is on a 3.5\" disk" (the extra characters are evidenced).
This is quite annoying in code generation, because it forces to review and edit the sample code that has to be written by the code generator instead of simply copying and pasting it.
Macrocoder overcomes this problem by introducing a new type of string called freetext. Unlike standard strings, that are delimited by a pair of explicit ASCII characters, the quotation marks, the freetext string is delimited by an internal invisible marker. The editor delimits each freetext string by coloring its background: inside, any character can be written without any escaping.
To enter text in the freetext mode just press the freetext icon, as shown in the picture below, or press F9; to restore the normal text (called code mode), press the "code" icon (see picture below) or press F10.
Text blocks
One of the most common issues in macrocoding is the need to handle a multi-line, indented block of text. The example below shows the output of a complete html page:
Note how host language (FCL) indentation is harmonized with the target output indentation (HTML). The entire "yellow block" is nicely indented a couple of clicks inside the function to enhance readability; then, the yellow block has inside its own indentation.
In the following code, the output HTML text has been split in order to have a fixed header (lines 5-10), a variable body (lines 14 and 19) and again a fixed footer (lines 23-24):
Tabs and newlines
The freetext blocks may contain tabs and newlines that will be printed on the output stream. In order to see these normally invisible characters, toggle the Show control characters feature by clicking on the related menu entry (see picture below) or by using the shortcut CTRL+K:
With this feature enabled, the tab characters are shown as » and the new lines are shown as ¶.
Pasting an entire freetext block
Macrocoder allows pasting an entire block of clipboard text as freetext. This feature is very useful when copying the output code from a previously tested template.
- copy the desired text from any program into the clipboard;
- place the cursor in the position you want the text to be pasted 1;
- the cursor indent will be taken as the reference indent for all the text block;
- make sure the indent has been created by mean of the TAB key and not with the spacebar; by revealing the hidden characters with CTRL+K, the tabs must appear marked with the » symbol;
- right-click on the cursor and select Paste as freetext 2;
- the text will be automatically pasted with the right indent 3;
Newlines
The newline is a special character that terminates a line in a Macrocoder file. As we have seen, when the hidden characters are revealed with CTRL+K, the newline is shown with the ¶ symbol.
When working with freetext strings, we must pay particular attention to embedded newlines. Let's take the following example:
The lines above produce all the same result on the output stream: the string "Hello world" followed by a newline.
- line 1 - this uses a standard string; the newline is obtained with the constant
endl, whose name (END of Line) has been borrowed by C++; - line 3 - this is identical to previous case, except for the string, that here is expressed with a freetext; the newline is still implemented with
endl; - lines 5 and 6 - in this case, the programmer pressed ENTER while freetext mode was still on; this produced a freetext string embedding a newline; immediately after, the programmer deactivated freetext mode (F10) and typed the final semicolon
;; the ¶ symbol at line 5 has been added for clarity, but il will appear, among all the other, only if CTRL-K "show hidden characters" has been toggled to on.
Guillemets «...» shortcut
In Macrocoder projects most of the text generation actions are done by invoking the << operator on a stream object. For example:
This syntax is inherited from C++ streams and it is quite self explanatory: the system().msg object (in this case it is the Macrocoder output window) will receive first the string Dear friend followed by the variable name then followed by the string , have a nice day!. Assuming that name is set to "John", the final effect would be to print Dear friend John, have a nice day!.
When using freetext the syntax is the same:
Macrocoder supports a more compact version of the << operator that enhances a bit readability when inserting variables into freetext code: the guillemets. In the Macrocoder engine the symbols « and » are defined as aliases of <<. Therefore, the code above can be written as:
The guillemets version is graphically less intrusive thus enhancing readability of freetext code with variable parts.
Inserting guillemets
To inserts guillemets use the icons in the tool bar (see image below) or press F12 to open the guillemet and shift-F12 to close it. Note that the open guillemet command switches the editor mode to code and inserts the open guillemet; the close guillemet command, instead, inserts the closed guillemet and switches the editor mode to freetext. In this way, when in the process of typing code in freetext mode, the insertion of a variable can be done by the sequence F12, variable name, shift-F12 without bothering with editor mode switching.
Types
The plain string, the one within quotations, is a String. Instead, the freetext string type is DecoString.