mirror of
https://github.com/kovidgoyal/kitty.git
synced 2026-02-06 20:27:02 +01:00
120 lines
3.3 KiB
ReStructuredText
120 lines
3.3 KiB
ReStructuredText
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
|
|
|