DelphiDabbler CodeSnip
File Format Documentation

# Export Files

## Contents

- Introduction
- Encoding
- File Format
- Change Log
- Notes For File Readers

## Introduction

User defined snippets can be exported from the program for importing into another user's user 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.

In earlier versions of CodeSnip, XML files generated for submission to the online database were also encoded in UTF-8. Support for code submission was removed from CodeSnip v4.16.0.

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 seven different versions of the XML export file format – v1 to v7. Tags used by all 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 to 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 major version of file. Determines which tags are valid and establishes rules concerning content. Valid versions are 1 to 7.
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
  - versions 1 to 6: Contains information about user who created the file used for submissions to the online database, omitted for other exports.
  - version 7: Not supported. Ignored if present.
codesnip-export/user-info/name
  - versions 1 to 6: User's name or nickname.
  - version 7: Not supported. Ignored if present.
codesnip-export/user-info/email
  - versions 1 to 6: User's email address.
  - version 7: Not supported. Ignored if present.
codesnip-export/user-info/comments
  - versions 1 to 6: Any comments provided by user.
  - version 7: Not supported. Ignored if present.
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 to 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 to 5: Content is a single line of plain text.
  - version 6 to 7.2: Content is formatted text encoded in REML markup. REML v4 is supported.
  - version 7.3 and 7.4: Content is formatted text encoded in REML markup. REML v5 is supported.
  - version 7.5 and later: Content is formatted text encoded in REML markup. REML v6 is supported.
codesnip-export/routines/routine/source-code-text
  Snippet source code.
codesnip-export/routines/routine/highlight-source
  - versions 1 to 5: Not supported.
  - version 6 and later:
    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-export/routines/routine/display-name
  - versions 1 to 5: Not supported.
  - version 6 and later: 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-export/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
  - version 1: Not supported.
  - version 2 and later: Additional information about a snippet. Content is formatted text encoded in REML markup.
    - version 2: supports REML v1.
    - version 3: supports REML v2.
    - version 4: supports REML v3.
    - versions 5 to 7.2: supports REML v4.
    - version 7.3 & 7.4: supports REML v5.
    - version 7.5 & later: supports REML v6.
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 (all versions)
    - d3 – Delphi 3 compiler (all versions)
    - d4 – Delphi 4 compiler (all versions)
    - d5 – Delphi 5 compiler (all versions)
    - d6 – Delphi 6 compiler (all versions)
    - d7 – Delphi 7 compiler (all versions)
    - d2005 – Delphi 2005 compiler (all versions)
    - d2006 – Delphi 2006 compiler (all versions)
    - d2007 – Delphi 2007 compiler (all versions)
    - d2009 – Delphi 2009 compiler (all versions)
    - d2010 – Delphi 2010 compiler (v4.1 & later)
    - dXE – Delphi XE compiler (v4.2 & later)
    - dXE2 – Delphi XE2 compiler (v4.3 & later)
    - dXE3 – Delphi XE3 compiler (v4.4 to v4.5 and v6.1 & later)
    - dXE4 – Delphi XE4 compiler (v4.5 only)
      Note: CodeSnip 3 used correct dXE4 id, but CodeSnip 4 did not (see dDX4 below).
    - dDX4 – Delphi XE4 compiler (v6.2 & later)
      Note: CodeSnip 4 dDX4 in error instead of dXE4 used by CodeSnip 3 (see above). The erroneous value was retained for backwards compatibility reasons.
    - dXE5 – Delphi XE5 compiler (v6.3 & later)
    - dXE6 – Delphi XE6 compiler (v6.4 & later)
    - dXE7 – Delphi XE7 compiler (v6.5 & later)
    - dXE8 – Delphi XE8 compiler (v6.6 & later)
    - d10s – Delphi 10 Seattle compiler (v6.7 & later)
    - d101b – Delphi 10.1 Berlin compiler (v6.8 & later)
    - d102t – Delphi 10.2 Tokyo compiler (v7.1 & later)
    - d103r – Delphi 10.3 Rio compiler (v7.1 & later)
    - d104s – Delphi 10.4 Sydney compiler (v7.1 & later)
    - d11a – Delphi 11.x Alexandria compiler (v7.2 & later)
    - d12y – Delphi 12 Athens compiler (v7.4 & later)
    - fpc – Free Pascal compiler (all versions)
  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 to 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 to 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.

## Change Log

This section describes the changes between versions of the file format.

There were small changes within versions, that probably should have been given minor version numbers - but weren't. Such minor numbers have been assigned retrospectively below, in order to better explain when in-version changes actually took place.

