summaryrefslogtreecommitdiff
path: root/doc/interface.txt
blob: 22a35ed722d157b7075d92d0284fa96836205c78 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108


THANDY CLIENT INTERFACE:

   thandy-client update [options] [bundlename...]

   thandy-client json2xml filename

Recognized options for thandy-client update are:

   --repo=<dir>    Store downloaded, finished information under <dir>.
                   Defaults to ~/.thandy/cache

   --no-download   Only decide what to download; don't actually download
                   anything.

   --loop          Do not exit after we have nothing more to download; keep
                   waiting until there's something to do.

   --no-packagesys Do not ask any underlying package system about what
                   versions of things are installed.  Assume we need to
                   fetch all packages not in the cache.

   --install       Try to install packages after downloading them.

   --socks-port=<port>
                   Run all network operations over the SOCKS4a server at
                   localhost:<port>

   --debug|--info|--warn
                   Set logging severity.


   --force-check
                   Download a fresh version of the timestamp file, whether
                   we need it or not.

   --controller-log-format
                   Output log messages in a format designed to be easy
                   for controllers to read.  (See below.)


THE CONTROLLER LOG FORMAT:

  All lines are of the form:
    Keyword SP (Keyword=QuotedString SP)* NL

    Keyword=[A-Za-z0-9_]+
    QuotedString=DQ Quoted* DQ
    Quoted =   (Any character except for \, ", or newline)
             | (\\)
             | (\")
             | (\n)

    SP = A single space character.
    NL = A newline character
    DQ = A double-quote character.

  Current message types are:

    INFO, WARN, DEBUG
       These correspond to regular user-visible log messages.

    WANTFILE FILENAME="a relative path in the repository"
       Thandy wants to download the listed file from some mirror.

    CAN_INSTALL PKG="a relative path in the repository" ITEM="another one"
       Thandy has enough information to install something.  The 'item' is
       an installable item (exe, rpm, msi, etc); the PKG is the json package
       descriptor it belongs to.

    NO_INSTALL PKG="a relative path in the repository" ITEM="another one"
       As CAN_INSTALL, but Thandy has gotten something that it doesn't
       have a way to install.  Can you help?


THANDY'S JSON2XML FORMAT:

  Some people use libraries whose XML parsers are way better than their JSON
  parsers, so Thandy includes a quick-and-dirty json2xml converter.  It is a
  one-way converter that's good enough for Thandy documents, but little else.

  Here's the specification for it.  CONV.x. indicates the conversion of a
  JSON object x into XML.

     ESC(x) == x, with the characters &, <, and > escaped.

     CONV."x". == ESC(x) if x is a string.
     CONV.x. == x if x is an integer, a boolean, or none.
     CONV.[a,b,c,...]. ==
            <list><item>CONV.a.</item>
                  <item>CONV.b.</item>
                  <item>CONV.c.</item>
            </list>

     CONV.{k1:v1, k2:v2, k3:v3, ...}. ==
            <dict>CONV.k1:v1.
                  CONV.k2:v2.
                  CONV.k3:v3.</dict>

     CONV.k:v. == <k>CONV.v.</k>   if k is a valid XML tag name made up of
                                   nothing but ascii characters.

               == <dict-entry><key>CONV.k.</key>
                              <val>CONV.v.</val>
                  </dict-entry>                     otherwise