todo.txt

   1 tk_cmd
   2 ======
   3
   4 X evaluate expression tree in ec_tk_expr
   5 X cmd token
   6 X example
   7 X tk_re
   8
   9 cleanup / rework
  10 ================
  11
  12 X ec_completed_item_update()
  13 X ec_completed_item_set_display_value()
  14 X add_no_match
  15 X add_partial_match
  16 - check XXX in code
  17 X properly manage quotes in shlex
  18 X remove the _new() functions
  19 X iterate children nodes without chaining them
  20 - add a node vector type: will be used in several nodes (ex: or, seq, ...)
  21 - check allocation model everywhere
  22 - checkpatch?
  23 - use linux style (update .emacs)
  24 - better logs
  25 - check return values (-1 or NULL) + use errno
  26 - check missing static / const
  27 X license: SPDX
  28 - check all completion nodes
  29 X split ecoli_tk.h
  30 - size_t or unsigned int?
  31 X rename:
  32   X ec_tk -> ec_node
  33   X ec_parsed_tk -> ec_parsed
  34   X ec_completed_tk -> ec_completed
  35   X tk, gen_tk, token, ... -> node
  36   X tokens -> input_str / input_strvec ?
  37 X save node path in completion to fix help string
  38 - code coverage
  39 - try to hide structures
  40 X anything better than weakref?
  41 - add ec_node_defaults.[ch] providing usual implementations of node methods
  42 X use vec for strvec
  43 / ELOOP in case of loop
  44 X remove weakref?
  45 - sh_lex to provide offsets in attributes
  46 - accessors for all structs
  47 - private vs user attributes?
  48 - limit max loop,
  49 - limit max completions
  50
  51 dependencies
  52 ============
  53
  54 X pass the current parsed state when parsing/completing
  55 X new node "once"
  56 - new node "condition"
  57
  58 logs
  59 ====
  60
  61 X register log types
  62
  63 yaml
  64 ====
  65
  66 X register nodes by name
  67 X interface to add attributes: all nodes must be configurable through a
  68   generic api:
  69   X attr string
  70   X attr string list
  71   X attr node
  72   X attr node list
  73   X attr int
  74
  75 X yaml interface to create nodes
  76 - example
  77
  78 examples
  79 ========
  80
  81 - example which parses arguments (argc/argv)
  82 - example that acts as bash completion (ip link ?)
  83 - calculator example (var assignation, expression evaluation)
  84 - example with libedit
  85 - mini script language
  86 - configuration file
  87 - mini shell: cd, ls, cat, stat
  88 - mini network console based on ip
  89 - dialog-like for use in shell
  90 - pcap https://github.com/the-tcpdump-group/libpcap/blob/master/grammar.y
  91
  92 doc
  93 ===
  94
  95 - overview
  96 - add api doc in .h
  97 - generate automatic api doc
  98 - architecture
  99 - coding rules, process
 100 - each node
 101 - allocation model
 102 - say that it stops at first match (no ambigous support)
 103 - say that completion must be exhaustive
 104
 105 build framework
 106 ===============
 107
 108 - .map files for API
 109 - split libs, tests and examples
 110 - add make help
 111 - add make config
 112 - -fvisibility=
 113 - use meson
 114
 115 tests
 116 =====
 117
 118 - complete automatic tests with "make test"
 119
 120 new nodes
 121 =========
 122
 123 - regexp
 124 X node which always matches
 125 X file + partial completion
 126 - ether, ip, network
 127 - fusion node: need to match several children, same for completion?
 128 - float
 129 - not
 130 - reparse: parse a tree with received strvec, then another tree
 131   with strvec generated from first tree
 132
 133 encoding
 134 ========
 135
 136 - support utf-8 and other encodings
 137 - example
 138 - documentation
 139
 140 netconf example
 141 ===============
 142
 143 / demonstration example that parses yang file and generate cli
 144
 145
 146
 147 -----------------------
 148
 149 readline:
 150
 151 [tab]  list possible completions (matches/partial only)
 152 [?]    list what is expected, example:
 153
 154 "command [foo] toto|titi|<int>"
 155
 156 help("command f") ->
 157   foo     (help of foo)
 158   toto    (help of toto)
 159   titi    (help of titi)
 160   <int>   (help of int)
 161
 162
 163 ----------------
 164
 165 struct names
 166 ============
 167
 168 ideas:
 169
 170 - ec_node: a node that can be parsed/completed
 171 - ec_parse: a tree describing the result of parse(node, input)
 172 - ec_comp: a list describing the result of complete(node, input)
 173
 174 ec_comp_item
 175
 176
 177 ---------------
 178
 179 node tree
 180 =========
 181
 182 Example:
 183
 184 1  seq
 185 2    option
 186 3      str(foo)
 187 4    or
 188 5      int(1,10)
 189 6      str(bar)
 190 7      str(foo)
 191
 192 parse() returns a tree
 193 =======
 194
 195 - each node of the tree refers to a ec_node
 196 - each node points to the strvec that matches
 197 - parse returns the first matching solution
 198 - usually try to match as many str in the vecs (seq node)
 199
 200 [foo] ->
 201 1 seq
 202 2   option
 203 4   or
 204 7     str(foo)
 205
 206 The parse cb of the node is:
 207
 208 parse_cb(node, current_parse_state, strvec, *nmatch)
 209
 210 return values:
 211 - 0: success, child->strvec is set by node (NULL = no_match)
 212 - -1: error (errno is set)
 213 maybe complex to use:
 214 - the node must set the match (ex: "return ec_parsed_node_match()")
 215 - the caller must use accessor to check if it matches or not
 216
 217 alternative idea for return values:
 218 - >= 0: match, ret == nb_tk
 219 - -1: error (errno is set)
 220 - -2 or MAX_INT: success, but no match
 221 This is strange to have a specific value for no match
 222 With MAX_INT, this is the best (less bad) alternative
 223
 224 alternative idea for return values:
 225 - ec_parse_result_match(n_tokens >= 0)
 226 - ec_parse_result_nomatch()
 227 - ec_parse_result_error(errno)
 228
 229 A node always try to consume the maximum number of tokens.
 230 Example:
 231 1  seq
 232 2    option
 233 3      str(foo)
 234 4    str(foo)
 235 5    str(bar)
 236
 237 [foo, foo, bar] matches
 238 [foo, bar] does *not* match
 239
 240 complete() returns a list of possible completions
 241 ==========
 242
 243 problems:
 244 - partial completion: in a path dir/file, completion stops once
 245   after the directory
 246 - displayed value is not the completion token: when completing a
 247   file in several subdirectories, the full path is not displayed
 248 - any parent node can modify the completions, ex: add missing quotes
 249   in ec_node_sh_lex(), filter completions in case of a ec_node_filter()
 250 - a command line may want to display the help from the most specific
 251   token, or not.
 252 - some specific nodes can complete several tokens
 253
 254 struct item {
 255   const char *str;
 256   type: full, partial, unknown
 257 }
 258
 259 full: the completion item matches token
 260 partial: beginning of a completion, does not match the token
 261          (good example is a directory in a path)
 262 unknown: could complete, but the node does not know how
 263
 264 struct completion_item {
 265   const char *value;
 266   const char *disp;
 267 }
 268
 269 struct completed_elt {
 270   ec_parsed *parse_tree; // current tree state
 271   ec_node *last;         // last node of the tree
 272   list of items;         // list of items for this parse tree
 273 }
 274
 275 struct completed {
 276   list(elt)
 277 }
 278
 279 The callback is:
 280
 281 complete_cb(node, current_complete_state, current_parse_state, strvec)
 282 return:
 283 - 0 = success, the current complete state is updated
 284 - -1 = error (set errno?)
 285
 286
 287 a node can filter the completions
 288
 289
 290 [] ->
 291   foo   3 str(foo)
 292     seq
 293       option
 294         str(foo) <-
 295
 296   ""    5 int(1,10)
 297     seq
 298       option
 299       or
 300         int <-
 301
 302   bar   6 str(bar)
 303   foo   7 str(bar)
 304 ...
 305
 306
 307 [foo, ] ->
 308
 309   ?       5 int(1,10)
 310   seq
 311     option
 312       str(foo)
 313     or
 314       int <-
 315
 316   bar   6 str(bar)
 317   foo   7 str(bar)
 318
 319
 320
 321 -----
 322
 323 changes:
 324 - a completion item should contain a strvec for the value
 325   (the display string remains a string)
 326 - there is maybe no good reason to split in:
 327   - ec_completed_item()
 328   - ec_completed_item_set()
 329   - ec_completed_item_set_display()
 330   - ec_completed_item_add()
 331
 332 -----
 333
 334 sh_lex
 335   or
 336     str(foo)
 337     str(foo2)
 338     str(bar)
 339
 340 complete(sh_lex, ["'fo"])
 341   complete(sh_lex, ["fo"]) -> ["foo", "foo2"]
 342
 343
 344 -----
 345
 346 #include <stdio.h>
 347 #include <stdbool.h>
 348
 349
 350 struct res {
 351         int a;
 352 };
 353
 354 static inline bool is_success(struct res r)
 355 {
 356         if (r.a == 0)
 357                 return true;
 358         return false;
 359 }
 360
 361
 362 static inline struct res res(int a)
 363 {
 364         struct res r;
 365         r.a = a;
 366         return r;
 367 }
 368
 369 int main(void)
 370 {
 371         struct res r;
 372
 373         r = res(0);
 374
 375         printf("%d\n", r.a);
 376         if (is_success(r))
 377                 printf("success: %d\n", r.a);
 378
 379         r = res(1);
 380
 381         printf("%d\n", r.a);
 382         if (is_success(r))
 383                 printf("success: %d\n", r.a);
 384
 385         return 0;
 386 }
 387
 388
 389 ----
 390
 391
 392 expr expr expr
 393
 394 [toto] | tutu
 395
 396 [toto [titi]]
 397
 398
 399
 400 pre_op = "!"
 401 post_op = "^"
 402 post = val |
 403        pre_op expr |
 404        "(" expr ")"
 405 term = post post_op*
 406 prod = term ( "*" term )*
 407 sum = prod ( "+" prod )*
 408 expr = sum
 409
 410
 411 -----
 412
 413 break on malloc:
 414
 415 b debug_malloc
 416 # or: b debug_realloc
 417 condition <breakoint num> malloc_seq >= <value>
 418
 419 alternative
 420
 421 watch malloc_seq
 422 condition <watchpoint num> malloc_seq == <value + 1>
 423 run <args...>
 424 c
 425
 426
 427 ---------------
 428
 429
 430 about split in several libraries
 431
 432 There are several options:
 433
 434 1/ one library, config options to select libyaml, libedit
 435    - need to manage dependencies in build system
 436
 437 2/ one library for ecoli-core, one for ecoli-yaml, one for
 438    ecoli-edit
 439    - extra complexity
 440
 441 3/ one library with core + yaml + edit
 442    dependency is managed at runtime
 443
 444
 445 --------------
 446
 447 current naming: ec_node_parse* and ec_comp_complete* are not
 448 so good names
 449
 450 struct          ec_comp
 451 alloc           ec_complete()
 452 free            ec_complete_free()
 453 action          ec_comp_complete()
 454 action          ec_comp_complete_strvec()
 455 action          ec_comp_dump()
 456 action          ec_comp_merge()
 457 accessors       ec_comp_get()
 458
 459 struct          ec_parse
 460 alloc           ec_parse()
 461 free            ec_parse_free()
 462 action          ec_node_parse()
 463 action          ec_node_parse_strvec()
 464 accessors       ...
 465
 466 struct          ec_node
 467 alloc           ec_node()
 468 free            ec_node_free()
 469 action          ...
 470 accessors       ...
 471
 472 struct          ec_strvec
 473 alloc           ec_strvec()
 474 free            ec_strvec_free()
 475 action          ec_strvec_*()
 476
 477 ---------
 478
 479 proposal
 480
 481 - struct name must not be a verb (ex: not ec_parse)
 482 - allocator is the name of struct
 483 - actions are <structname>_<verb>() except for basic/common actions
 484 - basic actions are ec_<verb>()
 485 - accessors (get) are <structname>_<field>()
 486 - accessors (set) are <structname>_set_<field>()
 487
 488
 489 XXX list all functions to be sure
 490 XXX this could go in documentation (coding rules)
 491
 492 struct          ec_comp
 493 alloc           ec_comp()
 494 free            ec_comp_free()
 495 action          ec_complete()
 496 action          ec_complete_strvec()
 497 action          ec_comp_dump()
 498 action          ec_comp_merge()
 499 accessors       ec_comp_id()
 500 accessors       ec_comp_attrs()
 501
 502 (pnode means parsed node)
 503 struct          ec_pnode
 504 alloc           ec_pnode()
 505 free            ec_pnode_free()
 506 action          ec_parse()
 507 action          ec_parse_strvec()
 508 accessors       ...
 509
 510 (node means grammar node)
 511 struct          ec_node
 512 alloc           ec_node()
 513 free            ec_node_free()
 514 action          ...
 515 accessors       ec_node_get*()
 516
 517 struct          ec_strvec
 518 alloc           ec_strvec()
 519 free            ec_strvec_free()
 520 action          ec_strvec_*()
 521
 522 ---
 523