TODO

   1 TO DO
   2
   3 - Address the remaining "---" issues
   4
   5 - Get the rest of the unit tests working
   6   - Ensure we can parse/print descriptor.proto, unittests.proto, etc
   7     - unittests.proto completely fails when 'optimize = SPEED'
   8   - Ensure we can (de)serialize "golden" data against unittests.proto
   9   - Get the rest of Bob Brown's tests working
  10 [  - Convert examples into a test suite                                         ]
  11 [    - Implement 'protobufs-equal' predicate                                    ]
  12
  13 - Get "namespaces" (i.e., nested classes) fully working
  14 [  - Messages and enums should have a 'fully-qualified-names' slot              ]
  15 [    that records both symbols and strings, and in the correct package          ]
  16 [  - Printers need to print qualified names, as needed                          ]
  17 [  - 'find-message' and 'find-enum' need to search namespaces                   ]
  18 [     if the quick compare against the name/class fails                         ]
  19   - 'message Foo { message Bar { ... } ... }'
  20     should not produce a Lisp class defaultly named 'foo.bar', but...
  21     - Add a keyword arg, :class-name, that overrides this convention;
  22       in .proto files this should be called lisp_class
  23     - Also, add :slot-name for slots and :type-name for enums
  24       (called lisp_slot and lisp_type in .proto files)
  25     - Rationale: 'foo.bar' isn't very Lispy;
  26       for the most part, packages provide enough namespaces to avoid clashes
  27
  28 - Get 'merge-from-message' fully working
  29   - See the place in 'deserialize-object' that needs to merge, too
  30   - Maybe this isn't so useful in Lisp, where I'd prefer to encourage
  31     a more function style
  32
  33 - Lose 'proto-class', replace it with 'proto-type';
  34     its type is (or null symbol)
  35   'proto-type' should always be the name from the Lisp side
  36 [  All 'define-xxx' macros should have, as their first argument,                ]
  37 [    a type (not a "name")                                                      ]
  38 [  In .proto files, there should be an 'option lisp_name="pkg:name"'            ]
  39 [    which can be used to override the 'proto->class-name' default              ]
  40 [    for messages and enums                                                     ]
  41
  42 - Refactor 'protobuf-field' so the names are clearer:
  43   - 'proto-value' should be the Lisp name of the slot
  44       (this is already the case)
  45   - Add new 'proto-field' slot,
  46       which will hold the Protobufs name of the field
  47       (this used to be in 'proto-name')
  48   - Lose the existing 'proto-type' slot,
  49       then rename the 'proto-class' slot to 'proto-type';
  50       this will hold the Lisp name of the slot type
  51   - 'proto-name' will hold the Protobufs name of the field type
  52       (this used to hold the Protobufs name of the field)
  53 [  - &key name should give the Protobufs name for the field                     ]
  54 [  - 'option lisp_name="pkg:name"' should give the Lisp name for the slot       ]
  55
  56 [- Refactor 'define-message'/'define-extend'/'define-group'                     ]
  57 [  to avoid so much duplicated code                                             ]
  58
  59 [- Need search paths in the ASDF .proto module                                  ]
  60
  61 [- Make 'import' really work                                                    ]
  62 [  - *all-protobufs* should record keyed by pathname, too                       ]
  63 [  - 'import' should not bother loading if the import is present,               ]
  64 [    and should record the imported schema when it's done                       ]
  65 [  - 'find-message' and 'find-enum' should search imports, too                  ]
  66
  67 [- Implement 'vector-of' in addition to 'list-of'                               ]
  68
  69 [- Do we need 'has-extension' and 'clear-extension'?                            ]
  70 [  If so, just generate methods for them in 'define-extend'                     ]
  71
  72 [- 'package'/'lisp_package' should create the package, if necessary.            ]
  73
  74 [- Don't generate 'import "net/proto2/proto/descriptor.proto"' and              ]
  75 [  'extend proto2.MessageOptions { ..}' lines unless we need to include         ]
  76 [  one of the lisp_* options in the generated model                             ]
  77
  78 [- Handle 'import'                                                              ]
  79 [  It should probably just compile/load the file when the import                ]
  80 [    is seen                                                                    ]
  81 [  - The Lisp macros should be able to import both .lisp and .proto files       ]
  82 [  - The .proto parser should only be able to import .proto files               ]
  83
  84 [- Handle 'extension' and 'extends'                                             ]
  85 [  - 'define-extension' just declares the extension within a message            ]
  86 [      and adds it to 'proto-extensions' for the message                        ]
  87 [  - Easiest is to add an "extension-p" flag to 'protobuf-message'              ]
  88 [  - Define new 'define-extends' macro                                          ]
  89 [      which *copies* all slots from the message being extended,                ]
  90 [      then just adds the extension fields as (flagged) ordinary fields         ]
  91 [      with reader/writer function (see below)                                  ]
  92 [      - Factor out field-processing code from 'define-message'                 ]
  93 [      - If we do it this way, no other special magic is needed                 ]
  94 [        Serialization, e.g., should just work                                  ]
  95 [        Scoping should also just work                                          ]
  96 [      - We will need 'proto-writer' as an analog to 'proto-reader'             ]
  97 [  - Get deserialization working;                                               ]
  98 [      Need to call the 'proto-writer' function if its around                   ]
  99 [      instead of just using (setf (slot-value ...) ...)                        ]
 100 [  - Don't forget to check that the "extends" indexes match                     ]
 101 [      what was declared by 'define-extension'                                  ]
 102 [      - And don't allow overlapping extension indexes                          ]
 103 [  - Generate new getter and setter methods for each extended slot:             ]
 104 [      (let ((an-int 10))                                                       ]
 105 [       (declare (type (or integer null) an-int))                               ]
 106 [       (defmethod an-int ((object extendable-foo))                             ]
 107 [         an-int)                                                               ]
 108 [       (defmethod (setf an-int) (val (object extendable-foo))                  ]
 109 [         (declare (type (or integer null) val)                                 ]
 110 [         (setq an-int val))))                                                  ]
 111 [  - Handle "extends" in the parser, too                                        ]
 112
 113 [- Support "deprecated" groups. Sigh.                                           ]
 114 [  - Need 'proto:define-group', which is like 'define-message'                  ]
 115 [  - Need to parse 'group' things                                               ]
 116 [    - "option group Locator = 1 { ... }"                                       ]
 117 [      means create a submessage (and class!) called "Locator"                  ]
 118 [      whose field is named "locator" (note lower case)                         ]
 119 [      then just treat it like a message                                        ]
 120 [  - Need a printer for groups, too                                             ]
 121 [  - Make 'proto-extension-p' be 'proto-message-type',                          ]
 122 [    which is one of :message, :extends or :group                               ]
 123 [  - (De)serialization of groups uses a start and end tag,                      ]
 124 [    and the end tag counts as part of the group length                         ]
 125 [    - Serialization uses the start-group wire type,                            ]
 126 [      then serializes the message,                                             ]
 127 [      then writes the end-group tag                                            ]
 128 [    - Deserialization works the usual way,                                     ]
 129 [      except that it stops at a matching end-group tag                         ]
 130 [      (i.e., has the same field number as the start tag)                       ]
 131 [      - Add new 'end-tag' argument to 'serialize-object' and                   ]
 132 [        the 'serialize' internal function, it's the expected                   ]
 133 [        end tag value to indicate end-of-group; if the default                 ]
 134 [        value for this is 0, then the (i= tag 0) test can be                   ]
 135 [        changed to (i= tag end-tag) (sweet!)                                   ]
 136
 137 [- We need both 'package' and 'lisp-package' for protobufs                      ]
 138 [  'package' gets set from the 'package' line in .proto files                   ]
 139 [  'lisp-package' gets set from a new 'option lisp_package="pkg"'               ]
 140 [  'define-protobuf' needs both :package and :proto/:lisp-package               ]
 141
 142 [- Speed up 'list-of' by shadowing the Quux version,                            ]
 143 [    and don't do any type-checking (!)                                         ]
 144 [  Having done this, we can probably remove the hack of using map:map,          ]
 145 [    which should make deserialization much faster                              ]
 146
 147 [- 'proto-name' should always be the name from the Protobufs side;              ]
 148 [    its type is (or null string)                                               ]
 149 [  All 'define-xxx' macros should have '&key name' which gives the Protobufs    ]
 150 [   name, which can be used to override the 'class-name->proto' default         ]
 151
 152 [- 'class-override' should be called 'alias-for';                               ]
 153 [    its type is (or null symbol)                                               ]
 154 [  'define-message' and 'define-enum' both get '&key alias-for'                 ]
 155
 156 [- 'find-message' and 'find-enum' should only look at (the new) 'proto-type',   ]
 157 [    and never (the new) 'proto-alias-for'                                      ]
 158
 159 [- 'deserialize-object' uses the alias when it calls 'make-instance',           ]
 160 [    or if there is no alias, 'proto-type'                                      ]
 161
 162 [- 'serialize-object' and 'object-size' should take both 'object' and 'type'    ]
 163 [    args, and should not call 'class-of' (and do call it "type")               ]
 164 [  The 'cl' (and 'class') locals in '(de)serialize-object' and 'object-size'    ]
 165 [    should instead be called 'type'                                            ]
 166 [  In .proto files, there should be 'option lisp_alias="pkg:name"'              ]
 167 [    that gets used to fill in 'proto-alias-for'                                ]
 168
 169 [- 'serialize-object' and 'object-size' never use the alias;                    ]
 170 [    instead all the "dispatching" should be done of off 'proto-type',          ]
 171 [  Ditto, 'print-text-format'                                                   ]
 172
 173 [- Deserialization should stop if it sees a #x00 in the position where          ]
 174 [    it's expecting a tag, since no tag can be #x00 (fields start at 1)         ]
 175
 176 [- The "name" of a protobuf should be the camel-cased file name                 ]
 177 [  The "type" of a protobuf should just be the file name as a keyword symbol    ]
 178
 179 [- RPCs should have 'input-name', 'input-type', 'output-name' and 'output-type' ]
 180 [  The "name" ones are for the Protobufs side                                   ]
 181 [  The "types" ones are for the Lisp side; we look up on "type" only            ]
 182 [  In the Lisp, the RPC types can be either 'type' or '(type :name <name>)'     ]
 183 [  In .proto files, there should be an 'option lisp_name="pkg:name"'            ]
 184 [   which can be used to override the 'proto->class-name' default               ]
 185 [   for the name of the RPC function                                            ]
 186
 187 [- Finishing eliminating 'protobuf' argument from the API                       ]
 188 [  - Lose it in 'serialize-object-to-stream' and 'deserialize-object-from-stream']
 189 [  - Rename it to 'trace' in '(de)serialize-object' and 'object-size',          ]
 190 [      make it be the last supplied argument                                    ]
 191 [  - Fix up the '(de)serialize-object' and 'object-size' generators, too        ]
 192 [  - Apply the same fix to 'print-text-format'                                  ]
 193 [  - Then make the compatibility API actuallty work                             ]
 194
 195 [- Implement 'parse-text-format'                                                ]
 196
 197 [- Renamings                                                                    ]
 198 [   'define-proto' -> 'define-schema'                                           ]
 199 [   'protobuf' (class name) -> 'protobuf-schema'                                ]
 200 [   'find-protobuf' -> 'find-schema'                                            ]
 201 [   *all-protobufs* -> *all-schemas*                                            ]
 202 [   'parse-protobuf-from-file' -> 'parse-schema-from-file'                      ]
 203 [   'parse-protobuf-from-stream' -> 'parse-schema-from-file'                    ]
 204 [   'write-protobuf' -> 'write-schema'                                          ]
 205 [   'write-protobuf-as' -> 'write-schema-as'                                    ]
 206 [   'ensure-all-protobufs' -> 'ensure-all-protobufs'                            ]
 207 [   'ensure-protobuf' -> 'ensure-protobuf'                                      ]
 208 [   'protobuf-upgradable' -> 'schema-upgradable'                                ]
 209 [   'protobufs-equal' -> 'schemas-equal'                                        ]
 210 [   'generate-protobuf-schema-for-classes' -> 'generate-schema-for-classes'     ]
 211 [   'write-protobuf-schema-for-classes' -> 'write-schema-for-classes'           ]
 212
 213 [- Write documentation                                                          ]