RFC: Documenting Scintilla lexer properties

Properties.txt

# lexer:property_name:property_type:description
asm:fold:boolean:Enable or disable folding
asm:fold.asm.comment.explicit:boolean:This option enables folding explicit fold points when using the Asm lexer. Explicit fold points allows adding extra folding by placing a ;{ comment at the start and a ;} at the end of a section that should fold.
asm:fold.asm.comment.multiline:boolean:Set this property to 1 to enable folding multi-line comments.
asm:fold.asm.explicit.anywhere:boolean:Set this property to 1 to enable explicit fold points anywhere, not just in line comments.
asm:fold.asm.explicit.end:string:The string to use for explicit fold end points, replacing the standard ;}.
asm:fold.asm.explicit.start:string:The string to use for explicit fold start points, replacing the standard ;{.
asm:fold.asm.syntax.based:boolean:Set this property to 0 to disable syntax based folding.
asm:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
asm:lexer.as.comment.character:string:Overrides the default comment character (which is ';' for asm and '#' for as).
asm:lexer.asm.comment.delimiter:string:Character used for COMMENT directive's delimiter, replacing the standard "~".
caml:lexer.caml.magic:integer:
cmake:fold:integer:Enable or disable folding
cmake:fold.at.else:integer:This option enables folding on a "} else {" line of an if statement.
cobol:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
coffeescript:fold.coffeescript.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
coffeescript:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
conf:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
conf:lexer.props.allow.initial.spaces:integer:For properties files, set to 0 to style all lines that start with whitespace in the default style.
cpp:fold:boolean:Enable or disable folding
cpp:fold.at.else:boolean:This option enables C++ folding on a "} else {" line of an if statement.
cpp:fold.comment:boolean:This option enables folding multi-line comments and explicit fold points when using the C++ lexer. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
cpp:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
cpp:fold.cpp.comment.explicit:boolean:Set this property to 0 to disable folding explicit fold points when fold.comment=1.
cpp:fold.cpp.comment.multiline:boolean:Set this property to 0 to disable folding multi-line comments when fold.comment=1.
cpp:fold.cpp.explicit.anywhere:boolean:Set this property to 1 to enable explicit fold points anywhere, not just in line comments.
cpp:fold.cpp.explicit.end:string:The string to use for explicit fold end points, replacing the standard //}.
cpp:fold.cpp.explicit.start:string:The string to use for explicit fold start points, replacing the standard //{.
cpp:fold.cpp.preprocessor.at.else:boolean:This option enables folding on a preprocessor #else or #endif line of an #if statement.
cpp:fold.cpp.syntax.based:boolean:Set this property to 0 to disable syntax based folding.
cpp:fold.preprocessor:boolean:This option enables folding preprocessor directives when using the C++ lexer. Includes C#'s explicit #region and #endregion folding directives.
cpp:lexer.cpp.allow.dollars:boolean:Set to 0 to disallow the '$' character in identifiers with the cpp lexer.
cpp:lexer.cpp.backquoted.strings:boolean:Set to 1 to enable highlighting of back-quoted raw strings .
cpp:lexer.cpp.escape.sequence:boolean:Set to 1 to enable highlighting of escape sequences in strings
cpp:lexer.cpp.hashquoted.strings:boolean:Set to 1 to enable highlighting of hash-quoted strings.
cpp:lexer.cpp.track.preprocessor:boolean:Set to 1 to interpret #if/#else/#endif to grey out code that is not active.
cpp:lexer.cpp.triplequoted.strings:boolean:Set to 1 to enable highlighting of triple-quoted strings.
cpp:lexer.cpp.update.preprocessor:boolean:Set to 1 to update preprocessor definitions when #define found.
cpp:lexer.cpp.verbatim.strings.allow.escapes:boolean:Set to 1 to allow verbatim strings to contain escape sequences.
cpp:styling.within.preprocessor:boolean:For C++ code, determines whether all preprocessor code is styled in the preprocessor style (0, the default) or only from the initial # to the end of the command word(1).
css:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
css:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
css:lexer.css.hss.language:integer:Set to 1 for HSS (.hss)
css:lexer.css.less.language:integer:Set to 1 for Less CSS (.less)
css:lexer.css.scss.language:integer:Set to 1 for Sassy CSS (.scss)
d:fold:boolean:Enable or disable folding
d:fold.at.else:boolean:This option enables folding on a "} else {" line of an if statement.
d:fold.comment:boolean:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
d:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
d:fold.d.comment.explicit:boolean:Set this property to 0 to disable folding explicit fold points when fold.comment=1.
d:fold.d.comment.multiline:boolean:Set this property to 0 to disable folding multi-line comments when fold.comment=1.
d:fold.d.explicit.anywhere:boolean:Set this property to 1 to enable explicit fold points anywhere, not just in line comments.
d:fold.d.explicit.end:string:The string to use for explicit fold end points, replacing the standard //}.
d:fold.d.explicit.start:string:The string to use for explicit fold start points, replacing the standard //{.
d:fold.d.syntax.based:boolean:Set this property to 0 to disable syntax based folding.
d:lexer.d.fold.at.else:integer:This option enables D folding on a "} else {" line of an if statement.
fortran:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
fortran:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
freebasic:fold:boolean:Enable or disable folding
freebasic:fold.basic.comment.explicit:boolean:This option enables folding explicit fold points when using the Basic lexer. Explicit fold points allows adding extra folding by placing a ;{ (BB/PB) or '{ (FB) comment at the start and a ;} (BB/PB) or '} (FB) at the end of a section that should be folded.
freebasic:fold.basic.explicit.anywhere:boolean:Set this property to 1 to enable explicit fold points anywhere, not just in line comments.
freebasic:fold.basic.explicit.end:string:The string to use for explicit fold end points, replacing the standard ;} (BB/PB) or '} (FB).
freebasic:fold.basic.explicit.start:string:The string to use for explicit fold start points, replacing the standard ;{ (BB/PB) or '{ (FB).
freebasic:fold.basic.syntax.based:boolean:Set this property to 0 to disable syntax based folding.
freebasic:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
haskell:fold:boolean:Enable or disable folding
haskell:fold.comment:boolean:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
haskell:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
haskell:fold.haskell.imports:boolean:Set to 1 to enable folding of import declarations
haskell:lexer.haskell.allow.hash:boolean:Set to 0 to disallow the '#' character at the end of identifiers and literals with the haskell lexer (GHC -XMagicHash extension)
haskell:lexer.haskell.allow.questionmark:boolean:Set to 1 to allow the '?' character at the start of identifiers with the haskell lexer (GHC & Hugs -XImplicitParams extension)
haskell:lexer.haskell.allow.quotes:boolean:Set to 0 to disable highlighting of Template Haskell name quotations and promoted constructors (GHC -XTemplateHaskell and -XDataKinds extensions)
haskell:lexer.haskell.cpp:boolean:Set to 0 to disable C-preprocessor highlighting (-XCPP extension)
haskell:lexer.haskell.import.safe:boolean:Set to 0 to disallow "safe" keyword in imports (GHC -XSafe, -XTrustworthy, -XUnsafe extensions)
haskell:styling.within.preprocessor:boolean:For Haskell code, determines whether all preprocessor code is styled in the preprocessor style (0, the default) or only from the initial # to the end of the command word(1).
html:asp.default.language:integer:Script in ASP code is initially assumed to be in JavaScript. To change this to VBScript set asp.default.language to 2. Python is 3.
html:fold:boolean:Enable or disable folding
html:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
html:fold.html:boolean:Folding is turned on or off for HTML and XML files with this option. The fold option must also be on for folding to occur.
html:fold.html.preprocessor:boolean:Folding is turned on or off for scripts embedded in HTML files with this option. The default is on.
html:fold.hypertext.comment:boolean:Allow folding for comments in scripts embedded in HTML. The default is off.
html:fold.hypertext.heredoc:boolean:Allow folding for heredocs in scripts embedded in HTML. The default is off.
html:fold.xml.at.tag.open:boolean:Enable folding for XML at the start of open tag. The default is off.
html:html.tags.case.sensitive:boolean:For XML and HTML, setting this property to 1 will make tags match in a case sensitive way which is the expected behaviour for XML and XHTML.
html:lexer.html.django:boolean:Set to 1 to enable the django template language.
html:lexer.html.mako:boolean:Set to 1 to enable the mako template language.
html:lexer.xml.allow.scripts:boolean:Set to 0 to disable scripts in XML.
lua:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
matlab:fold:integer:Enable or disable folding
matlab:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
matlab:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
nsis:fold:integer:Enable or disable folding
nsis:fold.at.else:integer:This option enables folding on a "} else {" line of an if statement.
nsis:nsis.foldutilcmd:integer:
nsis:nsis.ignorecase:integer:
nsis:nsis.uservars:integer:
pascal:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
pascal:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
pascal:fold.preprocessor:integer:This option enables folding preprocessor directives when using the C++ or Pascal lexer. Includes C#'s explicit #region and #endregion folding directives.
pascal:lexer.pascal.smart.highlighting:integer:
perl:fold:boolean:Enable or disable folding
perl:fold.comment:boolean:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
perl:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
perl:fold.perl.at.else:boolean:This option enables Perl folding on a "} else {" line of an if statement.
perl:fold.perl.comment.explicit:boolean:Set to 0 to disable explicit folding.
perl:fold.perl.package:boolean:Set to 0 to disable folding packages when using the Perl lexer.
perl:fold.perl.pod:boolean:Set to 0 to disable folding Pod blocks when using the Perl lexer.
php:asp.default.language:integer:Script in ASP code is initially assumed to be in JavaScript. To change this to VBScript set asp.default.language to 2. Python is 3.
php:fold:boolean:Enable or disable folding
php:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
php:fold.html:boolean:Folding is turned on or off for HTML and XML files with this option. The fold option must also be on for folding to occur.
php:fold.html.preprocessor:boolean:Folding is turned on or off for scripts embedded in HTML files with this option. The default is on.
php:fold.hypertext.comment:boolean:Allow folding for comments in scripts embedded in HTML. The default is off.
php:fold.hypertext.heredoc:boolean:Allow folding for heredocs in scripts embedded in HTML. The default is off.
php:fold.xml.at.tag.open:boolean:Enable folding for XML at the start of open tag. The default is off.
php:html.tags.case.sensitive:boolean:For XML and HTML, setting this property to 1 will make tags match in a case sensitive way which is the expected behaviour for XML and XHTML.
php:lexer.html.django:boolean:Set to 1 to enable the django template language.
php:lexer.html.mako:boolean:Set to 1 to enable the mako template language.
php:lexer.xml.allow.scripts:boolean:Set to 0 to disable scripts in XML.
po:fold:integer:Enable or disable folding
po:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
po:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
powershell:fold.at.else:integer:This option enables folding on a "} else {" line of an if statement.
powershell:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
powershell:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
python:fold:boolean:Enable or disable folding
python:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
python:fold.quotes.python:boolean:This option enables folding multi-line quoted strings when using the Python lexer.
python:lexer.python.keywords2.no.sub.identifiers:boolean:When enabled, it will not style keywords2 items that are used as a sub-identifier. Example: when set, will not highlight "foo.open" when "open" is a keywords2 item.
python:lexer.python.literals.binary:boolean:Set to 0 to not recognise Python 3 binary and octal literals: 0b1011 0o712.
python:lexer.python.strings.b:boolean:Set to 0 to not recognise Python 3 bytes literals b"x".
python:lexer.python.strings.f:boolean:Set to 0 to not recognise Python 3.6 f-string literals f"var={var}".
python:lexer.python.strings.over.newline:boolean:Set to 1 to allow strings to span newline characters.
python:lexer.python.strings.u:boolean:Set to 0 to not recognise Python Unicode literals u"x" as used before Python 3.
python:lexer.python.unicode.identifiers:boolean:Set to 0 to not recognise Python 3 Unicode identifiers.
python:tab.timmy.whinge.level:integer:For Python code, checks whether indenting is consistent. The default, 0 turns off indentation checking, 1 checks whether each line is potentially inconsistent with the previous line, 2 checks whether any space characters occur before a tab character in the indentation, 3 checks whether any spaces are in the indentation, and 4 checks for any tab characters in the indentation. 1 is a good level to use.
r:fold.at.else:integer:This option enables folding on a "} else {" line of an if statement.
r:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
ruby:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
ruby:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
rust:fold:boolean:Enable or disable folding
rust:fold.at.else:boolean:This option enables folding on a "} else {" line of an if statement.
rust:fold.comment:boolean:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
rust:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
rust:fold.rust.comment.explicit:boolean:Set this property to 0 to disable folding explicit fold points when fold.comment=1.
rust:fold.rust.comment.multiline:boolean:Set this property to 0 to disable folding multi-line comments when fold.comment=1.
rust:fold.rust.explicit.anywhere:boolean:Set this property to 1 to enable explicit fold points anywhere, not just in line comments.
rust:fold.rust.explicit.end:string:The string to use for explicit fold end points, replacing the standard //}.
rust:fold.rust.explicit.start:string:The string to use for explicit fold start points, replacing the standard //{.
rust:fold.rust.syntax.based:boolean:Set this property to 0 to disable syntax based folding.
rust:lexer.rust.fold.at.else:integer:This option enables Rust folding on a "} else {" line of an if statement.
sh:fold:boolean:Enable or disable folding
sh:fold.comment:boolean:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
sh:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
sql:fold:boolean:Enable or disable folding
sql:fold.comment:boolean:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
sql:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
sql:fold.sql.at.else:boolean:This option enables SQL folding on a "ELSE" and "ELSIF" line of an IF statement.
sql:fold.sql.only.begin:boolean:
sql:lexer.sql.allow.dotted.word:boolean:Set to 1 to colourise recognized words with dots (recommended for Oracle PL/SQL objects).
sql:lexer.sql.backticks.identifier:boolean:
sql:lexer.sql.numbersign.comment:boolean:If "lexer.sql.numbersign.comment" property is set to 0 a line beginning with '#' will not be a comment.
sql:sql.backslash.escapes:boolean:Enables backslash as an escape character in SQL.
tcl:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
tcl:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
verilog:fold.at.else:boolean:This option enables folding on the else line of an if statement.
verilog:fold.comment:boolean:This option enables folding multi-line comments when using the Verilog lexer.
verilog:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
verilog:fold.preprocessor:boolean:This option enables folding preprocessor directives when using the Verilog lexer.
verilog:fold.verilog.flags:boolean:This option enables folding module definitions. Typically source files contain only one module definition so this option is somewhat useless.
verilog:lexer.verilog.allupperkeywords:boolean:Set to 1 to style identifiers that are all uppercase as documentation keyword.
verilog:lexer.verilog.fold.preprocessor.else:boolean:This option enables folding on `else and `elsif preprocessor directives.
verilog:lexer.verilog.portstyling:boolean:Set to 1 to style input, output, and inout ports differently from regular keywords.
verilog:lexer.verilog.track.preprocessor:boolean:Set to 1 to interpret `if/`else/`endif to grey out code that is not active.
verilog:lexer.verilog.update.preprocessor:boolean:Set to 1 to update preprocessor definitions when `define, `undef, or `undefineall found.
vhdl:fold.at.Begin:integer:
vhdl:fold.at.Parenthese:integer:
vhdl:fold.at.else:integer:This option enables folding on a "} else {" line of an if statement.
vhdl:fold.comment:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.
vhdl:fold.compact:integer:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
xml:asp.default.language:integer:Script in ASP code is initially assumed to be in JavaScript. To change this to VBScript set asp.default.language to 2. Python is 3.
xml:fold:boolean:Enable or disable folding
xml:fold.compact:boolean:This option on leads to blank lines following the end of an element folding with that element. Defaults to on.
xml:fold.html:boolean:Folding is turned on or off for HTML and XML files with this option. The fold option must also be on for folding to occur.
xml:fold.html.preprocessor:boolean:Folding is turned on or off for scripts embedded in HTML files with this option. The default is on.
xml:fold.hypertext.comment:boolean:Allow folding for comments in scripts embedded in HTML. The default is off.
xml:fold.hypertext.heredoc:boolean:Allow folding for heredocs in scripts embedded in HTML. The default is off.
xml:fold.xml.at.tag.open:boolean:Enable folding for XML at the start of open tag. The default is off.
xml:html.tags.case.sensitive:boolean:For XML and HTML, setting this property to 1 will make tags match in a case sensitive way which is the expected behaviour for XML and XHTML.
xml:lexer.html.django:boolean:Set to 1 to enable the django template language.
xml:lexer.html.mako:boolean:Set to 1 to enable the mako template language.
xml:lexer.xml.allow.scripts:boolean:Set to 0 to disable scripts in XML.
yaml:fold.comment.yaml:integer:Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.

scintilla-lexer-properties.c

/*
 *      scintilla-lexer-properties.c
 *
 *      Copyright 2020 The Geany contributors
 *
 *      This program is free software; you can redistribute it and/or modify
 *      it under the terms of the GNU General Public License as published by
 *      the Free Software Foundation; either version 2 of the License, or
 *      (at your option) any later version.
 *
 *      This program is distributed in the hope that it will be useful,
 *      but WITHOUT ANY WARRANTY; without even the implied warranty of
 *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *      GNU General Public License for more details.
 *
 *      You should have received a copy of the GNU General Public License along
 *      with this program; if not, write to the Free Software Foundation, Inc.,
 *      51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#include <gtk/gtk.h>
#include "geany.h"
#include "utils.h"

#include "SciLexer.h"
#include "Scintilla.h"
#include "ScintillaWidget.h"


static gchar *sci_get_string(ScintillaObject *sci, guint msg, gulong wParam)
{
	gint size = (gint) scintilla_send_message(sci, msg, wParam, 0);
	gchar *str = g_malloc(size + 1);

	scintilla_send_message(sci, msg, wParam, (sptr_t) str);
	str[size] = '\0';	/* ensure termination, needed for SCI_GETLINE */
	return str;
}


