:mod:`elf` -- convenience functions and settings
================================================

.. _convenience_functions:

Convenience functions
---------------------


.. function:: prettify(obj [, indent=0, mask=None, oneline=True, maxlength=80])

    Prettify a pylibelf object (or any :class:`PrettyPrintBase` object).
    ``indent`` specifies the amount of leading indentation, 
    ``mask`` should be a :class:`PrettifyMask` instance specifying stuff to
    mask or stuff to keep.
    If ``oneline`` is true, a single object be formatted on a single line if it doesn't exceed ``maxlength``.

.. function:: pretty_print(obj [, \*\*kwargs])

    Pretty print an object, using the same rules as :class:`prettify`.

.. function:: find(iterable [, errors=<settings.errors>, index=False], \*\*kwargs)

    Returns the first matching object that has the specified attributes. 
    ``iterable`` is the iterable you want to find stuff in and
    ``error`` indicates whether to raise errors when no object is found.
    ``index`` returns the index in a tuple like ``(index, object)`` 
    if set to a truth value.
    Any additional keyword arguments are used in the matching of objects. 
    The keyword is the attribute of the object and the argument its supposed 
    value.

.. function:: findall(it, \*\*kwargs)

    Like :class:`find`. Find all matching objects.

Classes
-------

.. class:: PrettifyMask([attrs=None, values=None, classes=None, attrkeys=None, valuekeys=None, invert=False])

    A mask can be used for comparing pylibelf objects, or for printing them.

    :param attrs: list of attribute names to mask
    :param values: a list of values to mask
    :param classes: types of values to mask
    :param invert: inverts the mask

    ``attrkeys`` and ``valuekeys`` are like ``attrs`` and ``values``
    respectively, except that they are keys that take the attribute name or
    value as the argument, and return whether the attribute or value 
    should be masked.
    Masks can be inverted with the ``~`` operator, which returns a new inverted mask object. This can be useful
    for "inclusion" instead of "exclusion" purposes.

    .. method:: match(obj, attrribute_name)
        
        Indicates whether the attribute of ``obj`` specified by 
        ``attribute_name`` is masked.

Example::

    >>> from pylibelf import libelf, elf
    >>> lib = libelf.Library('/bin/ls')
    >>> elf.pretty_print(lib, mask=elf.PrettifyMask(classes=(libelf.Section, libelf.Segment)))
    Library(filename:    '/bin/bash'
            elfobject:   ElfObject(fd=0xb, shoffset=932480, phoffset=64)
            mode:        Type(ELF_C_READ, 1) 
            kind:        Type(ELF_K_ELF, 'elf')
            elfclass:    Type(ELFCLASS64, 64)
            type:        Type(ET_EXEC, 'executable') 
            ordering:    Type(ELFDATA2LSB, '<')
            machine:     Type(EM_X86_64, 'AMD x86-64 architecture')
            entrypoint:  4321808 
            flags:       0
            elf_version: 0x1
            os_abi:      0x0 
            abi_version: 0x0 
            segments:    [...] 
            sections:    [...])


.. class:: Type(value[, representation=None, varname=None])

    A Type instance can represent anything with an integer value, 
    representation and variable name. In pylibelf it is used to keep track
    of C constants, so it's easy for the user to figure out what a certain
    value actually represents.
    ``Type`` objects can be used like any normal int or long.

    :param value: the integer value of the constant
    :param representation: the representation of the constant
    :param varname: the name of the constant
