Highlight documentation

• Manual
• Regular expressions
• Plug-Ins
• Languages
• Installation
• Wiki

  ---

• Syntax samples
• Theme samples
• Screenshots
• GUI animation
• NaCl-Demo

  ---

• ChangeLog
• Credits
• SF.net project

  ---

• Deutsche Dokumentation

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

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 -- first add a description of what the plug-in does
02 Description="Add qtproject.org reference links to HTML, LaTeX or RTF output"
03 
04 -- the syntaxUpdate function contains code related to syntax recognition
05 function syntaxUpdate(desc)
06 
07   -- if the current file is no C++ file we exit
08   if desc~="C and C++" then
09      return
10   end
11       
12   -- this function returns a qt-project reference link of the given token
13   function getURL(token)
14      -- generate the URL
15      url='http://qt-project.org/doc/qt-4.8/'..string.lower(token).. '.html'
16      
17      -- embed the URL in a hyperlink according to the output format
18      -- first HTML, then LaTeX and RTF
19      if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
20         return '<a class="hl" target="new" href="' 
21                .. url .. '">'.. token .. '</a>'
22      elseif (HL_OUTPUT == HL_FORMAT_LATEX) then
23         return '\\href{'..url..'}{'..token..'}'
24      elseif (HL_OUTPUT == HL_FORMAT_RTF) then
25         return '{{\\field{\\*\\fldinst HYPERLINK "'
26                ..url..'" }{\\fldrslt\\ul\\ulc0 '..token..'}}}'
27      end
28    end
29 
30   -- the Decorate function will be invoked for every recognized token
31   function Decorate(token, state)
32 
33     -- we are only interested in keywords, preprocessor or default items
34     if (state ~= HL_STANDARD and state ~= HL_KEYWORD and 
35         state ~=HL_PREPROC) then
36       return
37     end
38 
39     -- Qt keywords start with Q, followed by an upper and a lower case letter
40     -- if this pattern applies to the token, we return the URL
41     -- if we return nothing, the token is outputted as is
42     if string.find(token, "Q%u%l")==1 then
43       return getURL(token)
44     end
45 
46   end
47 end
48 
49 -- the themeUpdate function contains code related to the theme
50 function themeUpdate(desc)
51   -- the Injections table can be used to add style information to the theme
52   
53   -- HTML: we add additional CSS style information to beautify hyperlinks,
54   -- they should have the same color as their surrounding tags
55   if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
56     Injections[#Injections+1]=
57       "a.hl, a.hl:visited {color:inherit;font-weight:inherit;}"
58       
59   -- LaTeX: hyperlinks require the hyperref package, so we add this here
60   -- the colorlinks and pdfborderstyle options remove ugly boxes in the output
61   elseif (HL_OUTPUT==HL_FORMAT_LATEX) then
62     Injections[#Injections+1]=
63       "\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}"
64   end
65 end
66 
67 -- let highlight load the chunks
68 Plugins={
69   { Type="lang", Chunk=syntaxUpdate },
70   { Type="theme", Chunk=themeUpdate },
71 }