Browse Source

Document the shell plugin

Clara Hobbs 7 years ago
parent
commit
0ffc0e7922
1 changed files with 28 additions and 3 deletions
  1. 28
    3
      kayleevc/plugins/shell.py

+ 28
- 3
kayleevc/plugins/shell.py View File

@@ -3,6 +3,29 @@
3 3
 # Copyright 2015-2016 Clayton G. Hobbs
4 4
 # Portions Copyright 2013 Jezra
5 5
 
6
+"""Run shell commands that match voice commands
7
+
8
+This Kaylee plugin can be used to perform the job of `Blather
9
+<https://gitlab.com/jezra/blather>`__.  Its configuration is of the
10
+following format::
11
+
12
+    ".shell": {
13
+        "VOICE_COMMAND": "SHELL_COMMAND",
14
+        ...
15
+    }
16
+
17
+A VOICE_COMMAND may contain any number of the special word ``%d``,
18
+which is a stand-in for a spoken number.  The spoken number is
19
+transformed into a decimal integer which may be substituted into the
20
+SHELL_COMMAND any number of times.  These substitutions are made by
21
+writing ``{INDEX}`` in the SHELL_COMMAND, where INDEX is an integer
22
+counting the ``%d`` strings from 0.  An example of this type of command
23
+is::
24
+
25
+    "%d is a number": "echo 'the number you said was {0}'"
26
+
27
+"""
28
+
6 29
 import subprocess
7 30
 
8 31
 from .pluginbase import PluginBase
@@ -10,8 +33,10 @@ from ..numbers import NumberParser
10 33
 
11 34
 
12 35
 class Plugin(PluginBase):
36
+    """Run shell commands that match voice commands"""
13 37
 
14 38
     def __init__(self, config, name):
39
+        """Initialize the shell plugin"""
15 40
         super().__init__(config, name)
16 41
         self.number_parser = NumberParser()
17 42
         self.commands = self.options
@@ -25,10 +50,10 @@ class Plugin(PluginBase):
25 50
         subprocess.call(cmd, shell=True)
26 51
 
27 52
     def recognizer_finished(self, recognizer, text):
28
-        """Process a recognized voice command
53
+        """Run the shell command corresponding to a recognized voice command
29 54
 
30
-        Recognized commands have the corresponding shell commands executed,
31
-        possibly with number(s) substituted.
55
+        Spoken number(s) may be substituted in the shell command.  The shell
56
+        commands are printed immediately before they are executed.
32 57
         """
33 58
         numt, nums = self.number_parser.parse_all_numbers(text)
34 59
         # Is there a matching command?

Loading…
Cancel
Save