JSyntax Color

http://www.japisoft.com

Contact : http://www.japisoft.com/contact.html

v1.2.5

JSyntaxColor is a library for coloring in real time user text input. It works with a set of file descriptor defining a relation between expression and user view (a color, underline, border...). Java, Javascript, SQL and Formula samples are provided.

Main features :

Standard EditorKit
Simple property file for each syntax description
Real time switch between syntax description
Very compact and fast
Inner cache for limiting parsing scope
Tokens libraries cutomizable by user
Color, Underline, Border attributes support
Collection, delimiters, standard tokens
Sample for Java/SQL/Formula syntax
GUI for editing a syntax description
Many samples for API interesting parts

JSyntaxColor is a shareware, it is free to try for 30 days, else you must register for a low price the full version at : http://www.japisoft.com/buy.html. By registring you have a royalty free license and you can include JSyntaxColor with all your product.

I. Usage

Here a straightforward way for supporting coloring in a JEditorPane.

JEditorPane ed = new JEditorPane();
ScEditorKit ek = new ScEditorKit();
ed.setEditorKit( ek );
ek.readSyntaxColorDescriptor( "sql.prop" );
ed.setText( ... )

ScEditorKit reads a property file describing a format file (syntax and color). This propery file is available by two ways :

readSyntaxColorDescriptor : Read the property file from the classpath or if no file is found, read it by the file system
setSyntaxColorDescriptor : Set a Property object.

Some property file samples are available in the lib directory : sql.prop, java.prop and formula.prop.

Note : We don't recommend to use setPage from the JEditorPage due to a mapping to custom EditorKits depending on the content-type of the loaded document. For XML usage, We advise you to use JXMLPad at http://www.japisoft.com/xmlpad.

II. Property file

Here a sample of property file for coloring formula

token_op=(:):+:-:/:*:,:=:^:=:!=:&&:||:<:>:.:
token_number1=_NUMBER_
token_cst=PI:E:x:y
color_op=150:150:20
color_number1=blue
color_cst=red

This file is composed of a set of line containing key=value element. The key part can start with
token_, color_, underline_ and border_ and end by an ID. In the previous sample, we have 3 ID
(op, number1 or cst). So, the first key part is reserved word and the last one is user choice (the ID).

Key	Role
token_ID	Define a list of keywords and link it to ID
color_ID	Define a color for ID
underline_ID	Decide to underline or not ID with the color of ID or the default one
border_ID	Decide to draw a rectangle around ID with the color of ID or the default one
tokenMatchIni	Set of characters before a token for validiting it
tokenMatchEnd	Set of characters after a token for validating it
ignoreTokenMatch_ID	We ignore the characters before or after the tokens from token_ID
info	Target of the current property file. This is mainly useful for the GUI usage.

The value part have different meaning depending on the key type.

- token_ID :

value have 5 formats:

