The collection is organised as a set of categories, each of which contains one or more code snippets.
Meta data describing the categories and snippets is stored in a set of .ini
files. In addition there are numerous .dat
files, each of which contains the source code of a snippet.
There are additional files containing the source code license information, version information and lists of credits.
All the files are plain text, encoded in UTF-8 format with UTF-8 preamble (BOM). Line breaks are denoted by CR+LF
pairs.
All files are located in the same directory.
There are two kinds of meta data files:
categories.ini
lists the categories contained in the collection.
.ini
files, one for each category specified in categories.ini
. Each of these files contains numerous details of each snippet along with the name of the file containing its source code.
categories.ini
Each section in this file defines a category and has the following format:
[<cat-id>] Desc=<category-description> Ini=<ini-file-name>
The sections in these files are named with a unique identifier that identifies a category within the collection. The section names must be alphanumeric characters. The values have the following purpose:
Desc
A brief, human readable, description of the category. Any text is permitted.
Ini
The name of the .ini
file that contains information about each snippet in the category. Must be a valid file name, without path. The files must be stored in the same directory as category.ini
.
Here is an example (this is a copy of the "Date and Time" category's entry):
[date] Desc=Date and Time Ini=date.ini
.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> Extra=<extra-info-REML> 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"> Delphi101B=<"Y"|"N"|"Q"|"W"> FPC=<"Y"|"N"|"Q"|"W"> Kind=<"freeform"|"routine"|"type"|"const"|"class"|"unit"> TestInfo=<"none"|"basic"|"advanced">
The sections in these files are named with identifiers that uniquely identify a snippet. This must be a valid Unicode Pascal identifier. The keys in a section have the following purpose:
DisplayName
The human readable name of the snippet. May be any text of up to 64 characters.
May be omitted. If not present then the snippet identifier that names the section is used as the human readable name.
Desc
Description of the snippet as plain text.
Desc
is ignored if a non-empty DescEx
key is present. At least one of the Desc
or DescEx
keys are required to be present and non-empty.
DescEx
Formatted description of the snippet using REML1 code.
May be empty, in which case the Desc
key is used. Desc
is ignored if DescEx
has a non-empty value. At least one of the Desc
or DescEx
keys are required to be present and non-empty.
Snip
The name of the file containing this snippet's source code. The file name must:
.ini
file;
This key is required to be present and non-empty.
Units
Comma separated list of units required to compile the snippet. The System
unit is assumed and does not need to be specified. Unit names must be valid Pascal identifiers.
May be omitted or empty if no units are required.
Depends
Comma separated list of the identifiers of snippets that are required to compile this snippet. Snippet identifiers must exist within the collection and must not cause a circular reference back to this snippet.
May be omitted or empty if there are no such dependencies.
SeeAlso
Comma separated list of the identifiers of cross-referenced snippets. Snippet identifiers should exist in the collection.
May be omitted or empty.
Extra
Provides extra information about the snippet. When present the value must be a valid string of REML1 code.
May be omitted or empty. In this case any extra information is generated from the values of any Comments
, Credits
and Credits_URL
keys, if present.
When Extra
has a non-empty value the Comments
, Credits
and Credits_URL
keys are ignored.
Credits
2
Text that notes any credits / acknowledgements. Credits
may optionally contain one (and only one) section of text delimited by [
and ]
characters that indicate the presence of a hyperlink. The enclosed text is used as the text of a hyperlink whose URL must be specified in the Credits_URL
key.
May be omitted or empty. Credits
is ignored if a non-empty Extra
key is present.
Credits_URL
2
The URL used in any hyperlink present in the Credits
key.
Must be present if Credits
specifies a hyperlink. Ignored if Credits
contains no hyperlink section or if a non-empty Extra
key is present.
Comments
Text string containing any additional comments about the snippet.
Optional. Ignored if a non-empty Extra
key is present.
DelphiXXX
& FPC
This related group of keys describe the results of compiling the snippet with various compilers. The key name identifies the compiler. Valid key names are:
Delphi2
– Delphi 2 compilerDelphi3
– Delphi 3 compilerDelphi4
– Delphi 4 compilerDelphi5
– Delphi 5 compilerDelphi6
– Delphi 6 compilerDelphi7
– Delphi 7 compilerDelphi2005Win32
– Win32 personality of Delphi 2005 compilerDelphi2006Win32
– Win32 personality of Delphi 2006 compilerDelphi2007
– Delphi 2007 compilerDelphi2009Win32
– Win32 personality of Delphi 2009 compilerDelphi2010
– Delphi 2010 compilerDelphiXE
– Delphi XE compilerDelphiXE2
– Delphi XE2 compilerDelphiXE3
– Delphi XE3 compilerDelphiXE4
– Delphi XE4 compilerDelphiXE5
– Delphi XE5 compilerDelphiXE6
– Delphi XE6 compilerDelphiXE7
– Delphi XE7 compilerDelphiXE8
– Delphi XE8 compilerDelphi10S
– Delphi 10 Seattle compilerDelphi101B
– Delphi 10.1 Berlin compilerFPC
– Free Pascal compilerValid values for these keys are:
Y
– compiles on the compilerN
– does not compile on the compilerW
– compiles with warnings on the compilerQ
– compilation result unknown
All keys are optional. If any of the above compiler keys is not present, or is empty, the compile result for the associated compiler is assumed to be Q
.
Kind
The kind (or type) of this code snippet. Valid values are:
freeform
3 – a freeform snippet that doesn't conform to any other other supported type.routine
– a Pascal routine (function or procedure).type
– a simple Pascal type definition.const
– a Pascal constant definition.class
– a Pascal class or advanced record definition and implementation.unit
3 – a complete Pascal unit.
Kind
is optional. If the key is not present then its value defaults to routine
.
TestInfo
Testing information for the snippet. Valid values are:
none
– the snippet has not been tested.basic
– the snippet has passed some simple testing.advanced
– the snippet has passed more advanced testing, usually unit tests.
TestInfo
is optional. If it is not present then its value defaults to basic
.
The format is quite messy, with several keys having similar or overlapping purposes. This has happened because new keys have been added over time while preserving backward compatibility.
Backwards compatibility with older file formats has now been dropped, but to save development time, some of the old style values have been retained. However some duplication of keys has been removed from the collection. Over time some redundant keys may be removed.
There is a separate source code file for each snippet. These file names must be named exactly as specified in the related category .ini
file's Snip
key. They are usually numbered from 001
and have a .dat
extension, but this is not a requirement.
Source code files must be structured in a way that is suitable for the kind of snippet the source code represents. The layout of source code required by each snippet kind is explained in detail in source-code-format.html.
There are two credits files, CONTRIBUTORS
and TESTERS
that list the people who have contributed code to the collection or helped to test the code, respectively.
Each file is simply a list of names, with each name on a separate line. No blank lines are permitted.
The files may be empty if there are no contributors and/or testers, but they must be present.
The credits files are not referenced by, and do not reference, any of the other files in the collection.
There are two files relating to license (and copyright) information: the full text of the license in human readable format and a file providing machine readable meta data about the license and copyright.
This file is named LICENSE
and contains the full text of the license that applies to the source code in the collection.
This file must be present and non-empty.
The LICENSE
file is not referenced by, and does not reference, any of the other files in the collection.
A file named LICENSE-INFO
is provided that contains information about the license in machine readable form. Information is in Key=Value
format as follows:
LicenseName=<human-readable-name> LicenseSPDX=<code-name> LicenseURL=<url> CopyrightDate=<date-range> CopyrightHolder=<name> CopyrightHolderURL=<url>
The keys have the following meaning:
LicenseName
The name of the license as plain text. Required.
Examples:
MIT License
Mozilla Public License 2.0
LicenseSPDX
The Open Source Initiative (OSI) SPDX short identifier of the license, if any. If the license does not have a SPDX identifier this key must either be omitted or be empty.
Examples:
MIT
MPL-2.0
For a list of OSI licenses with their SPDXs see https://opensource.org/licenses/alphabetical.
LicenseURL
The URL of an online copy of the license. If the license has no URL then this key must be omitted or be empty.
Example: https://opensource.org/licenses/MIT
.
CopyrightDate
The year of the copyright or range of years as plain text. Required.
Examples:
2020
2005-2020
CopyrightHolder
The name of the copyright holder as plain text. Required. Where there are contributors either list them all or append and contributors
4 to the primary copyright holder's name.
Examples:
Joe Bloggs
Annie Smith, Joe Bloggs and Jessie Sharp
Annie Smith and Contributors
CopyrightHolderURL
The URL of a web page where details of the copyright holder(s) or primary copyright holder can be found. This key is optional.
Example: https://example.com/joe-blogs-bio
.
The LICENSE-INFO
file is not referenced by, and does not reference, any of the other files in the collection.
This is a file named VERSION
that contains the version number of the collection, terminated by CR+LF
. The version number must be of the form 9.9.9
, where each 9
represents a non-negative integer. The file is required and must be non-empty.
Version numbers must be incremented according to to the principles of semantic versioning.
The current major version is v25.
The VERSION
file is not referenced by, and does not reference, any of the other files in the collection.