sysfs
=====
Read the required files in a directory.

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

   * - Name
     - Type
     - Description

   * - dir_path
     - str
     - The path of target sysfs folder.

   * - keys
     - list
     - The required file names in the sysfs folder.

   * - optional_keys
     - list, None
     - (optional; default: ``None``) The optional file names in the sysfs folder.

Description
-----------
Sysfs exports the information of device to a directory, and each attribute is
stored in a separate file.  This function is aimed to read the structure.

Examples
--------
Let's say we have the file tree:

- ``/sys/bus/cool/devices/1/aa`` contains "A"
- ``/sys/bus/cool/devices/2/aa`` contains "AA"
- ``/sys/bus/cool/devices/2/bb`` contains "BB"
- ``/sys/bus/cool/devices/3/xx`` contains "XX"

And the probe statement is::

  {
    "eval": {
      "sysfs": {
        "dir_path": "/sys/bus/cool/devices/*",
        "keys": [
          "aa"
        ],
        "optional_keys": [
          "bb"
        ]
      }
    }
  }

Then the probed results are::

  [
    {
      "aa": "A"
    },
    {
      "aa": "AA",
      "bb": "BB"
    }
  ]

The probed results don't include the entry ``/sys/bus/cool/devices/3``
because that entry doesn't contain the required field ``aa``.