static const gchar *get_property_type_name(gint property_type)
{
	switch (property_type)
	{
		case SC_TYPE_BOOLEAN:
			return "boolean";
		case SC_TYPE_INTEGER:
			return "integer";
		case SC_TYPE_STRING:
		default:
			return "string";
	}
}


int main(int argc, char **argv)
{
	ScintillaObject *sci;
	gchar *lexer_name;
	gchar *property_string;
	gchar **properties;
	gchar **property;
	gchar *property_description;
	const gchar *property_type_name;
	gint lexer;
	gint property_type;

	gtk_init_check(NULL, NULL);
	sci = SCINTILLA(scintilla_new());

	for (lexer = 1; lexer < SCLEX_AUTOMATIC; lexer++)
	{
		scintilla_send_message(sci, SCI_SETLEXER, lexer, 0);

		property_string = sci_get_string(sci, SCI_PROPERTYNAMES, 0);
		properties = g_strsplit(property_string, "\n", -1);
		if (properties && properties[0])
		{
			lexer_name = sci_get_string(sci, SCI_GETLEXERLANGUAGE, 0);
			foreach_strv(property, properties)
			{
				property_description = sci_get_string(sci, SCI_DESCRIBEPROPERTY, (sptr_t) *property);
				property_type = scintilla_send_message(sci, SCI_PROPERTYTYPE, (sptr_t) *property, 0);
				property_type_name = get_property_type_name(property_type);
				printf("%s:%s:%s:%s\n", lexer_name, *property, property_type_name, property_description);

				g_free(property_description);
			}
			g_free(lexer_name);
		}
		g_free(property_string);
		g_strfreev(properties);
	}
	gtk_widget_destroy(GTK_WIDGET(sci));
	return 0;
}

