Previous: Embedding Charts, Up: Command-Line Referece [Contents]
The options here are inteded for integration with text editors. They may change in the future. Please contact the author if you want to integrate with a text editor.
Using --tei-mode will put msc-gen into Text Editor Integration mode, where it expects a series of input files on its standard input and produces color syntax highlighting, quick error, text indentation or hints/autocomplete information on the standard output. These are produced via a quick parsing of the input text and are intended to be fast enough to be ran for every keystroke pressed. (At least for input files of reasonable sizes, say 64K.) Parsing in this mode is limited, thus not all errors are caught, but most are. Msc-gen reads and parses all the design libraries at startup and remains running for several input files - again to save time. (Reading design files can be avoided via option --nodesigns, as usual.)
On the standard input msc-gen expects a text line with a series of space separated letters, each optionally followed by a number, then a new line character. After this shall come the text of an input chart, terminated by a zero byte. The letter in the first line determines what kind of output is expected on the standard output (see below). The output is also terminated by a zero byte. All the above can then be repeated until the standard input is closed. In that case, msc-gen closes the standard output and exits with success.
Msc-gen uses the standard error to produce critical error messages (ones that do not pertrain to the correctness of input text, such as bad combination of options, etc.).
The type of the chart has to be specified via option -S and cannot be changed later. (Similar, if the design libraries change, msc-gen need to be restarted.) The text of the input can only be ASCII or UTF-8, but not UTF-16. Input or output filenames are invalid, so are the options -i and -o. A host of other options to manipulate graphics output (sizing, pagination, etc.) are simply ignored.
The following table summarizes, what letters can be used in the first line of the input
and what effect they have.
If you specify more than one letters in the first line separated by spaces, all output
for them will be returned separated by an empty line. Thus if you want to get both the coloring
information and the quick errors in one pass, use C E
in the first line. The order of the
letters in the first line do not matter, output is ordered as below in the table. You can specify
one letter several times, but it has no effect. In case the letter requires parameters, that of
the last mention will take effect.
C
In response to C
, msc-gen emits a description of how to color the input.
Each line describes a particular contigius area of the input file colored the
same way in the format below.
<first_pos>-<last_pos>: <color_id> <red> <green> <blue> <bold> <italics> <underline>
The first two numbers mark the first and the last position of the color range starting from 1. If the color range consists of a single character, the two values are equal. In case of UTF-8 encoding, multi-byte characters are counted as one thus the position is not a byte index. The different line endings (CR, LF or CRLF) are all understood, with CRLF counted as one character.
The color_id
is a number between 0 and 36 denoting what kind of
color do we talk about. The table further below summarizes the values. The rest of the numbers
on the line give actual colors and font flags (associated with the default color scheme).
D<pos>,<insert>
Similar to C
, this emits coloring information, but only a delta compared to a previous run.
This may be beneficial to reduce the amount of coloring results generated by msc-gen. Also, if the
text editor supports incremental updates in coloring, this may also reduce the work of updating coloring
after simple changes.
The delta can only be compared if a single (but perhaps multi-character) insertion or deletion were
made to the input file. <pos>
represents the caret position after which the characters
were inserted or deleted, while <insert>
tells us how many were inserted (negative number for deletes).
If you have specified the N
letter, you can omit the chart text entirely from after the first line
for deletions. For insertions, you just need to specify the characters inserted (which have to be as many)
as the <insert>
you specified.
By default (no N
added), msc-gen still expects the full chart text on its input.
If the chart text given to msc-gen was modified
in a different way compared to the original than the parameters of the D
command indicate the
resulting delta will likely be wrong. The returned coloring info will contain color_id
of 0
for texts that were colored before, but now coloring has to be removed.
Note that the delta computation algorithm assumes that the text editor maintains coloring before <pos>
and shifts coloring information after the insertion. That is, if a single character was deleted at position
5
, a blue colored character at position 3
will remain blue (and hence this can be omitted
from the delta) and a red character originally at position 7
(now at position 6
) will remain
red at its new position. This is how any sane text editor having text formatting shall work.
You can only specify one of C
or D
at the line, the latter takes effect.
E
Msc-gen will emit quick errors, for highlighting during editing.
(Not all errors are caputred, such as attributes not applying, etc.
This is to speed up the process.)
The output contains a character range <first_pos>-<last-pos>
followed by
a textual description. The text editor may underline these locations and assign ballon tooltips
for them.
H<pos>
If the letter in the first line is H
a nonnegative number shall be appended (with no space).
In this case msc-gen will return the possible list of auto-completions,
when the cursor is at the number specified. This position is a caret position, value zero is
before the first character in the file, value 1 is after it. In case of UTF-8 input each character
counts as 1, even if multi-byte. Thus if the first character takes two bytes, then the position 1
will start at byte #2.
The list returned consists of one line per hint and the hints are neither grouped nor filtered
(see Typing Hints and Autocompletion). There are seven fields separated by the \x01
character.
1
if the hint is selectable (can actually be inserted to the chart) and 0
,
if it is only explanatory.
1
if the hint text shall be bold, 0
otherwise.
1
if the hint text shall be italics, 0
otherwise.
\x02
in order to avoid confusion with newlines separating the hints.
If the cursor is at a location where the user can type a new identifier (and not just one of the
values among the hints), the first hint will have its hint text equal to the asterisk (’*
’).
This shall be honoured by not expanding to one of the hints when the user presses the space or a
non alphanumeric character.
I<pos>
In this case the position is also a character position as for H
, but smart indentation
information is returned. Text editors can use it when the user presses TAB or RETURN keys,
or when the user has typed a brace or square bracket to the beginning of a line.
Msc-gen will return four numbers separated by a space and terminated by a newline.
<pos>
.
<pos>
.
In case of a pure ASCII input this equals the first number.
Note that if you would like to indent several lines at once, you need to actually indent the first one (by adding/removing spaces) and then re-parse the resulting file and do it for the second line, etc. This is because the calculated indent depends on lines above.
N
If this letter is added to the line, the chart text following the first line can be missing. (It is ignored if present all the way to the terminating zero character.) The text of the previous run is re-used, but parsed again. It is useful, when the text has not been changed, but we want hints at a different location.
Note that C
, D
, E
and H
will result in a re-parse of the chart text, so
it is a good strategy to send them all in once to be done with a single re-parsing as opposed to
send them one-by-one with N
, which results in a fresh re-parse again.
I
, on the other hand can work from a previous parse.
And the code for the color_id
is as follows.
0
Regular text (if a character is not listed, its color defaults to this).
1
A keyword, like commands or parallel
2
A partially typed keyword
3
An msc-gen only keyword
4
The equal sign
5
The semicolon sign
6
The colon character
7
The comma character
8
A symbol, e.g., arrows, box symbols, etc.
9
An mscgen symbol, e.g., arrows, box symbols, etc.
10
An opening or closing brace {}
11
An opening or closing bracket []
12
An opening or closing parenthesis ()
13
The name of a design
14
The name of a style
15
The name of an entity
16
The name of an entity when first occures in the file
17
The name of a color
18
The description of a color other than a name
19
The name of a marker
20
The name of a marker partially written
21
The name of a procedure
22
The name of a file to include
23
The name of a procedure parameter ($xxx)
24
The name of a chart option
25
The name of a chart option partially written
26
The name of an mscgen-only chart option
27
The name of an attribute
28
The name of a attribute partially written
29
The name of an mscgen-only attribute
30
The value of an attribute
31
Emphasized part of the attribute value (usually variables)
32
The text of a label, either after a colon or between quotation marks
33
The text of a label escape, such as ’\n’
34
A place where an error was detected.
35
The inverse of error formatting (used only internally)
36
A comment
Previous: Embedding Charts, Up: Command-Line Referece [Contents]