DelphiDabbler CodeSnip
File Format Documentation
Export Files
Introduction
User defined snippets can be exported from the program for importing into
another program or for submitting to the online database. Exported data is
stored in a single XML file.
There have been several different versions of the XML file format. Each of
these is explained below.
Encoding
XML export files use UTF-8 encoding without a byte order mark. XML generated
for submission to the online database is also encoded in UTF-8.
CodeSnip 4 includes an encoding attribute "UTF-8" in the
XML file's XML processing instruction. Earlier versions of the program omitted
this attribute.
File Format
There have been six different versions of the XML file format – 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-export
-
Parent node for whole file. Attributes are:
-
watermark
-
Identifies file as correct type – always set to
"B46969D4-D367-4F5F-833E-F165FBA78631".
-
version
-
Identifies version of file. Determines which tags are valid and
establishes rules concerning content. Valid versions are 1..6.
-
codesnip-export/prog-version
-
Version of program that generated the file, as a dotted quad with format
N.N.N.N where N is a non-negative integer.
-
codesnip-export/user-info
-
Contains information about user who created the file (omitted for normal
exports – included for submissions to the online database).
-
codesnip-export/user-info/name
-
User's name or nickname.
-
codesnip-export/user-info/email
-
User's email address.
-
codesnip-export/user-info/comments
-
Any comments provided by user.
-
codesnip-export/routines
-
Contains a list of all exported snippets.
-
codesnip-export/routines/routine
-
Contains information about an exported snippet. One per snippet.
Attribute is:
-
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-export/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-export/routines/routine/source-code-text
-
Snippet source code.
-
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-export/routines/routine/comments
-
-
version 1: Additional comments about
snippets.
-
version 2 and later: Not supported.
-
codesnip-export/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-export/routines/routine/credits-url.
-
version 2 and later: Not supported.
-
codesnip-export/routines/routine/credits-url
-
-
version 1: URL required by
codesnip-export/routines/routine/credits tag. Present only if
codesnip-export/routines/routine/credits requires a hyperlink.
-
version 2 and later: Not supported.
-
codesnip-export/routines/routine/extra
-
-
codesnip-export/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-export/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 later:
"freeform", "routine", "type",
"const", "class" & "unit".
-
codesnip-export/routines/routine/compiler-results
-
Contains a list of compile results for the snippet.
-
codesnip-export/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-export/routines/routine/units
-
List of required units.
-
codesnip-export/routines/routine/units/pascal-name
-
Name of a unit within unit list. Must be a valid Pascal identifier.
-
codesnip-export/routines/routine/depends
-
List of required snippets.
-
codesnip-export/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-export/routines/routine/xref
-
List of cross-referenced snippets.
-
codesnip-export/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.
Differences Between File Versions
The differences between different export file versions is summarised below:
-
Version 1
-
First version of database.
-
Version 2
-
The following tags are no longer supported:
-
codesnip-export/routines/routine/comments
-
codesnip-export/routines/routine/credits
-
codesnip-export/routines/routine/credits-url
The following tag was introduced:
-
codesnip-export/routines/routine/extra (uses REML v1 markup).
-
Version 3
-
The following tag is no longer supported:
-
codesnip-export/routines/routine/standard-format
The following tag was introduced:
-
codesnip-export/routines/routine/kind
The version of REML supported by the
codesnip-export/routines/routine/extra tag was updated to v2.
-
Version 4
-
The version of REML supported by the
codesnip-export/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 '_'.
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 tags were introduced:
-
codesnip-data/routines/routine/display-name
-
codesnip-export/routines/routine/highlight-source
Notes For File Readers Used For Importing
Readers of v1 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 a
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.