scintilla-lexer-properties.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# flake8: noqa pylint: disable=line-too-long,no-self-use
#
# scintilla-lexer-properties.py
#
# Copyright 2020 The Geany contributors
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.



# Find and describe Scintilla lexer properties
# The script first uses "grep" to find old style lexer properties in the source
# code directly and then compiles a little C program (scintilla-lexer-properties.c)
# to query new style properties via the Scintilla API.
# All found properties are then printed to stdout.
#
# Requirements:
# - gcc
# - installed Geany with development files (to be found via pkg-config)
# - Python3.6+
# - grep
#
# Usage: python scripts/scintilla-lexer-properties.py
# (To be executed from the root Geany source directory)

import os
import re
import subprocess


# some properties lacks a description (all old style properties, also some of the newer ones)
# the following map describes some common, often repeating properties
# based on https://www.scintilla.org/SciTEDoc.html
FOLD_COMMENT_DESCRIPTION = 'Enables folding multi-line comments and explicit fold points. Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} at the end of a section that should fold.'
COMMON_PROPERTY_DESCRITPIONS = {
    'fold': 'Enable or disable folding',
    'fold.at.else': 'This option enables folding on a "} else {" line of an if statement.',
    'fold.comment': FOLD_COMMENT_DESCRIPTION,
    'fold.compact': 'This option on leads to blank lines following the end of an element folding with that element. Defaults to on.',
    'fold.preprocessor': 'This option enables folding preprocessor directives when using the C++ or Pascal lexer. Includes C#\'s explicit #region and #endregion folding directives.',
    'lexer.css.hss.language': 'Set to 1 for HSS (.hss)',
    'lexer.css.less.language': 'Set to 1 for Less CSS (.less)',
    'lexer.css.scss.language': 'Set to 1 for Sassy CSS (.scss)',
    'lexer.props.allow.initial.spaces': 'For properties files, set to 0 to style all lines that start with whitespace in the default style.',
    'fold.coffeescript.comment': FOLD_COMMENT_DESCRIPTION,
    'fold.comment.yaml': FOLD_COMMENT_DESCRIPTION,
}

