DelphiDabbler CodeSnip
File Format Documentation

# Configuration Files

## Introduction

CodeSnip uses two config files – one system wide application file named `Common.config` and another user file named `User.config`. The standard version of CodeSnip maintains separate user config file for each user account that uses CodeSnip, while the portable version has just one such file.

Config files use the standard INI file format and are written and read using Windows API calls.

The following data types are supported:

- String – stored as a sequence of characters, optionally enclosed in double quotes.
- Boolean – stored as the text `False` and `True` (although `0`, `No` and `N` are all read as false).
- Integer – stored as positive or negative whole numbers or zero.
- Float – stored as positive or negative floating point numbers or zero. Floating point representations of whole numbers are stored as integers.
- Date-Time – stored in the `YYYY-MM-DD hh:mm:ss` format in all locales (i.e. the date and time separators are always `-` and `:` respectively.

## Encoding

From CodeSnip v4 config files are little endian Unicode text files with a byte order mark. This encoding is used because the international support is required and because the Windows API, which is used to read and write the files, understands this file format.

On earlier versions of CodeSnip the config files were ANSI text files using the system's default encoding. CodeSnip v4 and the standard edition's installer convert the older ANSI files to Unicode.

## File Format

### Common Config File

Note: From CodeSnip v4.16 this file is used only by the installer of the standard edition. The portable edition does not use the file and does not create it.

The file stores information about the current version of the program. It is named `Common.config`. The file is stored in the standard edition's `%ProgramData%\DelphiDabbler\CodeSnip.4` directory.

There have been several versions of this file. The current one is version 7. The change to version 7 came with CodeSnip v4.16.0 and the removal of DelphiDabbler web service support.

The file has the following sections.

#### [Application] section

Provides information about the application.

Name / Value pairs:

`Version` (String)
  Internal version number of the installed version of CodeSnip as a dotted quad string.

#### [IniFile] section

Provides information about the config file itself.

Name / Value pairs:

`Version` (Integer)
  Version number of the config file. Incremented whenever the file format changes. If this section or this value is missing then the default value is `1`.
  The current value is `7`.

### User Config File

This file records configuration information that is unique users of the application. Some sections correspond to user preferences while others record details of previous operations or the layout of the GUI. The file is named `User.config`. The standard edition of CodeSnip stores the file in the logged on user's `%AppData%\DelphiDabbler\CodeSnip.4` directory, while the portable version stores it in the `AppDir` sub-directory of the folder where CodeSnip is installed.

There have been several versions of this file. The current one is version 19. The change to version 19 came with CodeSnip v4.21.0 and the addition of the [Compilers] section and the `CanAutoInstall` key in the [Cmp:XXX] sections.

The file has the following sections.

#### [Cmp:XXX] sections

There is one of these sections for each compiler known to CodeSnip. Each section describes how CodeSnip should use the compiler, or indicates that the compiler is not available.

The actual name of a section is found by replacing XXX with one of the following values:

- D2 – Delphi 2
- D3 – Delphi 3
- D4 – Delphi 4
- D5 – Delphi 5
- D6 – Delphi 6
- D2005w32 – Windows 32 personality of Delphi 2005
- D2006w32 – Windows 32 personality of Delphi 2006
- D2007 – Windows 32 personality of Delphi 2007
- D2009w32 – Windows 32 personality of Delphi 2009
- D2010 – Delphi 2010
- DXE – Delphi XE
- DXE2 – Delphi XE2
- DXE3 – Delphi XE3
- DXE4 – Delphi XE4
- DXE5 – Delphi XE5
- DXE6 – Delphi XE6
- DXE7 – Delphi XE7
- DXE8 – Delphi XE8
- D10S – Delphi 10 Seattle
- D101B – Delphi 10.1 Berlin
- D102T – Delphi 10.2 Tokyo
- D103R – Delphi 10.3 Rio
- D104S – Delphi 10.4 Sydney
- D11A – Delphi 11.x Alexandria
- D12Y – Delphi 12 Athens
- FPC – Free Pascal

Name / Value pairs (same for all sections unless noted otherwise):

`ExePath` (String)
  Path to the compiler's executable file. Empty string if the compiler not configured.
`Displayable` (Boolean)
  Indicates whether the compiler's compilation results for a snippet should be displayed in the UI.
`Namespaces` (String)
  Space separated list of the namespaces containing Delphi's RTL units. A missing or empty string value ⇒ use the default RTL namespaces for the compiler.
  Relates to the Delphi XE2 and later compilers. If the value is present, it is ignored for earlier compilers and Free Pascal.
`Prefix0` (String)
  Double quoted prefix to the text output by the compiler to indicate fatal compiler errors. If not present the default is `Fatal:` .
`Prefix1` (String)
  Double quoted prefix to the text output by the compiler to indicate standard compiler errors. If not present the default is `Error:` .
`Prefix2` (String)
  Double quoted prefix to the text output by the compiler to indicate warnings. If not present the default is `Warning:` .
`Switches` (String)
  Comma separated list of compiler switches. A missing or empty string value ⇒ use default switches for the compiler.
`SearchDirCount` (Integer)
  Count of the number of search directories configured for the compiler.
`SearchDirXXX` (String)
  One entry for each search directory configured for the compiler where `XXX` ranges from `0` to `SearchDirCount` - `1`.
  Each entry contains a fully specified directory path.
`CanAutoInstall` (Boolean)
  Determines whether the compiler can be automatically detected and registered by CodeSnip.
  Applies to Delphi compilers only, not to Free Pascal.

#### [Compilers] section

This section records configuration information that applies to all, or multiple, compilers.

Name / Value pairs:

`PermitStartupDetection` (Boolean)
  Determines whether CodeSnip should detect, and potentially register, any Delphi compilers that are installed on the user's system but not registered with the program.
  Does not apply to the Free Pascal compiler.

#### [Database] section

This section records database customisations.

Name / Value pairs:

`UserDataDir` (String)
  Specifies the directory that contains the user database. This value is only present if the user has moved the database from its default location.
  Note: The value is ignored in the portable version of CodeSnip.

#### [DuplicateSnippet] section

Persists the state of controls in the Duplicate Snippet dialogue box.

Name / Value pairs:

`EditSnippetOnClose` (Boolean)
  Stores the state of the Edit in Snippets Editor check box.

#### [Favourites] section

Persists the state of controls in Favourites dialogue box.

Name / Value pairs:

`DisplayInNewTabs` (Boolean)
  Stores the state of the Open favourites in new tabs check box.
`InactiveAlphaBlendValue` (Integer)
  Stores the alpha blend value (i.e. the degree of transparency) of the Favourites dialogue box when it is not active. Values should be in the range `128` to `255`.

#### [FindCompiler] section

Provides information about the last compiler search that was run.

Name / Value pairs:

`D2` (Boolean)
  Indicates whether Delphi 2 was included in the search.
`D3` (Boolean)
  Indicates whether Delphi 3 was included in the search.
`D4` (Boolean)
  Indicates whether Delphi 4 was included in the search.
`D5` (Boolean)
  Indicates whether Delphi 5 was included in the search.
`D6` (Boolean)
  Indicates whether Delphi 6 was included in the search.
`D7` (Boolean)
  Indicates whether Delphi 7 was included in the search.
`D2005w32` (Boolean)
  Indicates whether the Win32 personality of Delphi 2005 was included in the search.
`D2006w32` (Boolean)
  Indicates whether the Win32 personality of Delphi 2006 was included in the search.
`D2007` (Boolean)
  Indicates whether the Win32 personality of Delphi 2007 was included in the search.
`D2009w32` (Boolean)
  Indicates whether the Win32 personality of Delphi 2009 was included in the search.
`D2010` (Boolean)
  Indicates whether Delphi 2010 was included in the search.
`DXE` (Boolean)
  Indicates whether Delphi XE was included in the search.
`DXE2` (Boolean)
  Indicates whether Delphi XE2 was included in the search.
`DXE3` (Boolean)
  Indicates whether Delphi XE3 was included in the search.
`DXE4` (Boolean)
  Indicates whether Delphi XE4 was included in the search.
`DXE5` (Boolean)
  Indicates whether Delphi XE5 was included in the search.
`DXE6` (Boolean)
  Indicates whether Delphi XE6 was included in the search.
`DXE7` (Boolean)
  Indicates whether Delphi XE7 was included in the search.
`DXE8` (Boolean)
  Indicates whether Delphi XE8 was included in the search.
`D10S` (Boolean)
  Indicates whether Delphi 10 Seattle was included in the search.
`D101B` (Boolean)
  Indicates whether Delphi 10.1 Berlin was included in the search.
`D102T` (Boolean)
  Indicates whether Delphi 10.2 Tokyo was included in the search.
`D103R` (Boolean)
  Indicates whether Delphi 10.3 Rio was included in the search.
`D104S` (Boolean)
  Indicates whether Delphi 10.4 Sydney was included in the search.
`D11A` (Boolean)
  Indicates whether Delphi 11.x Alexandria was included in the search.
`D12Y` (Boolean)
  Indicates whether Delphi 12 Athens was included in the search.
`FPC` (Boolean)
  Indicates whether Free Pascal was included in the search.
`Option` (Integer)
  Code that describes the kind of compilation result to be searched for: `0` ⇒ snippet compiles OK; `1` ⇒ snippet compiles without warnings; `2` ⇒ snippet compiles with warning(s); `3` ⇒ snippet fails to compile; `4` ⇒ snippet not tested.
`Logic` (Integer)
  Code that describes the search logic to use: `0` ⇒ "and"; `1` ⇒ "or".

#### [FindText] section

Provides information about last the last text search that was run and records a history of search terms.

Name / Value pairs:

`HistoryCount` (Integer)
  Count of items in the search term history.
`HistoryXXX` (String)
  One entry for each search term in the history where `XXX` ranges from `0` to `HistoryCount` - `1`.
  Each entry contains one or more spaced separated search words.
`MatchCase` (Boolean)
  One of the search options. Indicates whether searches are case sensitive.
`WholeWord` (Boolean)
  One of the search options. Indicates whether searches match whole words only.
`Logic` (Integer)
  Code that describes the search logic to use: `0` ⇒ "and"; `1` ⇒ "or".

#### [FindXRefs] section

Provides information about the last snippet cross reference search that was run.

Name / Value pairs:

`IncludeSnippet` (Boolean)
  Indicates whether to include the snippet for which the search is being performed in the search result.
`Required` (Boolean)
  Indicates whether snippets that are required to compile the selected snippet are included in the search results.
`RequiredRecurse` (Boolean)
  Indicates whether the search for required snippets is recursive. Ignored if `Required` = `False`.
`RequiredReverse` (Boolean)
  Indicates whether snippets that depend on the searched-for snippet are included in the search results.
`SeeAlso` (Boolean)
  Indicates whether snippets that are cross referenced by the selected snippet are included in the search results.
`SeeAlsoRecurse` (Boolean)
  Indicates whether the search for cross-referenced snippets is recursive. Ignored if `SeeAlso` = `False`.
`SeeAlsoReverse` (Boolean)
  Indicates whether snippets that cross-reference the searched-for snippet are included in the search results.

#### [IniFile] section

Provides information about the config file and installed version of CodeSnip.

Name / Value pairs:

`Version` (Integer)
  The version number of the config file. Incremented whenever the file format changes. If this section or this value is missing then the default value is `1`.
  The current value is `19`.
`ProgramVersion` (String)
  Internal version number of the currently installed version of CodeSnip as a dotted quad.

#### [Prefs] section

Stores information about the Preferences dialogue box itself, rather than actual preferences data. Actual preference data is stored in sections with names like [Prefs:XXX] where XXX is a preferences sub-section.

Name / Value pairs:

`LastTab` (string)
  Name of the tab that was open when the dialogue box was last closed. May be the empty string if the dialogue box has not yet been opened.

#### [Prefs:CodeGen] section

Stores source code generation preferences. Used in test compilations or when generating user defined units.

Name / Value pairs:

`EmitWarnings` (Boolean)
  Flag indicating whether directives are emitted to switch specified warnings on or off. `True` ⇒ emit directives; `False` ⇒ do not emit directives.
`WarningCount` (Integer)
  Number of warning directives supported.
`WarningXXX.Symbol` (String)
  One entry for each supported warning directive, where `XXX` ranges from `0` to `WarningCount` - `1`.
  Each entry contains the symbol representing a warning as used in Delphi's $WARN directive.
`WarningXXX.MinCompiler` (Float)
  One entry for each supported warning directive, where `XXX` ranges from `0` to `WarningCount` - `1`.
  Records the earliest version of Delphi that supports the warning. This version number is a decimal value containing the compiler version number as specified by Delphi's CompilerVersion constant. Must be 14.0 (Delphi 6) or higher.
`WarningXXX.State` (Boolean)
  One entry for each supported warning directive, where `XXX` ranges from `0` to `WarningCount` - `1`.
  Indicates whether the warning should be switched on or off. `True` ⇒ switch on; `False` ⇒ switch off.

#### [Prefs:Display] section

Stores preferences for the main display.

Name / Value pairs:

`OverviewStartState` (Integer)
  Code that indicates the desired start state of the overview pane treeview: `0` ⇒ fully expanded; `1` ⇒ fully collapsed.
`ShowEmptySections` (Boolean)
  Flag that specifies whether empty sections should be displayed in the overview pane. `True` ⇒ display empty sections; `False` ⇒ hide empty sections.
`ShowNewSnippetsInNewTabs` (Boolean)
  Flag that specifies how newly created snippets and categories are displayed in the detail pane. `True` ⇒ a new tab is created for each new item; `False` ⇒ new items overwrite the current item in the selected tab.
`MainDBHeadingColour` (Integer)
  Colour to be used to display headings of items from the main database.
`UserDBHeadingColour` (Integer)
  Colour to be used to display headings of items from the user database.
`SourceCodeBGColour` (Integer)
  Colour to be used for the background of source code in the main display.
`MainDBHeadingCustomColourCount` (Integer)
  Number of recorded custom colours for main database item headings.
`MainDBHeadingCustomColourXXX` (String)
  One entry for each recorded custom colour for main database item headings, where `XXX` ranges from `0` to `MainDBHeadingCustomColourCount` - `1`.
  The value is a definition of a custom colour in the format used by the TColorDialog dialogue box. This format is `ColourID=ColourNum` where ColourID is a value from `ColorA` to `ColorP` and ColourNum is the hex representation of the colour.
`UserDBHeadingCustomColourCount` (Integer)
  Number of recorded custom colours for user database item headings.
`UserDBHeadingCustomColourXXX` (String)
  One entry for each recorded custom colour for user database item headings, where `XXX` ranges from `0` to `UserDBHeadingCustomColourCount` - `1`.
  The value is a definition of a custom colour in the format used by the TColorDialog dialogue box. This format is `ColourID=ColourNum` where ColourID is a value from `ColorA` to `ColorP` and ColourNum is the hex representation of the colour.
`SourceCodeBGCustomColourCount` (Integer)
  Number of recorded custom colours for the source code background in the main display.
`SourceCodeBGCustomColourXXX` (String)
  One entry for each recorded custom colour for the source code background in the main display, where `XXX` ranges from `0` to `SourceCodeBGCustomColourCount` - `1`.
  The value is a definition of a custom colour in the format used by the TColorDialog dialogue box. This format is `ColourID=ColourNum` where ColourID is a value from `ColorA` to `ColorP` and ColourNum is the hex representation of the colour.
`OverviewFontSize` (Integer)
  Size of font to be used in overview pane tree view. If missing or empty the default value is the default font size of the operationg system.
`DetailFontSize` (Integer)
  Size of font to be used in detail pane for all text except for source code. If missing or empty the default value is the default content font size of the operating system.

#### [Prefs:General] section

Stores miscellaneous application preferences.

Name / Value pairs:

`Units` (Integer)
  A code that records the units of measurement used by the application: `0` ⇒ inches; `1` ⇒ millimeters.

#### [Prefs:Hiliter] section

Stores preferences that define the properties of one or more syntax highlighters. Also records information about the custom colours available when configuring the highlighters.

Name / Value pairs:

`FontSize` (Integer)
  Size of the current highlighter font in points.
`FontName` (String)
  Name of the current highlighter font.
`ElemXXX.Color` (Integer)
  One entry for each of the 12 source code elements recognised by the current syntax highlighter. `XXX` ranges from `0` to `11`.
  Each value is a colour of a source code element as an integer representation of a Delphi TColor value. If the colour is not specified the value is the integer representation of clNone.
`ElemXXX.Style` (Integer)
  One entry for each of the 12 source code elements recognised by the current syntax highlighter. `XXX` ranges from `0` to `11`.
  Each value is a bitmask representing the font styles used for the source code element.
`NamedHiliterCount` (Integer)
  Number of custom (or "Named") syntax highlighters defined by the user.
`HilterNameXXX` (String)
  One entry for each custom syntax highlighter, where `XXX` ranges from `0` to `NamedHiliterCount` - `1`.
  Each value is the name used to identify the syntax highlighter with the same index. (See the various `NamedHiliterXXX` entries below.)
`NamedHiliterXXX.FontSize` (Integer)
  One entry for each custom syntax highlighter, where `XXX` ranges from `0` to `NamedHiliterCount` - `1`.
  Each value is the size of the corresponding syntax highlighter's font, in points.
`NamedHiliterXXX.FontName` (String)
  One entry for each custom syntax highlighter, where `XXX` ranges from `0` to `NamedHiliterCount` - `1`.
  Each value is the name of the corresponding syntax highlighter's font.
`NamedHiliterXXX.ElemYYY.Color` (Integer)
  There is an entry for each source code element of each custom synax highliter. `XXX` represents the index of the corresponding syntax highlighter and ranges from `0` to `NamedHiliterCount` - `1`. For each value of `XXX` there are 12 `.ElemYYY` values, with `YYY` ranging from `0` to `11`.
  Each value specifies the colour of a source code element as an integer representations of a Delphi TColor value. If the colour is not specified the value is the integer representation of clNone.
`NamedHiliterXXX.ElemYYY.Style` (Integer)
  There is an entry for each source code element of each custom synax highliter. `XXX` represents the index of the corresponding syntax highlighter and ranges from `0` to `NamedHiliterCount` - `1`. For each value of `XXX` there are 12 `.ElemYYY` values, with `YYY` ranging from `0` to `11`.
  Each value contains a bitmask representing the font style of a source code element.
`CustomColourCount` (Integer)
  Number of recorded custom colours available for use by highlighter elements.

`CustomColourXXX` (String)

  One entry for each recorded custom colour, where `XXX` ranges from `0` to `CustomColourCount` - `1`.
  The value is a definition of a custom colour in the format used by the TColorDialog dialogue box. This format is `ColourID=ColourNum` where ColourID is a value from `ColorA` to `ColorP` and ColourNum is the hex representation of the colour.

#### [Prefs:Printing] section

Stores default printing preferences.

Name / Value pairs:

`UseColor` (Boolean)
  Flag that indicates whether printing is to be in colour: `True` ⇒ print in colour; `False` ⇒ print in black and white.
`SyntaxPrint` (Boolean)
  Flag that indicates whether source code in printed output is to be syntax highlighted: `True` ⇒ use syntax highlighting; `False` ⇒ do not syntax highlight.
`LeftMargin` (Float)
  Size of a printed page's left margin in mm.
`TopMargin` (Float)
  Size of a printed page's top margin in mm.
`RightMargin` (Float)
  Size of a printed page's right margin in mm.
`BottomMargin` (Float)
  Size of a printed page's bottom margin in mm.

#### [Prefs:SnippetPageStructure] section

Stores preferences that describes the customisation of pages displayed in the details pane for different snippet kinds.

Name / Value pairs:

`PageKindXXX` (String)
  One entry for each snippet kind where `XXX` is the ordinal value of the snippet kind.
  Each entry's value describes the structure of the details pane page that displays snippets of the related kind. The value is a comma separated list of zero or more names, each of which denotes a page component. Components are displayed in the order they are listed. Valid component names are:
  - `Description`
  - `SourceCode`
  - `Kind`
  - `Category`
  - `Units`
  - `Depends`
  - `XRefs`
  - `CompileResults`
  - `ExtraInfo`

#### [Prefs:SourceCode] section

Stores preferences that specify how source code is exported by default.

Name / Value pairs:

`FileType` (Integer)
  A code that determines type of exported files: `0` ⇒ plain text; `1` ⇒ Pascal; `2` ⇒ HTML; `3` ⇒ rich text (RTF).
`CommentStyle` (Integer)
  A code that determines the style of documentation comments used for snippets in output files: `0` ⇒ no documentation comment; `1` ⇒ a description of the snippet apperars between the snippet's prototype and the body of the code; `2` ⇒ the description of the snippet immediately precedes it.
`TruncateComments` (Boolean)
  Flag indicating whether multi-paragraph snippet descriptions are to be truncated to the first paragraph only in documentation comments. `True` ⇒ truncate the description; `False` ⇒ use the full description.
`UseSyntaxHiliting` (Boolean)
  Flag indicating whether source code is to be syntax highlighted. `True` ⇒ use syntax highlighting; `False` ⇒ do not syntax highlight.

#### [UnitList] section

Records the names of the units that appear in the Units check box list on the References tab of the Edit Snippet dialoogue box.

Name / Value pairs:

`Count` (Integer)
  The number of units in the list.
`UnitXXX` (String)
  One entry for each unit, where `XXX` range from `0` to `Count` - `1`.

Note that some "reserved" unit names that always appear in the list box are not recorded in settings. They are:

- SysUtils
- Classes
- Windows
- Graphics

If this section is missing or has no units listed then CodeSnip defaults to using the following units in addition to the "reserved" units:

- Controls
- Messages
- Types
- ShlObj
- ShellAPI
- ActiveX
- Math

These default unit names will be included in this section the first time it is written.

#### [WindowState:XXX] sections

There is one of these section for each window that stores its state and size in the config file. XXX is a sub-section placeholder and is replaced by a unique name representing the window whose state is stored.

Some windows also store custom information in their sub-section that is unique to them. Values common to all sub-sections are described first, followed by additional details of any sub-section storing custom information.

##### Common values

These values do, or can, appear in any sub-section.

Name / Value pairs:

`Left` (Integer)
  Location of the left side of the window on screen in pixels.
`Top` (Integer)
  Location of the top of the window on screen in pixels.
`Width` (Integer)
  Width of the window in pixels.
  Not used for fixed size windows.
`Height` (Integer)
  Height of the window in pixels.
  Not used for fixed size windows.
`State` (Integer)
  Value of that describes the state of window: `0` ⇒ normal state; `1` ⇒ minimized; `2` ⇒ maximized.
  Not used for dialogue boxes and other windows that are always displayed in the normal state.

##### [WindowState:MainForm] sub-section

These values are used only in the MainForm sub-section.

Name / Value pairs:

`SplitterPos` (Integer)
  Position of the main window's vertical splitter control, in pixels from the left of the window client area.
`OverviewTab` (Integer)
  Index of the selected tab in the overview pane.