Allow passing the current selection to kittens

Fixes #2796

docs/changelog.rst

@@ -15,6 +15,8 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - macOS: Fix the LC_TYPE env var being set to UTF-8 on systems in which the
   language and country code do not form a valid locale (:iss:`1233`)
 
+- Allow passing the current selection to kittens (:iss:`2796`)
+
 
 0.18.1 [2020-06-23]
 --------------------

docs/kittens/custom.rst

@@ -58,7 +58,8 @@ You can pass arguments to kittens by defining them in the map directive in
 These will be available as the ``args`` parameter in the ``main()`` and
 ``handle_result()`` functions. Note also that the current working directory
 of the kitten is set to the working directory of whatever program is
-running in the active kitty window.
+running in the active kitty window. The special argument ``@selection``
+is replaced by the currently selected text in the active kitty window.
 
 
 Passing the contents of the screen to the kitten
@@ -87,7 +88,8 @@ This will send the plain text of the active window to the kitten's
 :file:`STDIN`. For text with formatting escape codes, use ``ansi``
 instead. If you want line wrap markers as well, use ``screen-ansi``
 or just ``screen``. For the scrollback buffer as well, use
-``history``, ``ansi-history`` or ``screen-history``.
+``history``, ``ansi-history`` or ``screen-history``. To get
+the currently selected text, use ``selection``.
 
 
 Using kittens to script kitty, without any terminal UI

kitty/boss.py

@@ -851,6 +851,9 @@ class Boss:
                             add_history='history' in type_of_input,
                             add_wrap_markers='screen' in type_of_input
                     ).encode('utf-8')
+                elif type_of_input == 'selection':
+                    sel = self.data_for_at(which='@selection', window=w)
+                    data = sel.encode('utf-8') if sel else None
                 elif type_of_input is None:
                     data = None
                 else:
@@ -858,9 +861,16 @@ class Boss:
             else:
                 data = input_data if isinstance(input_data, bytes) else input_data.encode('utf-8')
             copts = common_opts_as_dict(self.opts)
+            final_args: List[str] = []
+            for x in args:
+                if x == '@selection':
+                    sel = self.data_for_at(which='@selection', window=w)
+                    if sel:
+                        x = sel
+                final_args.append(x)
             overlay_window = tab.new_special_window(
                 SpecialWindow(
-                    [kitty_exe(), '+runpy', 'from kittens.runner import main; main()'] + args,
+                    [kitty_exe(), '+runpy', 'from kittens.runner import main; main()'] + final_args,
                     stdin=data,
                     env={
                         'KITTY_COMMON_OPTS': json.dumps(copts),