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.
-
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
-
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.
-
versions 1..5: Content is a single line
of plain text.
-
version 6: Content is formatted text
encoded in REML markup. REML v3 is supported.
-
codesnip-data/routines/routine/source-code
-
Name of file containing snippet's source code. No path information included.
-
codesnip-export/routines/routine/highlight-source
-
-
versions 1..5: Not supported.
-
version 6:
Flag indicating if snippet source code can be highlighted using
syntax highlighter. Permissible values are:
-
"0" – do not syntax highlight source code
-
"1" – syntax highlight source code
Omitting this tag is permitted. Value defaults to "1" in
this case.
-
codesnip-data/routines/routine/display-name
-
-
versions 1..5: Not supported.
-
version 6: Display name of snippet. Can
contain any characters and need not be unique. Present only if snippet
has a display name that is different to the value of the name
attribute of the codesnip-data/routines/routine tag.
-
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
-
-
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:
-
"Y" – Compiles with the identified compiler.
-
"W" – Compiles with the identified compiler with
warnings.
-
"N" – Does not compile with the identified compiler.
-
"Q" – Compile result for this compiler is not known.
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.
-
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/xref
-
List of cross-referenced snippets.
-
codesnip-data/routines/routine/xref/pascal-name
-
Name of a snippet within cross-reference list.
-
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.
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:
-
codesnip-data/routines/routine/comments
-
codesnip-data/routines/routine/credits
-
codesnip-data/routines/routine/credits-url
The following tag was introduced:
-
codesnip-data/routines/routine/extra (uses REML v1 markup).
-
Version 3
-
The following tag is no longer supported:
-
codesnip-data/routines/routine/standard-format
The following tag was introduced:
-
codesnip-data/routines/routine/kind
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:
-
codesnip-data/routines/routine/display-name
-
codesnip-export/routines/routine/highlight-source
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:
-
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.
-
Proceed as if a codesnip-export/routines/routine/highlight-source
tag with value "1" had been specified.