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
109
110
111
112
113
114
115
116
117
118
119
|
Developing builtin kittens
=============================
Builtin kittens in kitty are written in the Go language, with small Python
wrapper scripts to define command line options and handle UI integration.
Getting started
-----------------------
To get started with creating a builtin kitten, one that will become part of kitty
and be available as ``kitten my-kitten``, create a directory named
:file:`my_kitten` in the :file:`kittens` directory. Then, in this directory
add three, files: :file:`__init__.py` (an empty file), :file:`__main__.py` and
:file:`main.go`.
Template for `main.py`
^^^^^^^^^^^^^^^^^^^^^^
The file :file:`main.py` contains the command line option definitions for your kitten. Change the actual options and help text below as needed.
.. code-block:: python
#!/usr/bin/env python
# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
import sys
# See the file kitty/cli.py in the kitty sourcecode for more examples of
# the syntax for defining options
OPTIONS = r'''
--some-string-option -s
default=my_default_value
Help text for a simple option taking a string value.
--some-boolean-option -b
type=bool-set
Help text for a boolean option defaulting to false.
--some-inverted-boolean-option
type=bool-unset
Help text for a boolean option defaulting to true.
--an-integer-option
type=int
default=13
bla bla
--an-enum-option
choices=a,b,c,d
default=a
This option can only take the values a, b, c, or d
'''.format
help_text = '''\
The introductory help text for your kitten.
Can contain multiple paragraphs with :bold:`bold`
:green:`colored`, :code:`code`, :link:`links <http://url>` etc.
formatting.
Option help strings can also use this formatting.
'''
# The usage string for your kitten
usage = 'TITLE [BODY ...]'
short_description = 'some short description of your kitten it will show up when running kitten without arguments to list all kittens`
if __name__ == '__main__':
raise SystemExit('This should be run as kitten my-kitten')
elif __name__ == '__doc__':
cd = sys.cli_docs # type: ignore
cd['usage'] = usage
cd['options'] = OPTIONS
cd['help_text'] = help_text
cd['short_desc'] = short_description
Template for `main.go`
^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: go
package my_kitten
import (
"fmt"
"kitty/tools/cli"
)
var _ = fmt.Print
func main(_ *cli.Command, opts *Options, args []string) (rc int, err error) {
// Here rc is the exit code for the kitten which should be 1 or higher if err is not nil
fmt.Println("Hello world!")
fmt.Println(args)
fmt.Println(fmt.Sprintf("%#v", opts))
return
}
func EntryPoint(parent *cli.Command) {
create_cmd(parent, main)
}
Edit :file:`tools/cmd/tool/main.go`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Add the entry point of the kitten into :file:`tools/cmd/tool/main.go`.
First, import the kitten into this file. To do this, add :code:`"kitty/kittens/my_kitten"` into the :code:`import ( ... )` section at the top.
Then, add ``my_kitten.EntryPoint(root)`` into ``func KittyToolEntryPoints(root *cli.Command)`` and you are done. After running make you should
be able to test your kitten by running::
kitten my-kitten
|
