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.
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.
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
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:
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.
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:
† 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 ...
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 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.
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.