'Returns and logs items in a directory, optionally filtered with ``pattern``.
File and directory names are returned in case-sensitive alphabetical
order, e.g. ``[\'A Name\', \'Second\', \'a lower case name\', \'one more\']``.
Implicit directories ``.`` and ``..`` are not returned. The returned
items are automatically logged.
File and directory names are returned relative to the given path
(e.g. ``\'file.txt\'``) by default. If you want them be returned in
absolute format (e.g. ``\'/home/robot/file.txt\'``), give the ``absolute``
argument a true value (see `Boolean arguments`).
If ``pattern`` is given, only items matching it are returned. The pattern
matching syntax is explained in `introduction`, and in this case
matching is case-sensitive.
Examples (using also other `List Directory` variants):
| @{items} = | List Directory           | ${TEMPDIR} |
| @{files} = | List Files In Directory  | /tmp | *.txt | absolute |
| ${count} = | Count Files In Directory | ${CURDIR} | ??? |'

def list_directory(self, path, pattern=None, absolute=False):

    items = self._list_dir(path, pattern, absolute)
    self._info(('%d    item%s:\n%s' % (len(items), plural_or_not(items), '\n'.join(items))))
    return items