File formats v4 and v5/v6 actually overlapped in the dates they were in use. This is because v4 was used by CodeSnip v3 and v5/v6 were used by CodeSnip 4. Those two versions of CodeSnip were maintained in parallel for a while.

Version 1 - 15 December 2008

  Introduced in CodeSnip v2.2

  First version of export file format.

  Supported Delphi compilers from Delphi 2 to Delphi 2009 plus Free Pascal.

  REML not supported.

  The XML file was in UTF-8 format with no BOM and no XML encoding attribute.

Version 2 - 31 December 2008

  Introduced with CodeSnip v2.2.5.

  Removed following tags:

  - codesnip-export/routines/routine/comments
  - codesnip-export/routines/routine/credits
  - codesnip-export/routines/routine/credits-url

  Added following tag:

  - codesnip-export/routines/routine/extra

  The version of REML supported by the codesnip-export/routines/routine/extra tag was v1.

Version 3 - 29 June 2009

  Introduced with CodeSnip v3.0.

  The following tag was removed:

  - 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 - 06 July 2009

  Introduced with CodeSnip v3.0.1.

  The version of REML supported by the codesnip-export/routines/routine/extra tag was updated to v3.

  Version 4.1 - 24 September 2009
    Updated with CodeSnip v3.4 to add support for Delphi 2010.
  Version 4.2 - 23 October 2010
    Updated with CodeSnip v3.8.0 to add support for Delphi XE.
  Version 4.3 - 07 September 2011
    Updated with CodeSnip v3.9.0 to add support for Delphi XE2.
  Version 4.4 - 17 September 2012
    Updated with CodeSnip v3.11.0 to add support for Delphi XE3.
  Version 4.5 - 02 May 2013
    Updated with CodeSnip v3.12.0 to add support for Delphi XE4.
Version 5 - 31 December 2011

  Introduced with CodeSnip v4.0 alpha 1.

  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.

  The version of REML supported by the codesnip-export/routines/routine/extra tag was updated to v4.

Version 6 - 11 August 2012

  Introduced with CodeSnip v4.0 beta 1.

  A snippet's description is now stored as formatted text using REML v4 markup. Previously the description was plain text.

  The following tags were introduced:

  - codesnip-export/routines/routine/display-name
  - codesnip-export/routines/routine/highlight-source
  Version 6.1 - 14 September 2012
    Updated with CodeSnip v4.0 RC 1 to add support for Delphi XE3.
  Version 6.2 - 02 May 2013
    Updated with CodeSnip v4.5.0 to add support for Delphi XE4.
  Version 6.3 - 12 September 2013
    Updated with CodeSnip v4.8.0 to add support for Delphi XE5.
  Version 6.4 - 30 April 2014
    Updated with CodeSnip v4.9.0 to add support for Delphi XE6.
  Version 6.5 - 12 September 2014
    Updated with CodeSnip v4.10.0 to add support for Delphi XE7.
  Version 6.6 - 06 May 2015
    Updated with CodeSnip v4.12.0 to add support for Delphi XE8.
  Version 6.7 - 05 September 2015
    Updated with CodeSnip v4.13.0 to add support for Delphi 10 Seattle.
  Version 6.8 - 13 July 2016
    Updated with CodeSnip v4.15.0 to add support for Delphi 10.1 Berlin.
Version 7 - 31 May 2020

  Introduced with CodeSnip v4.16.0.

  The codesnip-export/user-info tag and sub-tags were no longer supported.

  Version 7.1 - 31 July 2020
    Updated with CodeSnip v4.17.0 to add support for Delphi 10.2 Tokyo, Delphi 10.3 Rio and Delphi 10.4 Sydney.
  Version 7.2 - 13 September 2021
    Updated with CodeSnip v4.18.0 to add support for Delphi 11.x Alexandria.
  Version 7.3 - 16 December 2022
    Updated with CodeSnip v4.21.0 to add support for REML v5, which is backward compatible with REML v4.
  Version 7.4 - 7 November 2023
    Updated in time for CodeSnip v4.22.0 to add support for Delphi 12 Athens.
  Version 7.5 - 2 April 2014
    Added support for REML v6, which is backward compatible with REML v4.

## Notes For File Readers

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

Readers of v1 and v2 files should map a codesnip-export/routines/routine/standard-format value of "0" to a codesnip-export/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-export/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.

Readers of v1 to v6 files must ignore the codesnip-export/user-info tag and sub-tags, where present.

Readers of v2 files and later can parse REML as v6, since all versions of REML up to v6 are backwards compatible.