shell
=====
Execute the shell command and return the output.

Function Arguments
------------------
.. list-table::
   :widths: 20 10 60
   :header-rows: 1
   :align: left

   * - Name
     - Type
     - Description

   * - command
     - str
     - The shell command.

   * - key
     - str
     - (optional; default: ``'shell_raw'``) The key of the result.

   * - split_line
     - bool
     - (optional; default: ``False``) True to split lines to multiple results.

Description
-----------
This function executes the specific shell command and takes the standard
output of that command as the probed results if the return code is zero.

The output of a probe function is always in dictionary type.  The output of
this function will contain only one entry, whose key is specified by the
argument ``key`` and the value is the standard output of the command.

Examples
--------
Let's assume that the output of the command ``ls`` is::

  aaa
  bbb
  ccc

Then the probe statement ::

  {
    "eval": "shell:ls"
  }

will have the corresponding probed result ::

  [
    {
      "shell_raw": "aaa\nbbb\nccc"
    }
  ]

Another example is that the probe statement ::

  {
    "eval": {
      "shell": {
        "command": "ls",
        "split_line": true,   # Treat each line as different probe results.
        "key": "my_key_name"  # Use "my_key_name" as the key in the output
                              # dictionary
      }
    }
  }

will have the corresponding probed results ::

  [
    {
      "my_key_name": "aaa"
    },
    {
      "my_key_name": "bbb"
    },
    {
      "my_key_name": "ccc"
    }
  ]

The command can be even more complex like ::

  {
    "eval": "shell:ls | grep aaa"
  }

In above case, the probed result will be empty if the output of ``ls``
command doesn't contain ``aaa`` because ``grep aaa`` will have a non-zero
return code when it cannot find ``aaa`` from its standard input.