kitty/docs/kittens/developing-builtin-kittens.rst

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