<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
* This Source Code Form is subject to the terms of the Mozilla Public License,
* v. 2.0. If a copy of the MPL was not distributed with this file, You can
* obtain one at http://mozilla.org/MPL/2.0/
*
* Copyright (C) 2012-2013, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* CodeSnip File Format Documentation: Main Database
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>
CodeSnip File Format Documentation - Main Database
</title>
<link
rel="stylesheet"
type="text/css"
media="screen"
href="main.css"
/>
</head>
<body>
<div class="title">
<div>
DelphiDabbler CodeSnip
</div>
<div class="subtitle">
File Format Documentation
</div>
</div>
<h1>
Main Database Files
</h1>
<h2>
Introduction
</h2>
<p>
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.
</p>
<p>
The master data file is named <code>categories.ini</code>. This lists the
database categories. There is another .ini file for each category which stores
information about all the snippets in the category.
</p>
<p>
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.
</p>
<p>
The credits text files contain lists of names.
</p>
<h2>
Encoding
</h2>
<p>
CodeSnip 4 stores all main database files, including the subsidiary text
files, using UTF-8 encoding. Files are saved with the UTF-8 preamble (BOM).
</p>
<p>
Prior to CodeSnip v4 local database files were encoded using the system
default ANSI code page.
</p>
<p>
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.
</p>
<h2>
File Format
</h2>
<h3>
Master Data File
</h3>
<p>
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:
</p>
<pre class="indent">[cat-id]
Desc=Category description
Ini=ini-file-name</pre>
<p>
and here is an example (this is a copy of the "Date and Time"
category's entry):
</p>
<pre class="indent">[date]
Desc=Date and Time
Ini=date.ini</pre>
<h3>
Category ini files
</h3>
<p>
Each section in these files defines a snippet and has the following content:
</p>
<pre class="indent">[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>
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></pre>
<p>
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:
</p>
<dl>
<dt>
<em>DisplayName</em>
</dt>
<dd>
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 earler
versions which always use the section name as display name.
</dd>
<dt>
<em>Desc</em>
</dt>
<dd>
Description of the snippet as plain text. Ignored by versions of CodeSnip
that recognise <em>DescEx</em> if that field is present.
</dd>
<dt>
<em>DescEx</em>
</dt>
<dd>
Formatted description of the snippet using <acronym
title="REML is decribed in the program's help file"
>REML</acronym> code. This value was supported from CodeSnip v4.0 beta 1.
May be empty, in which case the <em>Desc</em> field is used. The
<em>Desc</em> field is ignored if <em>DescEx</em> has a value.
</dd>
<dt>
<em>Snip</em>
</dt>
<dd>
Name of file containing source code. Contains no file path information.
</dd>
<dt>
<em>Units</em>
</dt>
<dd>
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.
</dd>
<dt>
<em>Depends</em>
</dt>
<dd>
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.
</dd>
<dt>
<em>SeeAlso</em>
</dt>
<dd>
Comma separated list of cross-referenced snippets. May be empty.
</dd>
<dt>
<em>Credits</em>
</dt>
<dd>
<div class="half-spaced">
Text string that notes any credits / acknowledgements. May be empty.
</div>
<div class="half-spaced">
<em>Credits</em> 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
<em>Credits_URL</em> field must contain the URL of the hyperlink.
</div>
<div class="half-spaced">
<em>Credits</em> is ignored by versions of CodeSnip that recognise the
<em>Extra</em> field unless the <em>Extra</em> field is empty.
</div>
</dd>
<dt>
<em>Credits_URL</em>
</dt>
<dd>
The URL used in any hyperlink present in the <em>Credits</em> field. May be
empty if <em>Credits</em> contains no hyperlink section.
</dd>
<dt>
<em>Comments</em>
</dt>
<dd>
Text string containing any additional comments about the snippet. May be
empty. Ignored by versions of CodeSnip that recognise the <em>Extra</em>
field unless the <em>Extra</em> field is empty.
</dd>
<dt>
<em>DelphiXXX</em> & <em>FPC</em>
</dt>
<dd>
<div class="half-spaced">
This related group of values describe compilation results for the snippets
on various compilers. Valid value names are:
</div>
<ul class="unspaced">
<li>
<em>Delphi2</em> – Delphi 2 compiler
</li>
<li>
<em>Delphi3</em> – Delphi 3 compiler
</li>
<li>
<em>Delphi4</em> – Delphi 4 compiler
</li>
<li>
<em>Delphi5</em> – Delphi 5 compiler
</li>
<li>
<em>Delphi6</em> – Delphi 6 compiler
</li>
<li>
<em>Delphi7</em> – Delphi 7 compiler
</li>
<li>
<em>Delphi2005Win32</em> – Win32 personality of Delphi 2005
compiler
</li>
<li>
<em>Delphi2006Win32</em> – Win32 personality of Delphi 2006
compiler
</li>
<li>
<em>Delphi2007</em> – Delphi 2007 compiler
</li>
<li>
<em>Delphi2009Win32</em> – Win32 personality of Delphi 2009
compiler
</li>
<li>
<em>Delphi2010</em> – Delphi 2010 compiler
</li>
<li>
<em>DelphiXE</em> – Delphi XE compiler
</li>
<li>
<em>DelphiXE2</em> – Delphi XE2 compiler
</li>
<li>
<em>DelphiXE3</em> – Delphi XE3 compiler
</li>
<li>
<em>DelphiXE4</em> – Delphi XE4 compiler
</li>
<li>
<em>FPC</em> – Free Pascal compiler
</li>
</ul>
<div class="half-spaced">
Valid values for these fields are:
</div>
<ul class="unspaced">
<li>
"Y" – compiles on the compiler
</li>
<li>
"N" – does not compile on the compiler
</li>
<li>
"W" – compiles with warnings on the compiler
</li>
<li>
"Q" – compilation result unknown
</li>
</ul>
<div class="half-spaced">
If not present, the compile results is assumed to be "Q"
</div>
<div class="half-spaced">
From CodeSnip v3.8.9 a compile result of "W" is treated as if it
were "Y".
</div>
</dd>
<dt>
<em>Extra</em>
</dt>
<dd>
<div class="half-spaced">
Provides extra information about the snippet. Can be empty or be a string
of <acronym
title="REML is decribed in the program's help file"
>REML</acronym> code. This value was supported from CodeSnip v2.2.5.
</div>
<div class="half-spaced">
If empty the extra information is generated from the <em>Comments</em> and
<em>Credits</em> / <em>Credits_URL</em> values.
</div>
</dd>
<dt>
<em>StandardFormat</em>
</dt>
<dd>
<div class="half-spaced">
Flag indicating if a snippet is in "standard format". This value
was supported from CodeSnip v2.0. Valid values are:
</div>
<ul class="unspaced">
<li>
"0" – no
</li>
<li>
"1" – yes.
</li>
</ul>
<div class="half-spaced">
If not present then <em>StandardFormat</em> = "1" is assumed.
</div>
<div class="half-spaced">
From CodeSnip v3.0 <em>StandardFormat</em> is ignored if the <em>Kind</em>
value is present. If <em>Kind</em> is not present then
<em>StandardFormat</em> = "0" is read as <em>Kind</em> =
"freeform" and <em>StandardFormat</em> = "1" is read
as <em>Kind</em> = "routine".
</div>
</dd>
<dt>
<em>Kind</em>
</dt>
<dd>
<div class="half-spaced">
Kind of code snippet. This value was supported from CodeSnip v3.0. Valid
values are:
</div>
<ul class="unspaced">
<li>
"freeform" – a freeform snippet that doesn't conform to
any type other supported type
</li>
<li>
"routine" – a Pascal routine (function or procedure)
</li>
<li>
"type" – a simple Pascal type definition
</li>
<li>
"const" – a Pascal constant definition
</li>
<li>
"class" – a Pascal class or advanced record definition
and implementation.
</li>
<li>
"unit" – a complete Pascal unit
</li>
</ul>
<div class="half-spaced">
If <em>Kind</em> is not present and <em>StandardFormat</em> is then
<em>StandardFormat</em> = "1" implies <em>Kind</em> =
"routine" and <em>StandardFormat</em> = "0" implies
<em>Kind</em> = "freeform". If neither <em>Kind</em> nor
<em>StandardFormat</em> are present then <em>Kind</em> defaults to
"routine".
</div>
</dd>
<dt>
<em>TestInfo</em>
</dt>
<dd>
<div class="half-spaced">
Testing information for snippets. This value was supported from CodeSnip
v4.0. Valid values are:
</div>
<ul class="unspaced">
<li>
"none" – the snippet has not been tested
</li>
<li>
"basic" – the snippet has passed some simple testing
</li>
<li>
"advanced" – the snippet has passed more advanced
testing, usually unit tests
</li>
</ul>
<div class="half-spaced">
If <em>TestInfo</em> 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.
</div>
</dd>
<dt>
<em>MinVer</em>
</dt>
<dd>
<div class="pullout">
Used only by the online database and ignored by the CodeSnip program.
</div>
<div class="half-spaced">
Minimum program version or equivalent on which this snippet can be
included in a generated unit.
</div>
<div class="half-spaced">
<em>MinVer</em>'s value is a dotted quad representing a program version
number where any omitted numbers are treated as zeros (e.g. 1, 1.0, 1.0.0
and 1.0.0.0 are all eqivalent).
</div>
<div class="half-spaced">
The online database uses this value so that it can display snippets that
it doesn't know how to include in units. The online database adopts an
equivalent version number to the CodeSnip release with similar qualities
and tests that against <em>MinVer</em>. If <em>MinVer</em> is greater than
the database's assumed version number, the snippet can't be included in
a generated unit.
</div>
</dd>
</dl>
<p>
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.
</p>
<h4>
Pre-processor directives
</h4>
<p>
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.
</p>
<p>
Pre-processor instructions all begin with ";", the .ini file comment
character, followed by a "#" and then the instruction name. Valid
instructions are:
</p>
<dl>
<dt>
<em>if-ver-eq <version></em>
</dt>
<dd>
Checks if application version is equal to <version>.
</dd>
<dt>
<em>if-ver-neq <version></em>
</dt>
<dd>
Checks if application version is not equal to <version>.
</dd>
<dt>
<em>if-ver-lt <version></em>
</dt>
<dd>
Checks if application version is less than <version>.
</dd>
<dt>
<del><em>if-ver-lte <version></em></del>
</dt>
<dd>
<del>Checks if application version is less than or equal to
<version>.</del> †
</dd>
<dt>
<em>if-ver-gt <version></em>
</dt>
<dd>
Checks if application version is greater than <version>.
</dd>
<dt>
<del><em>if-ver-gte <version></em></del>
</dt>
<dd>
<del>Checks if application version is greater than or equal to
<version>.</del> †
</dd>
<dt>
<em>if-ver-inrange <version-lo> <version-hi></em>
</dt>
<dd>
Checks if application version is in the range of versions specified from
<version-lo> to <version-hi>, inclusive.
</dd>
<dt>
<em>end-if</em>
</dt>
<dd>
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.
</dd>
</dl>
<p>
† Due to a bug going back to <em>CodeSnip</em> v3.0 <em>if-ver-gte</em>
and <em>if-ver-lte</em> have never worked correctly: they have always been
interpreted as <em>if-ver-gt</em> and <em>if-ver-lt</em> respectively. A fix
to this could now cause more problems than it solves in older version of
<em>CodeSnip</em>, so the implementation of the directives has been removed
from later versions of the program and all occurrences of the directives in
the database have been replaced by suitable <em>if-ver-inrange</em>
directives.
</p>
<p>
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.
</p>
<p>
<em>if-ver-lt 3</em> 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.
</p>
<p>
<code>date.ini</code>:
</p>
<pre class="indent">
;#if-ver-lt 3
[Snippet1]
Desc="My description"
Snip=044.dat
...
;#end-if</pre>
<p>
<code>date.3.ini</code>:
</p>
<pre class="indent">[Snippet1]
Desc="My second description"
Snip=044.3.dat
...</pre>
<h4>
Additional .ini Files For CodeSnip v3 and v4
</h4>
<p>
From CodeSnip v3 additional .ini files with .3 interposed between the file
name and extension are supported (e.g. <code>category.3.ini</code> and
<code>date.3.ini</code> are valid names).
</p>
<p>
From v4 similar files using the interposed .4 extension are supported in
addition to the .3 files (e.g <code>winsys.4.ini</code>).
</p>
<p>
CodeSnip concatenates all .ini files with the same base name before analysing
the file. For example if <code>date.ini</code>, <code>date.3.ini</code> and
<code>date.4.ini</code> all exist then <code>date.3.ini</code> and
<code>date.4.ini</code> are appended to <code>date.ini</code> before the files
are analysed.
</p>
<p>
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.
</p>
<p>
<code>categories.3.ini</code> 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.
</p>
<p>
.4 "inner" extensions are there to support any CodeSnip v4 specific
features that can't be hidden from earlier versions.
</p>
<p>
Finally, it is possible that a <code>name.3.ini</code> or
<code>name.4.ini</code> file will exist with no matching
<code>name.ini</code>. In this case <code>categories.ini</code> (or
<code>categories.3.ini</code> must still refer to <code>name.ini</code>, not
<code>name.3.ini</code> or <code>name.4.ini</code>. The program works out
which files to load.
</p>
<h3>
Source Code Files
</h3>
<p>
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 file. By
convention, source code files are named numerically in sequence and have a
.dat file extension. So <code>102.dat</code> 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, <code>102.3.dat</code> may be found.
</p>
<p>
Source code files are referenced by the <em>Snip</em> field in category .ini
files.
</p>
<h3>
Subsidiary "Credits" Text Files
</h3>
<p>
There are two credits files, <code>contrib.txt</code> and
<code>testers.txt</code> that list the people who have contributed code to the
main database or helped to test the code, respectively.
</p>
<p>
Each file is simply a list of names, each name on a separate line.
</p>
<p>
The credits file 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.
</p>
</body>
</html>
