%Library.SyntaxColor

How we call the DLL

Takes one of the following values :-

• 1 - use $ZF(-3) ... handy for debugging the DLL because it doesn't stay loaded

• 2 - use $ZF(-4)/$ZF(-5) ... to cache the DLL handle

• 3 - use $ZF(-4)/$ZF(-6) ... the default - there's normally no reason to change it

Initialised to 3

The cached DLLHandle (used only when DLLCallMode=2)

Set to a result code string returned by CacheColorHTML.DLL.

Mainly of use to Intersystems support.

Set to the underscore-suppression flag as last used in a call to Color

- so that we can pass it to GetCSS

The return value of this method is ignored.

Return a $List of coloring attribute names for the given language

The first name corresponds to attribute #0 in the K-flag JSON output

The language can be passed as a numerical index or as a canonical language moniker as returned by Languages()

Syntax color the given source code using the given language.

Note that this class is only available in Windows (both 32-bit and 64-bit) at present.

• InStream is a stream containing the source code, we rewind it before using it

• OutStream is a stream to which the HTML (or CSV) is written (not the stylesheet - you need to use GetCSS for that)

• Language is the lang moniker for the language (e.g. "BAS", "JS", "COS", "HTML"). The default is "COS"

• Flags is a string of flag letters. A flag letter can be followed by "=" and a list of subflags (terminated by a ",").

• DefFg and DefBg are ignored if stylesheets are used. When stylesheets are not used DefFg and DefBg are HTML color codes in hex #xxxxxx format (i.e. they should be passed as strings). They default to black and white, respectively. They are used whenever a color is specified as "default foreground" or "default background" in the Studio registry settings.

• Langs is returned with a list of language monikers used (so you know what stylesheets to request) - e.g. $LB("COS","HTML")

• ColoringErrors is returned with 0 if there were no syntax coloring errors, 1 otherwise

Some flags only apply to certain output modes (HTML/CSV/XML). Supported flags are :-

• S/s (HTML) specifies that stylesheets should be used, otherwise it just embeds FONT settings into the marked up source

• P/p (HTML) suppresses the enclosing <PRE>...</PRE>

• F/f (HTML) suppresses the outer <FONT>...lt;/FONT> which sets the default foreground and background

• I/i (HTML) inserts an HTML comment just before </PRE> (or the error messages section) if present, otherwise at the end of the output; the comment contains information about the parsers used and the HTML rendering

• I/i (CSV) inserts "\i" followed by parser information at the end of the output

• I/i (XML) writes an <info info="..."/> tag at the end of the output (before </color>) with the parser information as the attribute value

• U/u (HTML) suppresses the "_" character in style names

• C/c selects CSV output (see below)

• Q selects XML output (but if C/c is given as well Q flag is ignored)

  The Q can be followed by "=" and one or more (case-sensitive) subflags to tailor the XML output :-

  • P .. include XML prolog ("<?xml...") at start of output

  • L .. include source language in the XML tag name - e.g. <COS_Command>

  • l .. include source language as an XML attribute - e.g. <Command language="COS">

  • N .. wrap XML tags for each source line in <line>...</line> tags

  • n .. use <newline/> tags to mark line-breaks

  Notes:

  1. If neither L nor l is given the attribute language is not shown.

  2. If neither N nor n is given the line-breaks are not shown.

• E/e (ALL) includes empty source lines in the output

• A/a (CSV) outputs attribute descriptions instead of hexadecimal codes

• B/b (CSV) outputs both a hexadecimal code and an attribute description, separated by a "|" character

• R/r (HTML) inserts one or more HTML comments just before </PRE> if present, otherwise at the end of the output; the comments contain coloring error messages returned by the parsers

• R/r (CSV) inserts one or more lines at the end of the output, each consisting of "\e " followed by a tab-delimited record made up of the fields of a parser coloring error :- description,source,location,linenumber,lineoffset (linenumber and lineoffset are 1-based) (any tab character in the original error info is converted to a space)

• R/r (XML) writes one or <error message="..."/> tag at the end of the output (before </color>) with parser coloring error messages as the attribute values

CSV output writes a line to the output stream for each syntax element and for each special element :-

• a syntax element is written as a record with commas delimiting the three components :-

  • the first component is the language name - e.g. COS

  • the second component is the terminal index in base 16 - e.g. 2F

  • the third component is the source code fragment

  Note that the third component can contain commas.

• a special element begins with "\" :-

  • "\n" indicates newline in the source

  • "\i " precedes an information line, shown when the I flag is given

The S, P, F and U flags and the DefFg and DefBg parameters are ignored when CSV/XML output is selected.

The method returns 1 if it succeeded in generating the required HTML, CSV or XML; 0 if it failed to do so. In the case of failure the DLLResultCode property will sometimes contain a message with more information about the failure.

Typical use :-

  Set instr=##class(%GlobalCharacterStream).%New()
  Do instr.WriteLine(" &SQL(SELECT * FROM A WHERE B=C)")
  Set outstr=##class(%GlobalCharacterStream).%New()
  Set colorer=##class(%SyntaxColor).%New()
  Set ret=colorer.Color(instr,outstr,"COS","PFS",,,.langs,.coloringerrors)
  If 'ret {Write "Fatal error: ",colorer.DLLResultCode,! Quit}
  If coloringerrors {
    Write "Syntax error(s)",!
  }
  Do outstr.Rewind()
  While 'outstr.AtEnd {
    Write outstr.ReadLine(),!
  }
  

Generates a CSS stylesheet for the given language moniker.

Note that this class is only available in Windows (both 32-bit and 64-bit) at present.

• OutStream is a stream to which the stylesheet is written

• Language is the language moniker (e.g. "COS" or "BAS")

The method returns 1 if it succeeded in generating the required stylesheet, 0 if it failed to do so. In the case of failure the DLLResultCode property will sometimes contain a message with more information about the failure.

Underscores are suppressed in the style names if either Color was last called with this flag OR if you explicitly set NoStyleNameUnderscore before calling this method

Typical use (continues on from the Color() example) :-

  Set css=##class(%GlobalCharacterStream).%New()
  For i=1:1:$ListLength(langs) D colorer.GetCSS(css,$List(langs,i))
  Do css.Rewind()
  While 'css.AtEnd {
    Write css.ReadLine(),!
  }
  

Given a list of strings: combine the ones which are non-empty, separating them using the given delimiter

Return a $List of canonical language monikers

The first moniker corresponds to language #0 in the K-flag JSON output

Return the path to the DLL

Return whether two Studio language monikers are for the same language (ignoring moniker extensions)

Given the procedure block setting and optional lists of parameter and public names (with optional '=xxx' tails)
Return a string suitable for passing as a Symbols parameter to Color()

ProcedureBlock must be omitted or passed as 1 for coloring warnings to be available
- if ProcedureBlock is "" the PROCBLOCK symbol is not set at all