DelphiDabbler CodeSnip
File Format Documentation

User Database Files

Introduction

CodeSnip's user defined snippets database is stored in an XML file along with a number of data files located in the user database directory. There is a different user database for each logged on user.

The master XML file is named database.xml. It contains all the information about user defined snippets and categories except for the source code of each snippet.

The source code for each snippet is stored in separate sequentially numbered .dat data files – one per snippet. Each source code file is referenced by the XML file.

There have been several different versions of the XML file format. Each of these is explained below.

Encoding

CodeSnip 4 stores all user database files using UTF-8 encoding. Files are saved without any UTF-8 preamble (BOM). The XML processing instruction of database.xml has an "encoding" atrribute set to "UTF-8".

Prior to CodeSnip v4 source code data files were encoded using the system default ANSI code page. The XML file was in UTF-8, but its XML processing instruction had no "encoding" atrribute.

CodeSnip v4 must be able to work with all these encoding because it may inherit a copy of a user database in an earlier format.

File Format

XML File

There have been six different versions of the XML file formats – v1 to v6. Tags from all six versions are explained below with notes describing which versions a tag applies to. Where there is no note the tag is valid in all versions.

XML processing instruction
Attributes:
version
Always set to "1.0"
encoding
Character encoding used for file.
  • versions 1..4: Attribute not provided.
  • version 5 and later: Always set to "UTF-8".
codesnip-data
Parent node for whole file. Attributes are:
watermark
Identifies file as correct type – always set to "531257EA-1EE3-4B0F-8E46-C6E7F7140106".
version
Identifies version of file. Determines which tags are valid and rules concerning content. Valid versions are 1..6.
codesnip-data/categories
Contains list of all categories.
codesnip-data/categories/category
Contains information about a category. Attributes are:
id
Internal (unique) id of category.
codesnip-data/categories/category/description
Description of category.
codesnip-data/categories/category/cat-routines
Contains list of name of all snippets in category. Omitted if there are no snippets in category.
codesnip-data/categories/category/cat-routines/pascal-name
Contains name of a snippet. One per each snippet in category.
codesnip-data/routines
Contains a list of all user defined snippets.
codesnip-data/routines/routine
Contains information about a snippet. One per snippet. Attribute:
name
Name of snippet.
  • versions 1..4: Name must begin with an English language letter or the underscore.
  • version 5 and later: Name can begin with any character that is valid as the first character of a Unicode Pascal identifier.
codesnip-data/routines/routine/cat-id
Id of category to which snippet belongs.
codesnip-data/routines/routine/description
Description of snippet.
codesnip-data/routines/routine/source-code
Name of file containing snippet's source code. No path information included.
codesnip-export/routines/routine/highlight-source
codesnip-data/routines/routine/display-name
codesnip-data/routines/routine/comments
  • version 1: Additional comments about snippets.
  • version 2 and later: Not supported.
codesnip-data/routines/routine/credits
  • version 1: Credits for snippets. May contain a single piece of text, delimited by "[" and "]" that can form a hyperlink. URL for the hyperlink is provided in codesnip-data/routines/routine/credits-url.
  • version 2 and later: Not supported.
codesnip-data/routines/routine/credits-url
  • version 1: URL required by codesnip-data/routines/routine/credits tag. Present only if codesnip-data/routines/routine/credits requires a hyperlink.
  • version 2 and later: Not supported.
codesnip-data/routines/routine/extra
  • version 1: Not supported.
  • version 2 and later: Additional information about a snippet. Content is formatted text encoded in REML markup.
    • version 2: indicates REML v1
    • version 3: indicates REML v2
    • versions 4..6: indicates REML v3.
codesnip-data/routines/routine/standard-format
  • versions 1 and 2: Flag indicating if snippet is in "standard format". Value of 1 indicates true and 0 indicates false.
  • version 3 and later: Not supported.
codesnip-data/routines/routine/kind
  • versions 1 and 2: Not supported.
  • version 3 and later: Value indicating kind of snippet. Permissible values are:
    • versions 3 and 4: "freeform", "routine", "type" & "const".
    • version 5 and 6: "freeform", "routine", "type", "const", "class" & "unit".
