Introduction

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.

Notation

For any parts of this documentation that don't apply to all collection versions, the applicable versions may be specified using Ruby's twiddle-wakka pessimistic operator. For example ~>2.1 means that the item applies to all versions >=2.1 but <3.0 while ~>2.1.2 means that the item applies to all versions >=2.1.2 but <2.2.0.

Meta Data Files

There are two kinds of meta data files:

1. categories.ini lists the categories contained in the collection.
2. A set of further .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.

Format Of 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 and must be unique within the collection.

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

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

Format Of Individual 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>
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">
Delphi102T=<"Y"|"N"|"Q"|"W"> [~>2.2]
Delphi103R=<"Y"|"N"|"Q"|"W"> [~>2.2]
Delphi104S=<"Y"|"N"|"Q"|"W"> [~>2.2]
Delphi11A=<"Y"|"N"|"Q"|"W"> [~>2.2]
Delphi12A=<"Y"|"N"|"Q"|"W"> [~>2.2]
FPC=<"Y"|"N"|"Q"|"W">
Kind=<"freeform"|"routine"|"type"|"const"|"class"|"unit">
TestInfo=<"none"|"basic"|"advanced">
AdvancedTest.Level=<"unspecified"|"unit-tests"|"demo"|"other"> [~>2.2]
AdvancedTest.URL=<url> [~>2.2]

[~>2.1]: Keys marked with an asterisk (*) are deprecated and are no longer used in the collection. However, software requiring backwards compatibility must be prepared to process these keys and to make appropriate decisions about how to handle them. See other notes below for further details.

The [snippet-name] sections in these files must be named with identifiers that uniquely identify a snippet. This must be a valid Unicode Pascal identifier. The keys in each section have the following purpose:

DisplayName

The human readable name of the snippet. May be any plain 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.

[~>2.0.0]: 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.

[~>2.1]: Desc is deprecated and must not be used. DescEx must be used instead.

DescEx

Formatted description of the snippet. When present the value must be a valid string of REML¹ code.

[~>2.0.0]: DescEx 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.

[~>2.1]: DescEx is required to be present and non-empty.

Snip

The name of the file containing this snippet's source code. The file name must:

• be a valid file name;
• contain no path information;
• exist in the same directory as the .ini file;
• be unique within the whole collection.

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 REML¹ code.

May be omitted or empty.

Credits²

Text that notes any credits / acknowledgements. Credits may optionally contain one (and only one) section of plain 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.

[~>2.0.0]: May be omitted or empty. Credits is ignored if a non-empty Extra key is present.

[~>2.1]: Deprecated and must not be used. Use Extra instead.

Credits_URL²

The URL used in any hyperlink present in the Credits key.

[~>2.0.0]: Must be present if Credits specifies a hyperlink. Ignored if Credits contains no hyperlink section or if a non-empty Extra key is present.

[~>2.1] Deprecated and must not be used.

Comments

Plain text string containing any additional comments about the snippet.

Optional. Ignored if a non-empty Extra key is present.

[~>2.0.0]: May be omitted or empty. Comments is ignored if a non-empty Extra key is present.

[~>2.1]: Deprecated and must not be used. Use Extra instead.

DelphiXXX & FPC

This related group of keys describes the results of compiling the snippet with various compilers. The key name identifies the compiler. Valid key names are:

• Delphi2 – Delphi 2 compiler
• Delphi3 – Delphi 3 compiler
• Delphi4 – Delphi 4 compiler
• Delphi5 – Delphi 5 compiler
• Delphi6 – Delphi 6 compiler
• Delphi7 – Delphi 7 compiler
• Delphi2005Win32 – Win32 personality of Delphi 2005 compiler
• Delphi2006Win32 – Win32 personality of Delphi 2006 compiler
• Delphi2007 – Delphi 2007 compiler
• Delphi2009Win32 – Win32 personality of Delphi 2009 compiler
• Delphi2010 – Delphi 2010 compiler
• DelphiXE – Delphi XE compiler
• DelphiXE2 – Delphi XE2 compiler
• DelphiXE3 – Delphi XE3 compiler
• DelphiXE4 – Delphi XE4 compiler
• DelphiXE5 – Delphi XE5 compiler
• DelphiXE6 – Delphi XE6 compiler
• DelphiXE7 – Delphi XE7 compiler
• DelphiXE8 – Delphi XE8 compiler
• Delphi10S – Delphi 10 Seattle compiler
• Delphi101B – Delphi 10.1 Berlin compiler
• Delphi102T – Delphi 10.2 Tokyo compiler [~>2.2]
• Delphi103R – Delphi 10.3 Rio compiler [~>2.2]
• Delphi104S – Delphi 10.4 Sydney compiler [~>2.2]
• Delphi11A – Delphi 11.x Alexandria compiler [~>2.2]
• Delphi12A – Delphi 12.x Athens compiler [~>2.2]
• FPC – Free Pascal compiler

Valid values for these keys are:

