Highlight documentation
Plug-Ins
Script structure
The following script contains a minimal plug-in which has no effect on the output, since all update functions have empty definitions:
01 Description="NOOP plugin" 02 03 -- optional parameter: syntax description 04 function syntaxUpdate(desc) 05 end 06 07 -- optional parameter: theme description 08 function themeUpdate(desc) 09 end 10 11 Plugins={ 12 { Type="theme", Chunk=themeUpdate }, 13 { Type="lang", Chunk=syntaxUpdate }, 14 }
The first line contains a description which gives a short summary of the plug-in effects.
The next lines contain function definitions:
The syntaxUpdate function is applied on syntax definition scripts (*.lang),
whereas the themeUpdate function is applied on colour themes (*.theme).
The names of the functions are not mandatory.
The desc parameter contains the description of the syntax definition or
colour theme. This can be used to restrict modifications to certain kinds
of input (i.e. only C code should be enhanced with syslog keywords).
The Plugins array connects the functions to the Lua states which are created when highlight loads a lang or theme script. In this example, themeUpdate is connected to the theme state, and syntaxUpdate to the lang state. It is not required to define both connections if your plugin only affects one type of config script.
Syntax definition elements
The following list includes all items you may overwrite or extend to adjust the parser's syntax highlighting.
Syntax chunk elements:
Comments: table Description: string Digits: string EnableIndentation: boolean Identifiers: string IgnoreCase: boolean Keywords: table NestedSections: table Operators: string PreProcessor: table Strings: table Read only constants: HL_LANG_DIR: string HL_BLOCK_COMMENT: number HL_BLOCK_COMMENT_END: number HL_EMBEDDED_CODE_BEGIN: number HL_EMBEDDED_CODE_END: number HL_ESC_SEQ: number HL_ESC_SEQ_END: number HL_IDENTIFIER_BEGIN: number HL_IDENTIFIER_END: number HL_KEYWORD: number HL_KEYWORD_END: number HL_LINENUMBER: number HL_LINE_COMMENT: number HL_LINE_COMMENT_END: number HL_NUMBER: number HL_OPERATOR: number HL_OPERATOR_END: number HL_PREPROC: number HL_PREPROC_END: number HL_PREPROC_STRING: number HL_STANDARD: number HL_STRING: number HL_STRING_END: number HL_UNKNOWN: number HL_OUTPUT: number HL_FORMAT_HTML: number HL_FORMAT_XHTML: number HL_FORMAT_TEX: number HL_FORMAT_LATEX: number HL_FORMAT_RTF: number HL_FORMAT_ANSI: number HL_FORMAT_XTERM256: number HL_FORMAT_SVG: number HL_FORMAT_BBCODE: number Functions: AddKeyword: function OnStateChange: function Decorate: function
IMPORTANT: Functions will only be executed if they are defined as local functions within the lang chunk function referenced in the Plugins array. They will be ignored when defined elsewhere in the plug-in script.
Function OnStateChange
This function is a hook which is called if an internal state changes (ie from HL_STANDARD to HL_KEYWORD if a keyword is found). It can be used to alter the new state or to manipulate syntax elements.
OnStateChange(oldState, newState, token, kwGroupID)
Hook Event: Highlighting parser state change
Parameters: oldState: old state
newState: intended new state
token: the current token which triggered
the new state
kwGroupID: if newState is HL_KEYWORD, the parameter
contains the keyword group ID
Returns: Correct state to continue
Examples:
01 function OnStateChange(oldState, newState, token, kwgroup) 02 if newState==HL_KEYWORD and kwgroup==5 then 03 AddKeyword(token, 5) 04 end 05 return newState 06 end
This function adds the current token to the internal keyword list if the keyword belongs to keyword group 5. If keyword group 5 is defined by a regex, this token will be recognized later as keyword even if the regular regex does not match.
01 function OnStateChange(oldState, newState, token) 02 if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then 03 return HL_STRING_END 04 end 05 return newState 06 end
This function resolves a Lua parsing issue with the "]]" close delimiter which ends both comments and strings.
Function AddKeyword
This function will add a keyword to one of the the internal keyword lists. It has no effect if the keyword was added before. Keywords added with AddKeyword will remain active for all files of the same syntax if highlight is in batch mode.
AddKeyword(keyword, kwGroupID)
Parameters: keyword: string which should be added to a keyword list
kwGroupID: keyword group ID of the keyword
Returns: true if successfull
Function Decorate
This function is a hook which is called if a syntax token has been identified. It can be used to alter the token or to add additional text in the target output format (e.g. hyperlinks). Important: The return value of Decorate will be embedded in the formatting tags of the output format. The return value is not modified or validated by highlight.
Decorate(token, state, kwGroupID)
Hook Event: Token identification
Parameters: token: the current token
state: the current state
kwGroupID: if state is HL_KEYWORD, the parameter
contains the keyword group ID
Returns: Altered token string or nothing if original token should be
outputted
Examples:
01 function Decorate(token, state) 02 if (state == HL_KEYWORD) then 03 return string.upper(token) 04 end 05 end
This function converts all keywords to upper case.
01 knowntags={} 02 file = assert(io.open(HL_INPUT_FILE, "r")) 03 -- read file and fill knowntags 04 05 function Decorate(token, state, kwclass) 06 for k,v in pairs(knowntags) do 07 if k==token then 08 return '<span title="'..v..'">'..token .. '</span>' 09 end 10 end 11 end
This function adds tooltips to keywords which were found in a given tags file.
Theme chunk elements
The following list includes all items you may overwrite or extend to adjust the formatting (colour and font attributes) of the output:
Default: table Canvas: table Number: table Escape: table String: table StringPreProc: table BlockComment: table PreProcessor: table LineNum: table Operator: table LineComment: table Keywords: table Injections: table Read only: HL_OUTPUT: number HL_FORMAT_HTML: number HL_FORMAT_XHTML: number HL_FORMAT_TEX: number HL_FORMAT_LATEX: number HL_FORMAT_RTF: number HL_FORMAT_ANSI: number HL_FORMAT_XTERM256: number HL_FORMAT_SVG: number HL_FORMAT_BBCODE: number
Example
01 -- function to update language definition with syslog levels 02 function syntaxUpdate(desc) 03 if desc=="C and C++" then 04 table.insert( Keywords, 05 { Id=5, List={"LOG_EMERG", "LOG_CRIT", "LOG_ALERT", 06 "LOG_ERR", "LOG_WARNING","LOG_NOTICE","LOG_INFO", 07 "LOG_DEBUG"} 08 } ) 09 end 10 end 11 12 -- function to update theme definition 13 function themeUpdate(desc) 14 if desc=="Kwrite Editor" then 15 Canvas={ Colour="#E0EAEE" } 16 end 17 table.insert(Keywords, {Colour= "#ff0000", Bold=true}) 18 end 19 20 Plugins={ 21 { Type="theme", Chunk=themeUpdate }, 22 { Type="lang", Chunk=syntaxUpdate }, 23 }
01 Description="Add wxwidgets.org reference links to HTML, LaTeX or RTF output of C++ code" 02 03 function syntaxUpdate(desc) 04 05 if desc~="C and C++" then 06 return 07 end 08 09 function getURL(token) 10 urltoken, cnt = string.gsub(token, "%u", "_%1") 11 url='http://docs.wxwidgets.org/2.9.3/class'..string.lower(urltoken).. '.html' 12 13 if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then 14 return '<a class="hl" target="new" href="' .. url .. '">'.. token .. '</a>' 15 elseif (HL_OUTPUT == HL_FORMAT_LATEX) then 16 return '\\href{'..url..'}{'..token..'}' 17 elseif (HL_OUTPUT == HL_FORMAT_RTF) then 18 return '{{\\field{\\*\\fldinst HYPERLINK "'..url..'" }\\fldrslt \\ul\\ulc0 '..token..'}}' 19 end 20 end 21 22 function Decorate(token, state) 23 if (state ~= HL_STANDARD and state ~= HL_KEYWORD ) then 24 return 25 end 26 if string.find(token, "wx%u")==1 then 27 return getURL(token) 28 end 29 end 30 end 31 32 function themeUpdate(desc) 33 if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then 34 Injections[#Injections+1]="a.hl, a.hl:visited {color:inherit;font-weight:inherit;}" 35 elseif (HL_OUTPUT==HL_FORMAT_LATEX) then 36 Injections[#Injections+1]="\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}" 37 end 38 end 39 40 Plugins={ 41 42 { Type="lang", Chunk=syntaxUpdate }, 43 { Type="theme", Chunk=themeUpdate }, 44 45 }
