DelphiDabbler Code Snippets Database v2
Collection File Format

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.

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.

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">
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:

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

Credits2

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_URL2

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 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
  • 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:

  • freeform3 – 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.
  • unit3 – 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.

Source Code Files

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.

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