# map property type names
PROPERTY_TYPE_MAP = {
    'Int': 'integer'
}

# map lexer names to Geany filetype names
LEXER_FILETYPE_NAME_MAP = {
    'bash': 'sh',
    'hypertext': 'html',
    'phpscript': 'php',
    'props': 'conf',
}

GREP_MATCH_RE = re.compile('scintilla/lexers/Lex(?P<lexer>\\w+).cxx:.*GetProperty(?P<type>\\w+)\\("(?P<name>[\\w.]+)"(, .)?\\)')


class ScintillaLexerProperties:

    def __init__(self):
        self._lexer_properties = dict()

    def find_lexer_properties(self):
        self._find_old_style_properties()
        self._find_new_style_properties()

    def _find_old_style_properties(self):
        # Find old style properties in Scintilla with good old "grep" and post-process them
        grep_cmd = '''egrep 'GetProperty\\w*\\("([^"]+)"[^)]*\\)' scintilla/lexers/Lex*.cxx | uniq'''
        process = subprocess.run(grep_cmd, stdout=subprocess.PIPE, check=True, shell=True)
        result = process.stdout.decode('utf-8')
        for line in result.splitlines():
            line = line.strip()
            if self._line_looks_like_commented(line):
                continue

            match = GREP_MATCH_RE.match(line)
            if match:
                lexer = match.group('lexer')
                property_type = match.group('type')
                property_name = match.group('name')
                lexer = self._adapt_lexer_name(lexer)
                property_type = self._adapt_property_type(property_type)
                description = self._get_description_for_property(property_name)

                lexer_properties = self._lexer_properties.setdefault(lexer, set())
                lexer_properties.add((property_name, property_type, description))

    def _line_looks_like_commented(self, line):
        # try to detect commented properties (e.g. in scintilla/lexers/LexAbaqus.cxx)
        parts = line.split('(', 2)
        if '//' in parts[0]:
            return True

        return False

    def _adapt_lexer_name(self, lexer):
        lexer = lexer.lower()
        return LEXER_FILETYPE_NAME_MAP.get(lexer, lexer)

    def _adapt_property_type(self, property_type):
        return PROPERTY_TYPE_MAP.get(property_type, property_type)

    def _get_description_for_property(self, property_name):
        return COMMON_PROPERTY_DESCRITPIONS.get(property_name, '')

    def _find_new_style_properties(self):
        helper_program_name = 'scripts/scintilla-lexer-properties'
        # compile our helper program
        gcc_command = f'gcc -Wall -DGTK_DISABLE_DEPRECATED `pkg-config --libs --cflags geany` ' \
            f'-o {helper_program_name} scripts/scintilla-lexer-properties.c'
        subprocess.run(gcc_command, check=True, shell=True)
        # Find new style properties by reading them directly via Scintilla API
        process = subprocess.run([helper_program_name], stdout=subprocess.PIPE, check=True)
        result = process.stdout.decode('utf-8')
        for line in result.splitlines():
            lexer, property_name, property_type, description = line.strip().split(':', 3)
            lexer = self._adapt_lexer_name(lexer)
            if not description:
                description = self._get_description_for_property(property_name)

            lexer_properties = self._lexer_properties.setdefault(lexer, set())
            lexer_properties.add((property_name, property_type, description))

        os.remove(helper_program_name)

    def print_lexer_properties(self):
        for lexer in sorted(self._lexer_properties):
            for property_name, property_type, description in sorted(self._lexer_properties[lexer]):
                print(f'{lexer}:{property_name}:{property_type}:{description}')


def main():
    lexer_properties = ScintillaLexerProperties()
    lexer_properties.find_lexer_properties()
    lexer_properties.print_lexer_properties()


if __name__ == '__main__':
    main()