.. raw:: html

	<style>th, td { text-align:center }</style>

.. |v| unicode:: U+2713

.. module:: hdir

:mod:`hdir` --- Highlight dir
=============================

``hdir()`` is a highlighted version of the ``dir()`` function.


Dependencies
------------

* `Python <https://www.python.org>`_ 3.6+
* Console with `ANSI colors <https://en.wikipedia.org/wiki/ANSI_escape_code>`_


Usage
-----

::

	pip install hdir

Invoke ``hdir()`` without argument shows the legend:

.. raw:: html
	:file: ../hdir/legend.html

``hdir()`` does not break words and sort them alphabetically according to case.
Let's compare the classic ``dir()`` function with ``hdir()`` on the ``builtins`` module:

.. raw:: html
	:file: ../hdir/builtins.html

``type.__dict__`` is a *proxy* ``<>`` to a *dict* ``{}``
whose first item is a *descriptor* ``<>`` to a *function* (cyan):

.. raw:: html
	:file: ../hdir/recursive.html


Color
-----

.. table::
	:widths: auto

	======= ==========================
	Color   Type
	======= ==========================
	Blue    int, float, bool, complex
	Cyan    function or method
	Green   string
	Magenta module
	Red     exception
	Yellow  class other than exception
	======= ==========================

.. table::
	:widths: auto

	========= ============ ============ ======= =========== ============
	Style     Meaning      Windows [1]_ Mintty_ `Linux FB`_ GNOME_, KDE_
	========= ============ ============ ======= =========== ============
	Color     type [2]_    |v|          |v|     |v|         |v|
	Bold      is real [3]_ |v|          |v|     |v|         |v|
	Italic    is abstract               |v|                 |v|
	Underline of instance  |v|          |v|                 |v|
	========= ============ ============ ======= =========== ============

.. _Mintty: http://mintty.github.io
.. _Linux FB: https://en.wikipedia.org/wiki/Linux_framebuffer
.. _GNOME: https://wiki.gnome.org/Apps/Terminal
.. _KDE: https://konsole.kde.org

.. [1] ``HKCU\Console\VirtualTerminalLevel = 1`` enables ANSI colors except dark yellow
.. [2] If it is a container, first item's color
.. [3] Neither abstract nor wrapped in a *descriptor* or *proxy*


Decorators
----------

.. table::
	:widths: auto

	========== =================== =========
	Decorators Type                Recursive
	========== =================== =========
	``'...'``  string
	``[...]``  list                |v|
	``(...)``  tuple               |v|
	``{...}``  dict or set         |v|
	``<...>``  descriptor or proxy |v|
	``...()``  user function [4]_
	========== =================== =========

.. [4] Written in Python language, neither built-in nor C language library function


Instance variable
-----------------

``hdir()`` underlines instance variables. In this example,
the ``msg`` instance variable covers the same name's class variable:

.. raw:: html
	:file: ../hdir/instance.html


Flags
-----

``hdir()`` hides ``__double`` ``__magic__`` ``_private`` attributes
unless ``'d'`` ``'m'`` ``'p'`` flags are set:

.. raw:: html
	:file: ../hdir/magic.html

The *"all"* ``'a'`` flag equals ``'dmp'``,
though abstract items are always visible:

.. raw:: html
	:file: ../hdir/abstract.html

The *"no-color"* ``'n'`` flag disables ANSI colors but keeps decorators:

.. raw:: html
	:file: ../hdir/no-color.html

The *"raw"* ``'r'`` flag returns a ``vars()`` style's *dict*
to take advantage of attribute filtering:

.. raw:: html
	:file: ../hdir/raw.html


No false positive
-----------------

While ``dir()``, ``vars()`` and ``inspect.getmembers()``
return some attributes that does not exist,
``hdir()`` tests each attribute with ``hasattr()`` to remove false positives:

.. raw:: html
	:file: ../hdir/false-positive.html


Versions
--------

:0.5: February 16, 2019 --- *First beta release*
:0.4: February 8, 2019 --- ``import *`` *imports hdir() only*
:0.3: February 7, 2019 --- *Add legend,* ``'r'`` *flag, wrapper support*
:0.2: February 5, 2019 --- *False positive removal*
:0.1: February 5, 2019 --- *First alpha release*