DVPL-3421: splunklib.searchcommands | Support configuring search-assistant via searchbnf.conf

David Noble · David Noble · commit 8844d30238a0 · 2014-02-04T17:02:21.000-08:00
plus documentation update for examples/searchcommands_app. In a future release we will generate the searchbnf.conf file from source comments.

Signed-off-by: David Noble &lt;dnoble@splunk.com&gt;
diff --git a/examples/searchcommands_app/bin/countmatches.py b/examples/searchcommands_app/bin/countmatches.py
@@ -27,8 +27,8 @@ class CountMatchesCommand(StreamingCommand):
 
     ##Syntax
 
-    countmatches fieldname=**<field-name>** pattern=**<regular-expression>**
-    **<field-name>**...
+    .. code-block::
+        countmatches fieldname=<field> pattern=<regular_expression> <field-list>
 
     ##Description
 
@@ -39,14 +39,14 @@ class CountMatchesCommand(StreamingCommand):
     Event records are otherwise passed through to the next pipeline processor
     unmodified.
 
-    ## Example
+    ##Example
 
-    ```
-    | inputcsv tweets.csv | countmatches fieldname=word_count pattern="\\w+" text
-    ```
+    Count the number of words in the `text` of each tweet in tweets.csv and
+    store the result in `word_count`.
 
-    Counts the number of words in `some_text_field` and stores the result in
-    `word_count`.
+    .. code-block::
+        | inputcsv tweets.csv | countmatches fieldname=word_count
+        pattern="\\w+" text
 
     """
     fieldname = Option(
diff --git a/examples/searchcommands_app/bin/simulate.py b/examples/searchcommands_app/bin/simulate.py
@@ -30,31 +30,32 @@ class SimulateCommand(GeneratingCommand):
 
     ##Syntax
 
-    simulate csv=<path> rate=<expected-event-count> interval=<sampling-period>
-        duration=<execution-period> [seed=<string>]
+    .. code-block::
+        simulate csv=<path> rate=<expected_event_count>
+        interval=<sampling_period> duration=<execution_period> [seed=<string>]
 
     ##Description
 
-    The `simulate` command uses repeated random samples of the event records
-    in `csv` for the execution period of `duration`. Samples sizes are
-    determined for each time `interval` in `duration` using a Poisson
-    distribution with an average `rate` specifying the expected event count
-    during `interval`.
+    The :code:`simulate` command uses repeated random samples of the event
+    records in :code:`csv` for the execution period of :code:`duration`. Sample
+    sizes are determined for each time :code:`interval` in :code:`duration`
+    using a Poisson distribution with an average :code:`rate` specifying the
+    expected event count during :code:`interval`.
 
     ##Example
 
-    ```
-    | simulate csv=population.csv rate=50 interval=00:00:01 duration=00:00:01 |
-    countmatches fieldname=word_count pattern="\\w+" text |
-    stats mean(word_count) stdev(word_count)
-    ```
+    .. code-block::
+        | simulate csv=population.csv rate=50 interval=00:00:01
+            duration=00:00:05 | countmatches fieldname=word_count
+            pattern="\\w+" text | stats mean(word_count) stdev(word_count)
 
     This example generates events drawn from repeated random sampling of events
-    from `tweets.csv`. Events are drawn at an average rate of 200 events per
-    second for a duration of 30 seconds. Events are piped to the example
-    `countmatches` command which adds a `word_count` field containing the number
-    of words in the `text` field of each event. The mean and standard deviation
-    of the `word_count` are then computed by the builtin `stats` command.
+    from :code:`tweets.csv`. Events are drawn at an average rate of 50 per
+    second for a duration of 5 seconds. Events are piped to the example
+    :code:`countmatches` command which adds a :code:`word_count` field
+    containing the number of words in the :code:`text` field of each event. The
+    mean and standard deviation of the :code:`word_count` are then computed by
+    the builtin :code:`stats` command.
 
 
     """