• Y – compiles on the compiler
• N – does not compile on the compiler
• W – compiles with warnings on the compiler
• Q – 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³ – a freeform snippet that doesn't conform to any 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³ – a complete Pascal unit.

Kind is optional. If the key is not present then its value defaults to routine.

TestInfo

Information about if or how the snippet has been tested. Valid values are:

• none – the snippet has not been tested.
• basic – the snippet has passed some simple, unspecified 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.

AdvancedTest.Level [~>2.2]

Provides detailed testing information for snippets with TestInfo=advanced. Valid values are:

• unspecified – the type of advanced testing has not been specified.
• unit-tests – the snippet has passed unit tests.
• demo - there exists demo code that exercises the snippet.
• other - some other form of testing has been used.

AdvancedTest.Level is optional. If it is not present or is empty then its value defaults to unspecified.

AdvancedTest.Level must not be present if TestInfo ≠ advanced.

AdvancedTest.URL [~>2.2]

The URL of test code relating to the snippet.

AdvancedTest.URL is optional, but if present must be set to a valid URL.

AdvancedTest.URL must not be present if TestInfo ≠ advanced or AdvancedTest.Level = unspecified.

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.

Limited backwards compatibility with v1 file formats was retained for ~>2.0.0 in order to save development time. For ~>2.1 such duplication has been removed from the collection.

Source Code Files

There is a separate source code file for each snippet. These files 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.

Credits Files

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.

License Files

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.

Full License Text

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.

License Meta Information

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⁴ 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.

Version Information File

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 not be empty.

Version numbers must be incremented according to to the principles of semantic versioning.

The VERSION file is not referenced by, and does not reference, any of the other files in the collection.

Software Implementation Notes

Handling collection versions

Do not attempt to use v1 format collection files.

Backwards compatibility is guaranteed for all versions ~>2.0. The file formats are defined in such a way that software designed to read a later collection version can make sensible decisions about missing values when reading earlier versions.

Forwards compatibility is not guaranteed, but every attempt is made to enable software designed to read older collection versions to be able to read newer versions, albeit with some loss of information. To be able to do this software must ignore values and files that it does not understand or expect.

Key duplication in category .ini files

Given that the some keys duplicate or overlap with others, it can be confusing to know how to process this duplication in software. Here are some tips.

Desc & DescEx

In ~>v2.0.0, both Desc and DescEx keys can be found together or individually. Deal with them as follows:

• If both keys are non-empty use the value of DescEx and ignore Desc.
• If only DescEx is non-empty, use its value.
• If only Desc is non-empty then convert its plain text value into a REM¹ paragraph and proceed as if DescEx was defined with the REML as its value.

For ~>2.1 you can expect that DescEx will always be non-empty and that Desc does not exist.

Credits, Credits_URL, Comments & Extra

For ~>2.0.0 various combinations of the above keys can be found. Deal with them as follows:

• If a non-empty Extra key exists simply use the REML¹ code it defines and ignore any Credits, Credits_URL and Comments values.

• Wheres there is no Extra content do this:

  • If there is a non-empty Credits value, but no Credits_URL value, then create a REML¹ paragraph containing the plain text of the Credits value. Store this.
  • If there are non-empty Credits and Credits_URL values then create REML¹ as explained in footnote 2 and store it.
  • If there is a non-empty Credits_URL value but no Credits value then ignore the value.
  • If there is a non-empty Comments value then create a REML¹ paragraph containing the plain text value. Store this.

  Now combine any REML¹ paragraphs you generated from the Credits and Comments values and proceed as if there was an Extra key with the same value.

For ~>2.1 you can expect that Credits, Credits_URL or Comments won't exist and simply deal with Extra if it is present.

Handling compiler results

It is easy to deal with compilation results. Simply check for the existance of the key matching the required compiler (e.g. DelphiXE8). If the key exists then read its value, otherwise proceed as if it had the value Q.

Note that Delphi 10.2 Tokyo and later are only defined for ~>2.2.

Handling test information

Before v2.2.0 there was just the single TestInfo key that provided any information about program testing. v2.2.0 added the AdvancedTest.Level and AdvancedTest.URL keys.

Software that doesn't understand the new keys can safely ignore them and continue to use only TestInfo.

~>2.2 compliant software can get further information about snippets that have received advanced "testing", where such information is available. The possible values are documented above.

Note that AdvancedTest.Level = unspecified simply means we know that "advanced" testing was undertaken, but we don't know exactly what form it took. There can be no URL linking to test source code: if AdvancedTest.URL is non-empty that is an error and the value should be ignored. If AdvancedTest.Level is not present then software should assume unspecified, because that is the key's default value.

Having AdvancedTest.Level set to any value other than unspecified provides additional information. In these cases AdvancedTest.URL may provide a URL that links to code containing the tests. This could be a source code repository or a Gist, for example. Given that AdvancedTest.URL is optional, software should be able to handle cases where there is no link to the test code available.