KeyWord1:KeyWord2:... is for a set of keywords. In the formula sample, the cst token is for 'PI' or 'E' or 'x' or 'y' words.
[First word;Final word] : match all element starting with 'First word' and ending by the 'Final word'. This matching have a high priority meaning the previous keyword will not be match inside this 2 parts. Exception is available using the following syntax : [First word;Final word{{\character exception}], this is useful when you want to support string like "test\"mychain\"",then jsyntaxcolor parser will ignore any ' " ' with a previous ' \' as a final word.
(word1;word2;word3;...) match a combinaison of word1 word2 word3 .... This is useful when you have to define word definition. For sample a number is composed of figures like (0;1;2;3;...;9) and we want to see any numbers as a full word rather than a set of word for each numbers. Morever, it avoids a conflict if you use a number for a variable name.
_PREDEFINED_ : Predefined is for user or API preference. Currently '_NUMBER_', '_LITTERAL_' or '_OPERATOR' are provided. User can enhance it with the ScPredefinedToken class.
Part of word1[[ list of chars ]number]End of word 1 : Create a set of new tokens using the list of chars and the number. Each new token is built appending each char until the number. For instance a[[ ]2]b will create 2 tokens : a b, a b. And a[[ \t]3]b will create 6 tokens : a b, a b, a b,a{tab},a{tab}{tab}b,a{tab}{tab}{tab}b. This format is useful when you need to create a token with several words.

- color_ID :

value have 2 formats:

Red:Green:Blue or well-known RGB composite, each value must match the range 0 to 255
CONST : With all Color default color : white, lightGray, gray, darkGray, black, red, pink, orange, yellow, green, magenta, cyan, blue.

- underline_ID or border_ID :

value is a boolean : true or false

If you wish not to take into account the upper or lower case for the token value a property 'ignoreCase' is available.

- tokenMatchIni :

value is a set of characters like : "\ \t([{" meaning a token from the token_ID list is valid only if it is preceding by the blank caracter (\ ) or the tab character (\t) or the caracters '[', '(' or '{'.

This value is useful for avoiding conflicts with token detection like if you use a variable name in your language source that matches a key word.

- tokenMatchtEnd :

This is similar to tokenMatchIni, except that this is only for characters after a detected token.

This value is useful for avoiding conflicts with token detection. As sample if you have a key word 'AND' and you wish to use a variable
name 'AND1', then with a non empty tokenMatchEnd it will detect that AND from the AND1 is not a key word.

- ignoreTokenMatch_ID :

Sometimes the preceding rules for bad tokens detection should be ignored. This is often the case for operators and delimiters.

Here a complete SQL sample :

token_keywords1=CREATE:TABLE:IF:NOT:EXISTS:DEFAULT:NULL:INDEX_NONE:BIT:REAL:CHAR:TEXT:DATE:TIME:FLOAT:STRING:NUMERIC:INTEGER:VARCHAR:PRIMARY:FOREIGN:KEY:UNIQUE:
ALTER:ADD:DROP:VIEW
token_keywords2=INSERT:INTO:VALUES:SET:DELETE:FROM:WHERE:LIMIT:UPDATE:SELECT:GROUP BY:HAVING:ORDER BY:JOIN:AS:ASC: DESC :COMMIT:ROLLBACK:LIKE: OR : AND :CONCAT
token_litteral1=[';']
token_op=(:):+:-:/:*:,:=
token_number1=_NUMBER_
color_keywords1=blue
color_keywords2=blue
color_litteral1=50:150:50
color_number1=red
color_op=150:150:20
ignoreCase=true
tokenMatchIni=\ \t([
tokenMatchEnd=\ \t)];=
ignoreTokenMatch_op=true
ignoreTokenMatch_litteral1=true

Remarks : All provided sample may be complete depending on your context (SQL version...) and wishes (color, UI properties...).

Special tokens

In some cases, we would prefer to insert a ':' or '\n' (carriage return) caracters. But there's a little scope problem between the property file and the wished elements. That's why, JSyntaxColor includes special tokens avoiding conflicts with the descriptor format.

_RC_ : Carriage return, equals to '\n'
_DD_ : Double dot, equals to ':'

As sample here the Java '//' comment description :

token_comment=[//;_RC_]

III. Language modeling

JSyntaxColor is provided with a complete GUI "modeler" for building/updating property file syntax descriptor.

Modeler

The modeler lists and edits available language descriptors from the lib directory.
The first top part helps you to choose a language or to manage it with the following buttons :

- New : Create a new language descriptor. You have to choose a name like 'bsh'.
- Delete : Delete the current one, if you want to delete a new one, you have to reload the application
- Save : Save the current one
- Info : Update the language descriptor

You must know that you loose your language descriptor changes if you don't save it and if
you select a new language from the top list.

You have two ways for editing your language descriptor :

1. The Descriptor tab

You have to select, create or remove a list of token like the keyword2 from the previous SQL property file sample. This list
is shown inside the central list. You can remove, add a new element for this list with the add Token and remove Token buttons. Each time you select an element from the list a textfield is updated below. If you want to change the current token element, you just have to press enter in the textfield.
GUI features are available in the bottom of the UI, just select a color by pressing the color button or select the underline or border checkbox.
Match ini delimiters and Match end delimiters are list of characters for avoiding token bad detection. It means that a token is valid only if if begins with one character of the Match ini delimiters and if it terminates with one character of the Match end delimiters.

2. The Property file tab

modeler

This property file is editable, you can validate it by changing of tab.

The last Test tab is a simple editor including your language descriptor and you can write sequence of characters for evaluating your descriptor choice.