%Library.SyntaxColor
Class %Library.SyntaxColor Extends %RegisteredObject [ Not ProcedureBlock, System = 3 ]
Syntax color source code, generating HTML markup and stylesheets.
Note that this class is only available in Windows (both 32-bit and 64-bit) at present.
Parameters
ORDINALCOLOR
Parameter ORDINALCOLOR = 1;
ORDINALGETCSS
Parameter ORDINALGETCSS = 2;
ORDINALLANGUAGES
Parameter ORDINALLANGUAGES = 3;
ORDINALATTRIBUTES
Parameter ORDINALATTRIBUTES = 4;
Properties
DLLCallMode
Property DLLCallMode As %Integer [ InitialExpression = 3 ];
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
DLLHandle
Property DLLHandle As %Integer [ InitialExpression = 0 ];
The cached DLLHandle (used only when DLLCallMode=2)
DLLResultCode
Property DLLResultCode As %String;
Set to a result code string returned by CacheColorHTML.DLL.
Mainly of use to Intersystems support.
NoStyleNameUnderscore
Property NoStyleNameUnderscore As %Boolean [ InitialExpression = 0 ];
Set to the underscore-suppression flag as last used in a call to Color
- so that we can pass it to GetCSS
OrdinalOffset
Property OrdinalOffset As %Integer [ InitialExpression = 0, Internal ];
Methods
%OnClose
Method %OnClose() As %Status
Color
Method Color(InStream As %Stream.Object, OutStream As %Stream.Object, Language As %String = "COS", Flags As %String = "", DefFg As %String = "#000000", DefBg As %String = "#FFFFFF", ByRef Langs As %String, ByRef ColoringErrors As %Boolean, ByRef ErrorEnv As %String, ByRef ColoringWarnings As %Boolean, Symbols As %String = "") As %Boolean
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
... F/f (HTML) suppresses the outer ...lt;/FONT> which sets the default foreground and background I/i (HTML) inserts an HTML comment just before (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 anQ 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.
n .. use
Notes: If neither L nor l is given the attribute language is not shown. 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 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
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(),! }
ConfigName
Method ConfigName() As %String [ Private ]
Helper function to return the InterSystems IRIS configuration name.
GetCSS
Method GetCSS(OutStream As %Stream.Object, Language As %String = "COS", Format As %Integer) As %Boolean
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(),! }
Languages
Method Languages(ByRef Languages As %List) As %Boolean
Return a $List of canonical language monikers
The first moniker corresponds to language #0 in the K-flag JSON output
Attributes
Method Attributes(Language, ByRef Attributes As %List) As %Boolean
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
InvokeDLL
Method InvokeDLL(DLLFunction As %Integer, DLLArgs) As %List [ Private ]
Invoke the CacheColorHTML DLL function (DLLFunction), passing DLLArgs.
Returns what the $ZF call into the DLL returns, or something in the same format :-
$LISTBUILD(ZFOK, $LISTBUILD(Lang1, Lang2, ...), ColoringErrors, DLLResultCode)
ZF5
Method ZF5(handle As %Integer, DLLFunction As %Integer, DLLArgs, ByRef failed As %Boolean) As %String [ Private ]
Sets failed to 1 if the $ZF(-5,..) call fails, otherwise sets it to 0 and returns the DLL return code
ZF6
Method ZF6(DLLPath32 As %String, DLLPath64 As %String, DLLFunction As %Integer, DLLArgs, ByRef failed As %Boolean) As %String [ Private ]
Sets failed to 1 if the $ZF(-6,..) call fails, otherwise sets it to 0 and returns the DLL return code
PathToDLL
ClassMethod PathToDLL(SixtyFour As %Boolean) As %String [ CodeMode = expression ]
Return the path to the DLL
SameLanguage
ClassMethod SameLanguage(Lang1 As %String, Lang2 As %String) As %Boolean [ ProcedureBlock = 1 ]
Return whether two Studio language monikers are for the same language (ignoring moniker extensions)
SymbolsString
ClassMethod SymbolsString(ProcedureBlock As %Boolean = 1, ParameterNames As %List = "", PublicNames As %List = "") As %String [ ProcedureBlock = 1 ]
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
Assignments
ClassMethod Assignments(NameValues As %List, SymbolKinds As %List) As %String [ Private, ProcedureBlock = 1 ]
Given a list of names or 'name=value' strings and a list of symbol kinds (not documented)
Return a linefeed-delimited list of assignments to the names for each name/kind combination
Join
ClassMethod Join(SubStrings As %List, Delimiter As %String) As %String [ ProcedureBlock = 1 ]
Given a list of strings: combine the ones which are non-empty, separating them using the given delimiter