diff --git a/examples/searchcommands_app/bin/sum.py b/examples/searchcommands_app/bin/sum.py
@@ -22,11 +22,12 @@
 
 @Configuration(clear_required_fields=True, requires_preop=True)
 class SumCommand(ReportingCommand):
-    """ Computes the sum of a set of fields
+    """ Computes the sum of a set of fields.
 
     ##Syntax
 
-    sum total=*<fieldname>* [*<fieldname>*]...
+    .. code-block::
+        sum total=<field> <field-list>
 
     ##Description:
 
@@ -35,12 +36,11 @@ class SumCommand(ReportingCommand):
 
     ##Example
 
-    ```
-    index = _internal | head 200 | sum total=lines linecount
-    ```
+    ..code-block::
+        index = _internal | head 200 | sum total=lines linecount
 
     This example computes the total linecount in the first 200 records in the
-    _internal index.
+    :code:`_internal index`.
 
     """
     total = Option(
diff --git a/examples/searchcommands_app/default/commands.conf b/examples/searchcommands_app/default/commands.conf
@@ -5,16 +5,22 @@
 filename = countmatches.py
 supports_getinfo = true
 supports_rawargs = true
+
 outputheader = true
+requires_srinfo = true
 
 [simulate]
 filename = simulate.py
 supports_getinfo = true
 supports_rawargs = true
+
 outputheader = true
+requires_srinfo = true
 
 [sum]
 filename = sum.py
 supports_getinfo = true
 supports_rawargs = true
+
 outputheader = true
+requires_srinfo = true
diff --git a/examples/searchcommands_app/default/searchbnf.conf b/examples/searchcommands_app/default/searchbnf.conf
@@ -0,0 +1,61 @@
+# [searchbnf.conf](http://docs.splunk.com/Documentation/Splunk/latest/Admin/Searchbnfconf)
+
+[countmatches-command]
+syntax = countmatches fieldname=<field> pattern=<regular_expression> \
+    <field-list>
+alias =
+shortdesc = Counts the number of non-overlapping matches to a regular \
+    expression in a search result.
+description = A count of the number of non-overlapping matches to the regular \
+    expression specified by pattern is computed for each record processed.
+    The result is stored in the field specified by fieldname. If fieldname \
+    exists, its value is replaced. If fieldname does not exist, it is \
+    created. Results are otherwise passed through to the next pipeline \
+    processor unmodified.
+comment1 = Count the number of words in the text of each tweet in tweets.csv \
+    and put the result in word_count.
+example1 = | inputcsv tweets.csv | countmatches fieldname=word_count \
+    pattern="\\w+" text
+category = fields::add
+appears-in = 5.0
+maintainer = dnoble
+usage = public
+related = stats
+tags = searchcommands_app
+
+[simulate-command]
+syntax = simulate csv=<path> rate=<expected_event_count> \
+    interval=<sampling_period> duration=<execution_period> (seed=<string>)?
+alias =
+shortdesc = Generates a sequence of events drawn from a csv file using \
+    repeated random sampling.
+description = The simulate command uses repeated random samples of the event \
+    records in csv for the execution period of duration. Sample sizes are \
+    determined for each time interval in duration using a Poisson distribution \
+    with an average rate specifying the expected event count during interval.
+comment1 = Generate events drawn by repeated random sampling of events in \
+    tweets.csv.
+example1 = | simulate csv=population.csv rate=50 interval=00:00:01 \
+    duration=00:00:05
+category = results::generate
+appears-in = 5.0
+maintainer = dnoble
+usage = public
+related = inputcsv
+tags = searchcommands_app
+
+[sum-command]
+syntax = sum total=<field> <field-list>
+alias =
+shortdesc = Computes the sum of a set of fields.
+description = The total produced is sum(sum(fieldname, 1, n), 1, N) where n = \
+    number of fields, N = number of records.
+comment1 = This example computes the total linecount in the first 200 records \
+    in the _internal index.
+example1 = index = _internal | head 200 | sum total=lines linecount
+category = reporting
+appears-in = 5.0
+maintainer = dnoble
+usage = public
+related = stats
+tags = searchcommands_app