codesnip-data/routines/routine/compiler-results
Contains a list of compile results for the snippet.
codesnip-data/routines/routine/compiler-results/compiler-result
Entry for each known compiler. Attribute is:
id
Identifies compiler. Valid identifiers are are one of:
  • d2 – Delphi 2 compiler
  • d3 – Delphi 3 compiler
  • d4 – Delphi 4 compiler
  • d5 – Delphi 5 compiler
  • d6 – Delphi 6 compiler
  • d7 – Delphi 7 compiler
  • d2005 – Delphi 2005 compiler
  • d2006 – Delphi 2006 compiler
  • d2007 – Delphi 2007 compiler
  • d2009 – Delphi 2009 compiler
  • d2010 – Delphi 2010 compiler
  • dXE – Delphi XE compiler
  • dXE2 – Delphi XE2 compiler
  • dXE3 – Delphi XE3 compiler
  • dDX4 – Delphi XE4 compiler. Note: This value was named dDX4 in error: it should have been named dXE4 but the erroneous value has been retained for backwards compatibility reasons.
  • dXE5 – Delphi XE5 compiler
  • dXE6 – Delphi XE6 compiler
  • dXE7 – Delphi XE7 compiler
  • dXE8 – Delphi XE8 compiler
  • d10s – Delphi 10 Seattle compiler
  • fpc – Free Pascal compiler
Values are:
Omitting a tag for a certain compiler is permitted and is equivalent to specifying "Q".
codesnip-data/routines/routine/units
List of required units.
codesnip-data/routines/routine/units/pascal-name
Name of a unit within unit list.
codesnip-data/routines/routine/depends
List of required snippets.
codesnip-data/routines/routine/depends/pascal-name
Name of a snippet within depends list.
codesnip-data/routines/routine/xref
List of cross-referenced snippets.
codesnip-data/routines/routine/xref/pascal-name
Name of a snippet within cross-reference list.

Source Code Files

Source code is stored separately from the main XML file. The source code of each snippet has its file. Files are numbered sequentially and have a .dat extension, for example 6.dat.

Source code files are referenced by the codesnip-data/routines/routine/source-code tag in the database's XML file.

Differences Between File Versions

The differences between different user database file versions is summarised below:

Version 1
First version of database.
Version 2
The following tags are no longer supported:
The following tag was introduced:
Version 3
The following tag is no longer supported:
The following tag was introduced:
The version of REML supported by the codesnip-data/routines/routine/extra tag was updated to v2.
Version 4
The version of REML supported by the codesnip-data/routines/routine/extra tag was updated to v3.
Version 5
The XML file's encoding was explicitly set to "UTF-8" by setting the encoding attribute of the XML processing instruction to this value.
Snippet names, wherever they occur in the XML file, can now begin with any character that is a valid first character of a Unicode Pascal identifier. Previously the first character of the attribute had to be one of 'A'..'Z', 'a'..'z' or '_'.
Data files changed to use UTF-8 encoding with no BOM instead of the system default encoding.
New "class" and "unit" snippet kinds supported.
Version 6
A snippet's description is now stored as formatted text using REML markup. Previously the description was plain text.
The following tag was introduced:

Notes for File Readers

Readers of version 1 files must convert the contents of the codesnip-data/routines/routine/comments, codesnip-data/routines/routine/credits and codesnip-data/routines/routine/credits-url tags into formatted text that simulates the parsed content of the codesnip-data/routines/routine/extra tag.

Readers of v1 and v2 files should map a codesnip-data/routines/routine/standard-format value of "0" to a codesnip-data/routines/routine/kind value of "freeform" and a value of "1" to "routine".

Readers of v1 to v5 files must:

  1. Convert the plain text snippet description read from codesnip-data/routines/routine/description into the formatted text equivalent of a single paragraph containing the description.
  2. Proceed as if a codesnip-export/routines/routine/highlight-source tag with value "1" had been specified.