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.
codesnip-export/routines/routine/source-code-text
Snippet source code.
codesnip-export/routines/routine/highlight-source
codesnip-data/routines/routine/display-name
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
  • 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 and 5: indicates REML v3.
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:
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.
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.

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

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:

  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.