iniFileFormat

Fileformat of the UniversalIndentGUI indent description ini files
=================================================================

1. General
----------
The ini file has equal base format as common used ini files. It contains groups, which are written in brackets []. These groups can contain keys, to which a value can be assigned by the equal sign =.

2. Ini file header
------------------
At the beginning of the ini file the header is located. It is named [%20header]. You might wonder why I use the "%20" before the header. The reason for this is, that Qt, which I use as programming framework, automatically sorts the ini file by the group names in alphabetical order. To have the header at the beginning of each ini file I use "%20", it stands for a space. So nothing important about this.
Following a ini file header is shown:

[%20header]
categories=Predefined Style|Tab and Bracket|Indentation|Formatting
cfgFileParameterEnding=cr
configFilename=.astylerc
fileTypes=*.cpp|*.c|*.h|*.hpp|*.cs|*.java
indenterFileName=astyle
indenterName=Artistic Style
inputFileName=indentinput
inputFileParameter=
manual="http://website.of.onlinemanual"
outputFileName=indentinput
outputFileParameter=none
parameterOrder=ipo
stringparaminquotes=false
useCfgFileParameter="--options="
version=1.21

"categories" defines the categories, where each parameter can be assigned to. It is a list of strings, with each category name divied by a "|" from the other.

"cfgFileParameterEnding" defines how each parameter setting in the indenters config file is seperated from the other. Possible values are "cr" for CarriageReturn or any other string (also space signs, which are normally used if parameters are only set via commandline).

"configFilename" is the filename of the indenters default config file. It is used when the indenter is being called and might be explicit handed over as argument by setting the parameter "useCfgFileParameter". If "configFilename" is left empty, all parameters are set with the commandline call of the indenter. (As needed for csstidy and phpCB for example.)

"fileTypes" is a list of fileendings used for the selection in the "open source file" file dialog.

"indenterFileName" is the name of the indenters executable without any extension. Under linux it is tested, whether only a file with the extension ".exe" exists. If so, wine will be used to call the indenter.

"indenterName" is the name of the indenter as it will be shown in UniversalIndentGUIs indenters selection. Theoretic it can be any string.

"inputFileName" defines the file used as input file for the called indenter. It is a copy of the previous opened source code file.

"inputFileParameter" sets the eventually needed parameter in front of "inputFileName" to tell the indenter and the command line call that the following string is the input file. If set to "none" no special output file will be set.

"manual" is a string that points to a website that hosts the indenters online manual.

"outputFileName" the file name where the indenter writes its formatted source code to. Also the file UniversalIndentGUI reads after the indenter call to show it in the preview. Some times an indenter overwrites the content of the inputfile by default and creates a backup (as AStyle does). In this case "outputFileName" is equal to "inputFileName" but the parameter "outputFileParameter" has to be set to "none". No output file name will be selected for the indenter but UniversalIndentGUI knows where the output was written to.

"outputFileParameter" same as for "inputFileParameter" with respect to the special case mentioned for "inputFileParameter" if the input file will be overwritten. If the indenter only writes to standard output (stdout) this value has to be set to "stdout" (see uigui_phpCB.ini). In that case "outputFileName" can be left empty. It will be ignored anyway.

"parameterOrder" Some indenters need a strict order of the command line parameters for input file, output file and eventually indent settings. "parameterOrder" can be set to "iop", "ipo" and "pio" to define the order of input, ouput and paramters at the commandline call.

"stringparaminquotes" tells UniversalIndentGUI that all string values should be written to the indenter config file in quotes.

"useCfgFileParameter" is the parameter for the indenter used to tell the indenter where to find the config file, set in "configFilename", that it should use. If this parameter is left empty you should read the indenters manual where it searches by default for the config file.

"version" is not evaluated by UiGUI, but by this it is easier to see for which version of the indenter the configuration file has been written for.

3. The indenters parameters
---------------------------
After the header definition the paramters used by the indenter are defined. Each paramter name is written in brackets [] again, but the name is only descriptive and not functional. Each parameter consists of keys with values (same as in header). There are four types of parameters: boolean, numeric, string and multiple. All have the following keys in common:
"Category" defines to which category they belong and are corresponding only shown there in the GUI.

"Description" holds a text describing the parameter and it options. It is formatted as html, so source code examples can be embedded via <pre></pre> for example. This text is shown as tool tip for each parameter.

"EditorType" defines whether the parameter is boolean, numeric, string or multiple.

"Value" is the current defined value for the parameter. For boolean 0 is equal to false and 1 is equal to true. In case of multiple the number defines which of the multiple choice parameters is selected, starting with 0.

"ValueDefault" is the default value that is normally used by the indenter if this parameter is not defined. It is needed if the config file of an indenter is loaded but this value is not defined there.

"Enabled" is not used for boolean but for all other parameters. Defines whether the value should be written to the indenters config file or not. If it is disabled it will not be written and the indenter uses its default value.

3.1. Boolean parameters

Example:

[ANSI style formatting]
Category=0
Description="<html>ANSI style formatting/indenting.</html>"
EditorType=boolean
TrueFalse="--style=ansi|"
Value=0
ValueDefault=0

The only special here is the key "TrueFalse". The string is a parameter list always consists of two parameters devided by a "|" sign, where the first one defines the true case and the second the false case. Some indenters like GreatCode have a parameter for true and false, some other like AStyle in this example only have a parameter for the false case, so the second parameter is empty.

3.2. Numeric parameters

[Indent spaces]
CallName="--indent=spaces="
Category=1
Description="<html>Indent using # spaces per indent</html>"
EditorType=numeric
Enabled=false
MaxVal=20
MinVal=2
Value=4
ValueDefault=4

Numeric parameters have defined a maximum value "MaxVal" and a minimum value "MinVal" which can/should not be exceeded. The "CallName" is the parameter as string as it will be written to the indenters config file. At its ending "Value" will be appended.

3.3. String parameters

[Comment separation char]
CallName=-cmt_sep_char_4-
Category=5
Description="<html>Set the special character to fill automatic comments.</html>"
EditorType=string
Enabled=true
Value=*
ValueDefault=*

The "CallName" is the parameter as string as it will be written to the indenters config file. At its ending "Value" will be appended. Value can also be a list of strings separated by the "|" sign. By this the parameter is written to the config file with each value in the list.
In the upper example value could be "C|c|K". The result in the ouput file would be:
-cmt_sep_char_4-C -cmt_sep_char_4-c -cmt_sep_char_4-K

3.4. Multiple parameters

[Bracket style]
Category=1
Choices="--brackets=break|--brackets=attach|--brackets=linux|--brackets=break-closing-headers"
ChoicesReadable="Break brackets|Attach brackets|Break brackets Linux like|Break closing headers"
Description="<html>Sets the bracket style.</html>"
EditorType=multiple
Enabled=false
Value=1
ValueDefault=-1

Multiple parameters can have exactly one parameter out of a list selected. "Choices" is a parameter list consisting of parameters devided by a "|" sign. Each parameter in the list will be exactly written to the indenters config file as defined here. The list "ChoicesReadable" can be used to show more readable text in the combo box, instead of the "Choices" text. "ChoicesReadable" must have as many entries as "Choices".