highlight.pl -- Highlight token server

This module provides the Prolog part of server-assisted highlighting for SWISH. It is implemented by managing a shadow copy of the client editor on the server. On request, the server computes a list of semantic tokens.

To be done

- Use websockets

 current_highlight_state(?UUID, -State) is nondet

Return info on the current highlighter

 prolog:xref_open_source(+UUID, -Stream)[multifile]

Open a source. As we cannot open the same source twice we must lock it. As of 7.3.32 this can be done through the prolog:xref_close_source/2 hook. In older versions we get no callback on the close, so we must leave the editor unlocked.

 show_mirror(+Role) is det

 server_tokens(+Role) is det

These predicates help debugging the server side. show_mirror/0 displays the text the server thinks is in the client editor. The predicate server_tokens/1 dumps the token list.

Arguments:

Role	- is one of source or query, expressing the role of the editor in the SWISH UI.

 swish_config:config(-Name, -Styles) is nondet[multifile]

Provides the object config.swish.style, a JSON object that maps style properties of user-defined extensions of library(prolog_colour). This info is used by the server-side colour engine to populate the CodeMirror styles.

To be done

- Provide summary information

 css(?Context, ?Selector, -Style) is nondet[multifile]

Multifile hook to define additional style to apply in a specific context. Currently defined contexts are:

hover

Used for CodeMirror hover extension.

Arguments:

Selector	- is a CSS selector, which is refined by Context
Style	- is a list of Name(Value) terms.

 token_info(+Token:dict)// is det[multifile]

Generate HTML, providing details about Token. Token is a dict, providing the enriched token as defined by style/3. This multifile non-terminal can be hooked to provide details for user defined style extensions.

 style(+StyleIn) is semidet[multifile]

 style(+StyleIn, -SWISHType:atomOrPair, -Attributes:list)[multifile]

Declare that we map StyleIn as generated by library(prolog_colour) into a token of type SWISHType, providing additional context information based on Attributes. Elements of Attributes are terms of the form Name(Value) or the atom text. The latter is mapped to text(String), where String contains the text that matches the token character range.

The resulting JSON token object has a property type, containing the SWISHType and the properties defined by Attributes.

Additional translations can be defined by adding rules for the multifile predicate style/3. The base type, which refers to the type generated by the SWISH tokenizer must be specified by adding an attribute base(BaseType). For example, if the colour system classifies an atom as refering to a database column, library(prolog_colour) may emit db_column(Name) and the following rule should ensure consistent mapping:

swish_highlight:style(db_column(Name),
                      db_column, [text, base(atom)]).

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 man_predicate_summary(Arg1, Arg2)