DCPD: Extensions

For additional DCPD information, see:

Extensions

A DCPD extension should be understood as an extension to the DCPD envelope, not as a run-time plugin to some editing tool. Extensions form a design smörgåsbord for a format designer, and is also how specific format needs are specified.

In order to represent chess problems (or other problem related information), additional structures are needed. This is (notionally) done by extensions, declared in format. Example:

format : {                  -- req
  name : "someformatname"  --   req
  version : VERSION        --   req
  
  used-extensions : [      --   opt
    { name: "ext1", version: "0.0.1"},  --   one or more
  ]
}

ext1 : {
  ... ext1-specific data
}

The used-extensions data is a kind of checkpoint: if an extension is declared that is not recognized by the processing software, or an extension required by the format specification is not supported, this should probably produce an early warning or an error. (The actual specification of the format decides about this.)

See Common Formats : VERSION for details of VERSION.

The extension structures themselves are added after the format field. They may contain identifying data themselves. (They may, at present, not have extensions of their own.)

ext1 : {
  extension : {         -- opt 
    name : string,      --   req
    version : VERSION   --   req
    ... additional extension fields  -- opt
  }

  ... additional fields 
}

This allows some particular extension structure to identify itself by formal means (name and version).

In this case, the field name (“ext1”) is used for clarity. The overall format specification may force it to be this particular name, and base identification only on that. On the other hand, identification may also be based on the extension field inside the structure (mandatory, in such case), and in that case the field name need not be used at all. In either case, the particular format specification decides.

This extension field (or used-extension field) may also contain additional related fields, if the extension allows. These could be considered as parameters, and allow a particular extension to operate in different modes.

An example of an additional extension field:

extension : { name : "something", version : "0.0.0", retainTrailingSpaces : true }

This extension allows for a particular processing mode to keep trailing spaces in data, although the normal default operation may not do this. Each format designer will have to decide if allowing different modes by this method is preferable to creating a new format for this particular case.

The particular format specification also decides what to do if a declaration is not matched by a structure, or if additional extension fields are different in different declarations. In general, mismatches should be regarded as errors unless there are special conditions at hand, such that version “1.2.0” is known to be interpret and convert also “1.1.5” content. Such knowledge is not expressed in a DCPD design or a final data file, but it is expected to be expressed in the specification of version “1.2.0”.

Extensions cannot themselves be extended. (While there probably is no technical reason why they couldn’t, no compelling practical need has been found so far.)

As extensions are assumed to have unique names, the problem of name collision does not appear in a normal design. In case design name collision does occur and the original extension designs cannot be renamed, the reserved extension field name dcpd:internalname may be used in the following fashion.

format : {
  ...
  used-extensions: [
    { name : "superext", version : "0.0",  dcpd:internalname : "superext_1" },
    { name : "superext", version : "0.0",  dcpd:internalname : "superext_2" }
  ]
}

superext_1 : {
  ... 
}

superext_2 : {
  ... 
}

Note: This is still a design format. dcpd:internalname is information to a design format designer, it is not intended to be used in any particular file format. The actual file format specification is where all trickyness goes. In the example above, ‘superext_1’ and ‘superext_2’ are probably frozen by the specification, not by the content of the extension declarations. ‘superext_1’ cannot be replaced by ‘acmefmt’, and still be expected to work. (Thus, this particular issue does rely on implicit information to be handled. As it is considered a fairly small and rare issue, there seems to be no clear need for a more formal solution.)

See DCPD: Common Formats for further information.