file
====
Read the content of a file.

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

   * - Name
     - Type
     - Description

   * - file_path
     - str
     - The file path of target file.

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

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

Description
-----------
The content of the file is stripped and the empty content is filtered. If the
``split_lines`` argument is set, then the content will be splitted by line.
The file path is allowed unix style to match multiple files.

Examples
--------
Let's say if the file tree looks like:

- ``/tmp/aaa/x`` contains::

    Hello, Google
    Hello, ChromiumOS

- ``/tmp/aaa/y`` contains::

    Bye, Everyone

And the probe statement is::

  {
    "eval": "file:/tmp/aaa/x"
  }

Then the probed results will be::

  [
    {
      "file_row": "Hello, Google\nHello, ChromiumOS"
    }
  ]

If the probe statement is ::

  {
    "eval": {
      "file": {
        "file_path": "/tmp/aaa/*",
        "split_line": true,
        "key": "my_awesome_key"
      }
    }
  }

, then the probed results will be::

  [
    {
      "my_awesome_key": "Hello, Google"
    },
    {
      "my_awesome_key": "Hello, ChromiumOS"
    },
    {
      "my_awesome_key": "Bye, Everyone"
    }
  ]

In above example we use ``"split_line": true`` to let this function treat
each line of the content of a file as different results.  And instead of
just specifying a real path, we have ``/tmp/aaa/*`` to match both
``/tmp/aaa/x`` and ``/tmp/aaa/y``.