DelphiDabbler CodeSnip
File Format Documentation

Main Database Files

Introduction

The Code Snippets database is stored in a set of .ini files with associated data files located in the main database directory. Two subsidiary text files containing credits are also included.

The master data file is named categories.ini. This lists the database categories. There is another .ini file for each category which stores information about all the snippets in the category.

The source code for each snippet is stored in separate data files – one or more per snippet. This snippet file is referenced in the relevant category .ini file.

The credits text files contain lists of names.

Encoding

CodeSnip v4 stores all main database files, including the subsidiary text files, using UTF-8 encoding. Files are saved with the UTF-8 preamble (BOM).

Prior to CodeSnip v4 local database files were encoded using the system default ANSI code page.

CodeSnip v4 must be able to work with both encodings because it may inherit or have to use a database downloaded by a v3 or earlier version of the program.

File Format

Master Data File

This file has a simple format. Each section is named after a category id, i.e. the id by which the category is referred to in the database. Each section of the .ini file has a value containing the description of the category and another that names the category's .ini file. Here is the format of a section:

[cat-id]
Desc=Category description
Ini=ini-file-name

and here is an example (this is a copy of the "Date and Time" category's entry):

[date]
Desc=Date and Time
Ini=date.ini

Category ini files

Each section in these files defines a snippet and has the following content:

[snippet-name]
DisplayName=<snippet-display-name>
Desc=<description-text>
DescEx=<description-REML>
Snip=<snippet-file-name>
Units=<required-units>
Depends=<required-snippets>
SeeAlso=<cross-referenced-snippets>
Credits=<credits-text>
Credits_URL=<url-used-in-credits>
Comments=<comments-text>
Delphi2=<Y|N|Q|W>
Delphi3=<Y|N|Q|W>
Delphi4=<Y|N|Q|W>
Delphi5=<Y|N|Q|W>
Delphi6=<Y|N|Q|W>
Delphi7=<Y|N|Q|W>
Delphi2005Win32=<Y|N|Q|W>
Delphi2006Win32=<Y|N|Q|W>
Delphi2007=<Y|N|Q|W>
Delphi2009Win32=<Y|N|Q|W>
Delphi2010=<Y|N|Q|W>
DelphiXE=<Y|N|Q|W>
DelphiXE2=<Y|N|Q|W>
DelphiXE3=<Y|N|Q|W>
DelphiXE4=<Y|N|Q|W>
DelphiXE5=<Y|N|Q|W>
DelphiXE6=<Y|N|Q|W>
DelphiXE7=<Y|N|Q|W>
DelphiXE8=<Y|N|Q|W>
Delphi10S=<Y|N|Q|W>
FPC=<Y|N|Q|W>
Extra=<extra-info-REML>
StandardFormat=<0|1>
Kind=<freeform|routine|type|const|class|unit>
TestInfo=<none|basic|advanced>
MinVer=<version-number>

The sections in these files are named with a unique name that identifies a snippet. This must be a valid Unicode Pascal identifier. The values have the following purpose:

DisplayName
Display name of snippet. If present this value is used in the program GUI as the snippet's name. The value is optional. If not present the name of the section is used as the display name. There are no restriction on the characters used.
Supported from CodeSnip v4.0 beta 1 and ignored by earlier versions which always use the section name as display name.
Desc
Description of the snippet as plain text. Ignored by versions of CodeSnip that recognise DescEx if that field is present.
DescEx
Formatted description of the snippet using REML code. May be empty, in which case the Desc field is used. The Desc field is ignored if DescEx has a value.
Supported from CodeSnip v4.0 beta 1.
Snip
Name of file containing source code. Contains no file path information.
Units
Comma separated list of units required by the snippet. May be empty if no units are required. The System unit is assumed and does not need to be specified.
Depends
Comma separated list of snippets that are required to compile this snippet. May be empty if there are no dependencies. Must not cause a circular reference back to this snippet.
SeeAlso
Comma separated list of cross-referenced snippets. May be empty.
Credits
Text string that notes any credits / acknowledgements. May be empty.
Credits may optionally contain one (and only one) section of text delimited by "[" and "]" characters that indicate the presence of a hyperlink. The text enclosed by "[" and "]" is used for the text of the hyperlink. If present the Credits_URL field must contain the URL of the hyperlink.
Credits is ignored by versions of CodeSnip that recognise the Extra field unless the Extra field is empty.
Credits_URL
The URL used in any hyperlink present in the Credits field. Should be empty if Credits contains no hyperlink section.
Comments
Text string containing any additional comments about the snippet. May be empty.
Ignored by versions of CodeSnip that recognise the Extra field unless the Extra field is empty.
DelphiXXX & FPC
This related group of values describe compilation results for the snippets on various compilers. Valid value names are:
Valid values for these fields are:
If not present, the compile result is assumed to be "Q"
From CodeSnip v3.8.9 a compile result of "W" is treated as if it were "Y".
Any compiler not recognised by a given version of CodeSnip is ignored.
Extra
Provides extra information about the snippet. Can be empty or be a string of REML code.
If empty the extra information is generated from any Comments and Credits / Credits_URL values.
This value was supported from CodeSnip v2.2.5.
StandardFormat
Flag indicating if a snippet is in "standard format". Valid values are:
If not present then StandardFormat = "1" is assumed.
This value was supported from CodeSnip v2.0.
From CodeSnip v3.0 StandardFormat is ignored if the Kind value is present. If Kind is not present then StandardFormat = "0" is read as Kind = "freeform" and StandardFormat = "1" is read as Kind = "routine".
Kind
Kind of code snippet. Valid values are:
If Kind is not present and StandardFormat is then StandardFormat = "1" implies Kind = "routine" and StandardFormat = "0" implies Kind = "freeform". If neither Kind nor StandardFormat are present then Kind defaults to "routine".
This value was supported from CodeSnip v3.0.
TestInfo
Testing information for snippets. Valid values are:
If TestInfo is not present then its value defaults to "basic". This is because, until the release of CodeSnip v4.0, all snippets had undergone at least basic testing.
This value was supported from CodeSnip v4.0.
MinVer
Ignored.
This value was used by a now defunct version of the online Code Snippets Database, but is no longer used.

Each value should occur only once. If more than one value of the same type is present the result is not defined and may change between program versions.

Pre-processor directives

A simple pre-processor was added to CodeSnip v3 and later that can process special pre-processor instructions contained in .ini files. The pre-processor symbols are ignored by CodeSnip versions earlier than v3. These symbols allow the program's version number to be tested and different parts of the file to be read or ignored accordingly.

Pre-processor instructions all begin with ";", the .ini file comment character, followed by a "#" and then the instruction name. Valid instructions are:

if-ver-eq <version>
Checks if application version is equal to <version>.
if-ver-neq <version>
Checks if application version is not equal to <version>.
if-ver-lt <version>
Checks if application version is less than <version>.
if-ver-lte <version>
Checks if application version is less than or equal to <version>.
if-ver-gt <version>
Checks if application version is greater than <version>.
if-ver-gte <version>
Checks if application version is greater than or equal to <version>.
if-ver-inrange <version-lo> <version-hi>
Checks if application version is in the range of versions specified from <version-lo> to <version-hi>, inclusive.
end-if
Ends a block started by any of the if-xxx instructions above. The block of text is only evaluated if the if-xxx instruction evaluates true.

† Due to a bug going back to CodeSnip v3.0 if-ver-gte and if-ver-lte have never worked correctly: they have always been interpreted as if-ver-gt and if-ver-lt respectively. A fix to this could now cause more problems than it solves in older version of CodeSnip, so the implementation of the problematic directives has been removed from later versions of the program and all occurrences of the directives in the database have been replaced by suitable if-ver-inrange directives.

In all cases version numbers are dotted quads of the form X.X.X.X where X is a sequence of digits. All except the first digit can be left out: omitted digits are assumed to be zero, so that 1.0.0.0, 1.0.0, 1.0 and 1 are all equivalent.

if-ver-lt 3 can be used to ignore a whole snippet definition in a normal .ini file, leaving the possibility of having a duplicate definition for CodeSnip v3 or later stored in a matching .3.ini file. E.g.

date.ini:

;#if-ver-lt 3
[Snippet1]
Desc="My description"
Snip=044.dat
...
;#end-if

date.3.ini:

[Snippet1]
Desc="My second description"
Snip=044.3.dat
...

Additional .ini Files For CodeSnip v3 and v4

From CodeSnip v3 additional .ini files with .3 interposed between the file name and extension are supported (e.g. category.3.ini and date.3.ini are valid names).

From v4 similar files using the interposed .4 extension are supported in addition to the .3 files (e.g winsys.4.ini).

CodeSnip concatenates all .ini files with the same base name before analysing the file. For example if date.ini, date.3.ini and date.4.ini all exist then date.3.ini and date.4.ini are appended to date.ini before the files are analysed.

The .3 "inner" extension was provided for category files so that constant and type definition snippets could be hidden from CodeSnip versions below v3 but be visible to CodeSnip v3 and later. The new style constant and type definition snippets are only recorded in .3 style files.

categories.3.ini has been provided to add any sections that need to be hidden from CodeSnip versions before v3. The "types" and "consts" sections are recorded in this file.

.4 "inner" extensions are there to support any CodeSnip v4 specific features that can't be hidden from earlier versions.

Finally, it is possible that a name.3.ini or name.4.ini file will exist with no matching name.ini. In this case categories.ini (or categories.3.ini) must still refer to name.ini, not name.3.ini or name.4.ini. The program works out which files to load.

Source Code Files

Source code is stored separately from the category .ini files. Each snippet has its own uniquely named file. Files can have any name providing it doesn't clash with the master file name or the names of the category files. By convention, source code files are named numerically in sequence and have a .dat file extension. So 102.dat is a typical source code file name. Sometimes there is a separate file for later versions of CodeSnip, so an occasional file named, for example, 102.3.dat may be found.

Source code files are referenced by the Snip field in category .ini files.

Subsidiary "Credits" Text Files

There are two credits files, contrib.txt and testers.txt that list the people who have contributed code to the main database or helped to test the code, respectively.

Each file is simply a list of names, each name on a separate line.

The credits files stand alone from the other files in the database in that they are not referenced by, and do not reference, any of the other files.