We could add local dir to ticat by:
$> ticat hub.add.local path=<dir-path>
Or add a git repo, ticat will do "git clone" to local dir:
$> ticat hub.add.local path=<dir-path>
Ticat will search any file with ext name ".ticat" in a local dir in hub. For each "file-or-dir-path.ticat" file, will try to register it to the command tree.
The position in the tree will depends on the relative path to the repo-root, the ext(s) will be ignored in registering.
For a dir "dir-path" with "dir-path.ticat", the ".ticat" file format is:
help = <help string>
abbrs = <abbr-1>|<abbr-2>|<abbr-3>...
cmd = <a relative path based on this dir>
If the values are quoted, the "'"" will be removed. Key "abbrs" and "abbr" are equal. If "cmd" is not provided, a empty command will be registered.
Multi-line value is supported with "\"(single ) as line breaker.
A dir without meta file "dir-path.ticat" will not be searched, so modules inside it will not be registered.
For a file "file-path" with "file-path.ticat", the ".ticat" file format is:
help = <help string>
abbrs = <abbr-1>|<abbr-2>|<abbr-3>...
[args]
arg-1|<abbr-x>|<abbr-y> = <arv-1 default value>
arg-2 = <arv-2 default value>
...
[env]
env-key-1 = <env-op>
env-key-2 = <env-op> : <env-op> : ...
...
[val2env]
env-key-1 = <value>
env-key-2 = <value>
...
[arg2env]
env-key-1 = arg-1
...
[dep]
os-cmd-1 = <why this command depends on this os-cmd>
os-cmd-2 = <why this command depends on this os-cmd>
...
The "help" and "abbrs" are the same with dir type of registering.
The [dep] section defines what os-command will be called in the command's code.
The [args] section defines the command's args with order.
Abbrs definition are allowed, seperate them with "|".
The [env] section defines which keys will read or write in the command's code.
"env-op" value could be: "read", "write", "may-read", "may-write".
The sequence of "env-op" could be one or more value with orders, seperated by ":".
Abbrs definition are also allowed in every path segment of the keys.
The [val2env] section defines keys will be written values automatically.
This is convenient for writing "on|off" switch commands.
The [arg2env] section defines keys will be written automatically with specify arg's value.
This is convenient for deliver commands with args any without any env manipulating,
so non-ticat-users could use them easily.
Dir struct:
<repo-root>
├── README.md
├── tidb (dir)
│ ├── stop.bash
│ └── stop.bash.ticat
├── tidb.ticat
└── misc (dir)
├── run.bash
└── run.bash.ticat
File "tidb.ticat":
help = simple test toolbox for tidb
abbrs = ti|db
File "stop.bash.ticat":
help = stop a tidb cluster
abbr = down|dn
[args]
force|f = true
[env]
cluster|c.name|n = read:write
What will happend:
- "run.bash" won't be registered, because "misc" with not "misc.ticat"
- "tidb" will be registered, because of "tidb.ticat"
Usage:
## This will do nothing
$> ticat tidb
## This will do nothing either, we use abbr to call "tidb"
$> ticat db
## Display command info of "tidb.stop", the ext name ".bash" is ignored
$> ticat cmds.tree tidb.stop
$> ticat cmds.tree db.down
$> ticat m.t db.dn
## Error: "tidb.stop" will read a key from env without any provider:
$> ticat tidb.stop
$> ticat db.stop
## Proper ways to call "tidb.stop", some use abbrs in the key path:
$> ticat {cluster.name = test} db.stop
$> ticat {c.n = test} db.stop
$> ticat <a-command-provide-env-key-cluster-name> : db.stop
## Use saved env to call "tidb.stop":
$> ticat {cluster.name = test} env.save
...
$> ticat db.stop
When more than one command register to a same command path, or more than one abbrs for a command path segment, ticat will display conflicting errors.
[arg2env] (only execute when env key not exists, and arg is not empty)
[val2env] (always execute, and always before arg2env and comand-exe)
[flow/][/flow] multiply flow template