$Id$
(This file public domain.)

JSON formats for the various outputs of tlmgr
=============================================

Fields guaranteed to be present are marked with a *.

TLPOBJ
------
JSON object with key/values according to the underlying structure with a few
exception (docfiles and docfiledata are merged). Details:

* String type:
  *name, shortdesc, longdesc, *category, catalogue, containerchecksum,
  srccontainerchecksum, doccontainerchecksum
  Example: "name": "12many"

* Number type:
  *revision, runsize, docsize, srcsize, containersize, srccontainersize, doccontainersize
  Example: "revision": 12345

* Boolean type:
  available, installed, relocated
  Example: "relocated": false

* Array type (with the sub-type in parenthesis):
  - of String type: runfiles, srcfiles, executes, depends, postactions
    Example: "runfiles": [ "texmf-dist/...", "texmf-dist/...file2" ]
  - of Object type:
    . docfiles: keys: *file, language, details (all Strings)
      Example:
        [ { "file": "docfile1", "lang": "en" }, { "file": "docfile2", "detail": "readme file" } ]

* Object type:
  - binfiles: keys are architecture names, values are arrays of strings (list of binfiles)
    Example: { "x86_64-linux": [ "binfile1", "binfile2", ... ], "win32": [ "binfile3" ] }
  - binsize: keys are architecture names, values are numbers
    Example: { "x86_64-linux": 1233, "win32": 333 }
  - cataloguedata: keys are topics, version, license, ctan, date, related (all strings)
    Example: { "topics": "graphic", "version": "1.23" }

Note: A minimal TLPOBJ might look like
{
  "name": "minimal",
  "category": "Package",
  "revision": 12345
}


TLPOBJINFO
----------
This JSON format is dumped on tlmgr info --data json and is slightly different
format compared to TLPOBJ above:

Removed fields: revision
Added fields:
- Number type: lrev, rrev -- local and remote revision of the package
- Boolean type: available (available at repository), installed
- Hash type: rcataloguedata -- catalogue data on the remote side


TLPDBSINGLE
-----------
JSON object with the following fields:
* Object type:
  - options: see TLOPTION below
  - settings: see TLSETTING below
  - configs: keys are the names of %TLConfig::TLPDBConfigs, that is
    . Boolean type: container_split_src_files, container_split_doc_files
    . String type: container_format, minrelease, release
* Array type:
  - tlpkgs: JSON array of TLPOBJs in JSON format


TLPDB
-----
This format is used when dumping tlpdb, local or remote
JSON object with the following fields.
Keys are tags, values are tlpdb in TLPDBSINGLE format.
Example:
{
  "main": {
    "options": {...},
    "tlpkgs": [...]
  },
  "tlcontrib": {
    "option": {...},
    "tlpkgs": [...]
  }
}


TLBACKUP
--------
This format is used when dumping available backups via the
tlmgr restore action.
JSON array of JSON objects, one per available backup.
Each backup has keys: name, rev, date (all strings).
Example:
[
   {
      "date" : "2017-10-30 11:04",
      "name" : "uplatex",
      "rev" : "45414"
   },
   {
      "date" : "2017-09-28 10:50",
      "name" : "uplatex",
      "rev" : "45141"
   }
]


TLPAPER
-------
An array of objects, each one having three keys: program, file, options.
`program' gives the program name, `file' the place where the configuration
has been found, and `options' is an array of strings with the first 
one being the currently selected paper.
Example for one element of the array:
   {
      "options" : [
         "a4",
         "letter"
      ],
      "file" : "/usr/local/texlive/2017/texmf-config/tex/generic/config/pdftexconfig.tex",
      "program" : "pdftex"
   }


TLOPTION / TLSETTING
--------------------
Each option/setting is an object with the following keys, values
are all strings(!).
for TLOPTIONS:
  name, tlmgrname, description, format, default, value (optional)
for TLSETTING:
  name, description, format, value (optional)
Example TLOPTIONS:
         {
            "format" : "b",
            "description" : "Install source files",
            "tlmgrname" : "srcfiles",
            "value" : "1",
            "default" : "1",
            "name" : "install_srcfiles"
         },
Example TLSETTING:
         {
            "type" : "b",
            "description" : "This tree acts as user tree",
            "name" : "usertree"
         },


TLSEARCH
--------
A hash with two keys, "packages" and "files".
Value for "packages" is a hash with <pkg> -> <shortdescription>.
Value for "files" is a hash with <pkg> -> array of matching files
{
        "packages": {
                "<PKG1>": "<SHORTDESC1>",
                ...
        },
        "files": {
                "<PKG1>": [ "<FILE1>", ... ],
                ...
        }
}