.. py:module:: enumeration

enumeration -- Enumeration module
=================================

This module exposes a number of tools that can be used to interact
with the enumerations or their members defined within the database.
The base argument type for interacting with an enumeration is the
enumeration identifier :py:obj:`idaapi.enum_t`. This is an opaque integer
that will need to be passed to the different tools in order to
reference the enumeration that the user is referring to.

There are a number of tools within the :py:obj:`member` namespace that can
be used to enumerate or locate the members of an enumeration. As
typically an enumeration is simply a constant, each result that is
returned will either be a value or a name. The identifier for these
is a :py:obj:`idaapi.uval_t`.

To list the different enumerations available in the database, one
can use :py:obj:`enumeration.list(...)<enumeration.list>` specifying their preferred method
of filtering. This will list all of the available enumerations at
which point the user can then request it by passing an identifier
to :py:obj:`enumeration.by(...)<enumeration.by>`. The types that can be used to filter are
as follows:

- ``name`` - Match according to the enumeration name
- ``like`` - Filter the enumeration names according to a glob
- ``regex`` - Filter the enumeration names according to a regular-expression
- ``index`` - Match the enumeration by its index
- ``identifier`` or ``id`` - Match the enumeration by its identifier
- ``predicate`` - Filter the enumerations by passing their identifier to a callable

-------------
Function list
-------------

The functions that are available in this module use multicased
functions and aliases. For more information on this, please see
:ref:`multicase-aliases` and :ref:`multicase-functions`.

.. py:function:: bitfield(enum)
   
   Return whether the enumeration identified by ``enum`` is a bitfield or not.
   
   :param enum: the enumeration to return the bitfield flag for
   
.. py:function:: bitfield(enum, boolean)
   
   Toggle the bitfield setting of the enumeration ``enum`` depending on the value of ``boolean``.
   
   :param enum: the enumeration to set the bitfield flag for
   :param boolean: whether to set the flag or clear it
   :type boolean: int or long or bool
   
.. py:function:: bits(enum)
   
   Return the number of bits for the enumeration ``enum``.
   
   :param enum: the enumeration to return the width of
   
.. py:function:: bits(enum, width)
   
   Set the number of bits for the enumeration ``enum`` to ``width``.
   
   :param enum: the enumeration to set the width for
   :param width: the number of bits to set the enumeration width to
   :type width: int or long
   
.. py:function:: by(index)
   
   Return the identifier for the enumeration at the specified ``index``.
   
   :param index: the index or id of the enumeration to return
   :type index: int or long
   
.. py:function:: by(name)
   
   Return the identifier for the enumeration with the specified ``name``.
   
   :param name: the name of the enumeration to return
   :type name: str
   
.. py:function:: by(\*\*type)
   
   Return the identifier for the first enumeration matching the keyword specified by ``type``.
   
   :param \*\*type: any keyword that can be used to filter enumerations with
   
.. py:function:: by_identifier(eid)
   
   Return the identifier for the enumeration using the specified ``eid``.
   
   Aliases: :py:func:`enumeration.byidentifier<by_identifier>`
   
   :param eid: the identifier of the enumeration to return
   
.. py:function:: by_index(index)
   
   Return the identifier for the enumeration at the specified ``index``.
   
   Aliases: :py:func:`enumeration.byindex<by_index>`
   
   :param index: the index of the enumeration to return
   
.. py:function:: by_name(name)
   
   Return the identifier for the enumeration with the given ``name``.
   
   Aliases: :py:func:`enumeration.byname<by_name>`
   
   :param name: the name of the enumeration to return
   
.. py:function:: comment(enum, \*\*repeatable)
   
   Return the comment for the enumeration ``enum``.
   
   If the bool ``repeatable`` is specified, then return the repeatable comment.
   
   :param enum: the enumeration to return the comment for
   :param \*\*repeatable: whether the returned comment should be repeatable or not
   
.. py:function:: comment(enum, comment, \*\*repeatable)
   
   Set the comment for the enumeration ``enum`` to ``comment``.
   
   If the bool ``repeatable`` is specified, then modify the repeatable comment.
   
   :param enum: the enumeration to modify the comment for
   :param comment: the comment to apply
   :type comment: str
   :param \*\*repeatable: whether the comment should be repeatable or not
   
.. py:function:: comment(enum, none, \*\*repeatable)
   
   Remove the comment from the enumeration ``enum``.
   
   :param enum:
   :param none:
   :type none: None
   :param \*\*repeatable:
   
.. py:function:: count()
   
   Return the total number of enumerations in the database.
   
.. py:function:: delete(enum)
   
   Delete the enumeration ``enum``.
   
   Aliases: :py:func:`enumeration.remove<delete>`
   
   :param enum: the enumeration to remove
   
.. py:function:: flags(enum)
   
   Return the flags for the enumeration identified by ``enum``.
   
   :param enum: the enumeration to return the flags for
   
.. py:function:: flags(enum, flags)
   
   Set the flags for the enumeration ``enum`` to the value specified by ``flags``.
   
   :param enum: the enumeration to return the flags for
   :param flags: the flags to apply to the enumeration
   :type flags: int or long
   
.. py:function:: has(enum)
   
   Return truth if an enumeration with the identifier ``enum`` exists within the database.
   
   :param enum: the enumeration identifier to check
   :type enum: int or long
   
.. py:function:: has(name)
   
   Return truth if an enumeration with the specified ``name`` exists within the database.
   
   :param name: the enumeration name to check
   :type name: str
   
.. py:function:: index(enum)
   
   Return the index in the enumeration list for the enumeration identified by ``enum``.
   
   :param enum: the enumeration to return the index of
   
.. py:function:: index(enum, index)
   
   Set the position in the enumeration list for the enumeration ``enum`` to the specified ``index``.
   
   :param enum: the enumeration to set the index for
   :param index: the index to change the enumeration to
   :type index: int or long
   
.. py:function:: iterate(\*\*type)
   
   Iterate through all of the enumerations in the database that match the keyword specified by ``type``.
   
   :param \*\*type: any keyword that can be used to filter enumerations with
   
.. py:function:: list(string)
   
   List any enumerations that match the glob in ``string``.
   
   :param string: the glob to filter the enumeration names with
   :type string: str
   
.. py:function:: list(\*\*type)
   
   List all of the enumerations within the database that match the keyword specified by ``type``.
   
   :param \*\*type: any keyword that can be used to filter enumerations with
   
.. py:function:: mask(enum)
   
   Return the bitmask for the enumeration ``enum``.
   
   :param enum: the enumeration to return the bitmask for
   
.. py:function:: name(enum)
   
   Return the name of the enumeration ``enum``.
   
   :param enum: the enumeration to return the name of
   
.. py:function:: name(enum, name)
   
   Rename the enumeration ``enum`` to the string ``name``.
   
   :param enum: the enumeration to rename
   :param name: the name to rename the enumeration to
   :type name: str
   
.. py:function:: names(enum)
   
   Return a set of all of the names belonging to the enumeration ``enum``.
   
   :param enum: the enumeration to return the names for
   
.. py:function:: new(name, flags=0)
   
   Create an enumeration with the specified ``name`` and ``flags`` using :py:obj:`idaapi.add_enum`.
   
   Aliases: :py:func:`enumeration.create<new>`
   
   :param name: the name of the new enumeration
   :param flags: any extra flags to pass to :py:obj:`idaapi.add_enum`
   
.. py:function:: repr(enum)
   
   Return a printable summary of the enumeration ``enum``.
   
   :param enum: the enumeration to summarize
   
.. py:function:: search(string)
   
   Return the identifier of the first enumeration that matches the glob ``string``.
   
   :param string: the glob to match the enumeration name with
   :type string: str
   
.. py:function:: search(\*\*type)
   
   Return the identifier of the first enumeration that matches the keyword specified by ``type``.
   
   :param \*\*type: any keyword that can be used to match an enumeration with
   
.. py:function:: size(enum)
   
   Return the number of bytes for the enumeration ``enum``.
   
   :param enum: the enumeration to return the width of
   
.. py:function:: size(enum, width)
   
   Set the number of bytes for the enumeration ``enum`` to ``width``.
   
   :param enum: the enumeration to set the width for
   :param width: the number of bytes to set the enumeration width to
   :type width: int or long
   
.. py:function:: up(enum)
   
   Return all structure or frame members within the database that reference the specified ``enum``.
   
   :param enum: the enumeration to return references for
   
.. py:function:: values(enum)
   
   Return a set of all of the values belonging to the enumeration ``enum``.
   
   :param enum: the enumeration to return the values of
   
--------------
Namespace list
--------------

These are the namespaces available within this module. Namespaces
group similar functions that can be used typically for the same
concept. Please see :ref:`multicase-namespaces` for more
information on namespaces. For more information on multicase
functions or aliases, please see :ref:`multicase-functions` or
:ref:`multicase-aliases`.

.. _ns-enumeration-masks:

*****************
enumeration.masks
*****************

This namespace allows one to interact with a masks that are within
an enumeration with its "bitfield" flag set. This is a very basic
namespace that provides some minor utilities to deal with the
naming of the bitmasks in an enumeration.

Some examples of how to use this namespace can be::

    > values = enum.masks('example_enumeration')
    > ok = enum.masks.has(eid, 'mask_name')
    > mask = enum.masks.by(eid, 'mask_name')
    > mask = enum.masks.by(eid, 0x1234)

.. py:function:: masks(enum)
   
   Iterate through all of the masks belonging to the enumeration ``enum`` and yield their name and value.
   
   :param enum: the enumeration to return the masks of
   
.. py:function:: masks\.comment(enum, mask, \*\*repeatable)
   
   Return the comment for the ``mask`` belonging to the enumeration ``enum``.
   
   If the bool ``repeatable`` is specified, then return the repeatable comment.
   
   :param enum: the enumeration to fetch a mask comment from
   :param mask: the mask to fetch the comment from
   :type mask: int or long
   :param \*\*repeatable: whether to return the repeatable comment or not
   
.. py:function:: masks\.comment(enum, mask, comment, \*\*repeatable)
   
   Set the comment for the ``mask`` belonging to the enumeration ``enum`` to ``comment``.
   
   If the bool ``repeatable`` is specified, then set the repeatable comment.
   
   :param enum: the enumeration containing the mask to set the comment for
   :param mask: the mask to set the comment of
   :type mask: int or long
   :param comment: the comment to assign to the mask
   :type comment: str
   :param \*\*repeatable: whether to set the repeatable comment or not
   
.. py:function:: masks\.comment(enum, mask, none, \*\*repeatable)
   
   Remove the comment for the ``mask`` belonging to the enumeration ``enum``.
   
   :param enum: the enumeration containing the mask to clear the comment of
   :param mask: the mask to clear the comment of
   :type mask: int or long
   :param none: the python value :py:obj:`None`
   :type none: None
   :param \*\*repeatable: whether to clear the repeatable comment or not
   
.. py:function:: masks\.has(enum, mask)
   
   Return whether the enumeration ``enum`` uses the specified ``mask``.
   
   :param enum: the enumeration to check the masks of
   :param mask: the bitmask to confirm
   
.. py:function:: masks\.iterate(enum)
   
   Iterate through all of the masks belonging to the enumeration ``enum``.
   
   :param enum: the enumeration to iterate through through the masks of
   
.. py:function:: masks\.list(enum)
   
   List all the masks belonging to the enumeration identified by ``enum``.
   
   :param enum: the enumeration containing the masks to list
   
.. py:function:: masks\.name(enum, mask)
   
   Return the name for the given ``mask`` belonging to the enumeration ``enum``.
   
   :param enum: the enumeration containing the mask to fetch
   :param mask: the mask to return the name of
   :type mask: int or long
   
.. py:function:: masks\.name(enum, mask, name)
   
   Set the name for the ``mask`` belonging to the enumeration ``enum`` to the provided ``name``.
   
   :param enum: the enumeration containing the mask to rename
   :param mask: the mask to set the name of
   :type mask: int or long
   :param name: the name to use when renaming the mask
   :type name: str or tuple
   
.. py:function:: masks\.name(enum, mask, name, \*suffix)
   
   Set the name for the ``mask`` belonging to the enumeration ``enum`` to the provided ``name``.
   
   :param enum: the enumeration containing the mask to rename
   :param mask: the mask to set the name of
   :type mask: int or long
   :param name: the name to use when renaming the mask
   :type name: str
   :param \*suffix: any other strings to append to the name
   
.. _ns-enumeration-member:

******************
enumeration.member
******************

This namespace allows one to interact with a member belonging
to an enumeration once the enumeration's id has been determined.
This allows one to modify the property of any one of an
enumeration's members.

Some examples of how to use this namespace can be::

    > eid = enum.by('example_enumeration')
    > mid = enum.members.by_value(eid, 0x1000)
    > oldname = enum.member.name(mid, 'somename')
    > oldvalue = enum.member.value(mid, 0x100)
    > oldcomment = enum.member.comment(mid, 'This is an example comment')
    > ok = enum.member.remove(mid)

.. py:function:: member\.by(mid)
   
   Return the enumeration member as specified by the provided ``mid``.
   
   :param mid: the identifier of the member to return
   
.. py:function:: member\.comment(mid, \*\*repeatable)
   
   Return the comment for the enumeration member ``mid``.
   
   If the bool ``repeatable`` is specified, then return the repeatable comment.
   
   :param mid: the identifier of an enumeration member to return the comment for
   :type mid: int or long
   :param \*\*repeatable: whether the returned comment should be repeatable or not
   
.. py:function:: member\.comment(enum, member, \*\*repeatable)
   
   Return the comment for the enumeration ``member`` belonging to ``enum``.
   
   :param enum: the enumeration containing the member to return the comment for
   :param member: the member to return the comment for
   :param \*\*repeatable: whether the returned comment should be repeatable or not
   
.. py:function:: member\.comment(mid, comment, \*\*repeatable)
   
   Set the comment for the enumeration member id ``mid`` to ``comment``.
   
   If the bool ``repeatable`` is specified, then set the repeatable comment.
   
   :param mid: the identifier of an enumeration containing the member to set the comment for
   :type mid: int or long
   :param comment: the comment to apply
   :type comment: str
   :param \*\*repeatable: whether the returned comment should be repeatable or not
   
.. py:function:: member\.comment(enum, member, comment, \*\*repeatable)
   
   Set the comment for the enumeration ``member`` belonging to ``enum`` to the string ``comment``.
   
   :param enum: the enumeration containing the member to set the comment for
   :param member: the member to set the comment for
   :param comment: the comment to apply
   :type comment: str
   :param \*\*repeatable: whether the returned comment should be repeatable or not
   
.. py:function:: member\.comment(enum, member, none, \*\*repeatable)
   
   Remove the comment from the ``member`` belonging to the enumeration ``enum``.
   
   :param enum:
   :param member:
   :param none:
   :type none: None
   :param \*\*repeatable:
   
.. py:function:: member\.mask(mid)
   
   Return the bitmask for the enumeration member ``mid``.
   
   :param mid: the identifier of an enumeration member to return the bitmask of
   :type mid: int or long
   
.. py:function:: member\.mask(enum, member)
   
   Return the bitmask for the enumeration ``member`` belonging to ``enum``.
   
   :param enum: the enumeration containing the member to return the bitmask for
   :param member: the member to return the bitmask for
   
.. py:function:: member\.name(mid)
   
   Return the name of the enumeration member ``mid``.
   
   :param mid: the identifier of the member to return the name for
   :type mid: int or long
   
.. py:function:: member\.name(enum, member)
   
   Return the name of the enumeration ``member`` belonging to ``enum``.
   
   :param enum: the enumeration containing the member to return the name for
   :param member: the member to return the name for
   
.. py:function:: member\.name(mid, name)
   
   Rename the enumeration member ``mid`` to ``name``.
   
   Aliases: :py:func:`enumeration.member.rename<member\.name>`
   
   :param mid: the identifier of an enumeration member
   :type mid: int or long
   :param name: the name to rename the enumeration member to
   :type name: str or tuple
   
.. py:function:: member\.name(enum, member, name, \*suffix)
   
   Rename the enumeration ``member`` belonging to ``enum`` to ``name``.
   
   Aliases: :py:func:`enumeration.member.rename<member\.name>`
   
   :param enum: the enumeration containing the member to rename
   :param member: the member to rename
   :param name: the name to rename the enumeration member to
   :type name: str
   :param \*suffix: any other names to append to the new name
   
.. py:function:: member\.parent(mid)
   
   Return the id of the enumeration that owns the member ``mid``.
   
   Aliases: :py:func:`enumeration.member.owner<member\.parent>`
   
   :param mid: the identifier of the member to return the enumeration for
   
.. py:function:: member\.refs(mid)
   
   Return the ``(address, opnum, type)`` of all the instructions that reference the enumeration member ``mid``.
   
   :param mid: the enumeration member identifier to return references for
   
.. py:function:: member\.refs(enum, member)
   
   Returns the ``(address, opnum, type)`` of all the instructions that reference the enumeration ``member`` belonging to ``enum``.
   
   :param enum: the enumeration to use
   :param member: the member name or identifier to return references for
   
.. py:function:: member\.remove(mid)
   
   Remove the enumeration member with the given ``mid``.
   
   :param mid: the identifier of the member to remove
   :type mid: int or long
   
.. py:function:: member\.remove(enum, member)
   
   Remove the specified ``member`` of the enumeration ``enum``.
   
   :param enum: the enumeration to remove a member from
   :param member: the member to remove
   
.. py:function:: member\.serial(mid)
   
   Return the serial of the enumeration member ``mid``.
   
   :param mid: the identifier of an enumeration member to return the serial for
   :type mid: int or long
   
.. py:function:: member\.serial(enum, member)
   
   Return the serial of the enumeration ``member`` belonging to ``enum``.
   
   :param enum: the enumeration containing the member to return the serial for
   :param member: the member to return the serial of
   
.. py:function:: member\.value(mid)
   
   Return the value of the enumeration member ``mid``.
   
   :param mid: the identifier of an enumeration member to return the value of
   :type mid: int or long
   
.. py:function:: member\.value(enum, member)
   
   Return the value of the specified ``member`` belonging to the enumeration ``enum``.
   
   :param enum: the enumeration containing the member to return the value of
   :param member: the member to return the value of
   
.. py:function:: member\.value(mid, value)
   
   Assign the integer specified by ``value`` to the enumeration member ``mid``.
   
   :param mid: the identifier of the member to set the value of
   :type mid: int or long
   :param value: the value to set the member to
   :type value: int or long
   
.. py:function:: member\.value(enum, member, value, \*\*bitmask)
   
   Set the ``value`` for the enumeration ``member`` belonging to ``enum``.
   
   :param enum: the enumeration containing the member to set the value for
   :param member: the member to set the value of
   :param value: the value to apply
   :type value: int or long
   :param \*\*bitmask: if ``bitmask`` is specified as an integer, then use it as the bitmask to assign to the value
   
.. _ns-enumeration-members:

*******************
enumeration.members
*******************

This namespace allows one to interact with the members belonging
to an enumeration once the enumeration's id has been determined.
This allows one to iterate through all of its members or add
and remove values to the enumeration.

By default this namespace will yield the names of all of the
members of an enumeration.

Some examples of using this namespace are::

    > eid = enum.by('example_enumeration')
    > mid = enum.members.add(eid, 'name', 0x1000)
    > ok = enum.members.remove(eid, mid)
    > mid = enum.members.by_name(eid, 'name')
    > mid = enum.members.by_value(eid, 0x1000)
    > for mid in enum.members.iterate(eid): ...
    > enum.members.list(e)

.. py:function:: members(enum)
   
   Yield the name, and value of each member from the enumeration ``enum``.
   
   If the enumeration ``enum`` is a bitfield, then yield each member's name, value, and bitmask.
   
   :param enum: the enumeration to yield the names for
   
.. py:function:: members\.add(enum, name, value, \*\*bitmask)
   
   Add an enumeration member ``name`` with the specified ``value`` to the enumeration ``enum``.
   
   If the integral, ``bitmask``, is specified then use it as the bitmask for the enumeration.
   
   Aliases: :py:func:`enumeration.member.new<members\.add>`, :py:func:`enumeration.member.create<members\.add>`
   
   :param enum: the enumeration to add a member to
   :param name: the name of the enumeration member
   :param value: the value of the enumeration member
   :param \*\*bitmask: if ``bitmask`` is specified as an integer, then use it as the bitmask for the enumeration
   
.. py:function:: members\.by(enum, n)
   
   Return the member belonging to ``enum`` identified by its index or id in ``n``.
   
   :param enum: the enumeration to return a member for
   :param n: an index or an identifier of the enumeration to return
   :type n: int or long
   
.. py:function:: members\.by(enum, name)
   
   Return the member of the enumeration ``enum`` with the given ``name``.
   
   :param enum: the enumeration to return a member for
   :param name: the name of the member to return
   :type name: str
   
.. py:function:: members\.by_identifier(enum, mid)
   
   Return the member of the enumeration specified by ``enum`` and its ``mid``.
   
   :param enum: the enumeration to return a member for
   :param mid: the identifier of the enumeration member to return
   
.. py:function:: members\.by_index(enum, index)
   
   Return the member identifier for the member of the enumeration ``enum`` at the specified ``index``.
   
   :param enum: the enumeration to return a member for
   :param index: the index of the enumeration member to return
   
.. py:function:: members\.by_name(enum, name)
   
   Return the member identifier for the member of the enumeration ``enum`` with the specified ``name``.
   
   Aliases: :py:func:`enumeration.member.byname<members\.by_name>`
   
   :param enum: the enumeration to return a member for
   :param name: the name of the enumeration member to return
   
.. py:function:: members\.by_value(enum, value, \*\*filters)
   
   Return the member identifier for the member of the enumeration ``enum`` with the specified ``value``.
   
   If the integrals, ``bitmask`` or ``serial``, is specified then use them to filter the returned enumeration members.
   
   Aliases: :py:func:`enumeration.member.byvalue<members\.by_value>`
   
   :param enum: the enumeration to return a member for
   :param value: the value of the enumeration member to return
   :param \*\*filters: the filters to use when choosing the enumeration member
   
.. py:function:: members\.has(enum, name)
   
   Return whether the enumeration ``enum`` contains a member with the specified ``name``.
   
   :param enum: the enumeration to use
   :param name: the name of the enumeration member to check
   :type name: str
   
.. py:function:: members\.has(enum, value, \*\*bitmask)
   
   Return whether the enumeration ``enum`` contains a member with the specified ``value``.
   
   If an integral is provided for ``bitmask`` or ``serial``, then only return true if the member is within the specified bitmask, or uses the provided serial.
   
   :param enum: the enumeration to use
   :param value: the value of the enumeration member to check
   :type value: int or long
   :param \*\*bitmask: if ``bitmask`` is specified as an integer, then check the value within the specified bitmask
   
.. py:function:: members\.iterate(enum)
   
   Iterate through all ids of each member associated with the enumeration ``enum``.
   
   :param enum: the enumeration containing the members to iterate through
   
.. py:function:: members\.list(enum)
   
   List all the members belonging to the enumeration identified by ``enum``.
   
   :param enum: the enumeration containing the members to list
   
.. py:function:: members\.mapping(enum)
   
   Return a dictionary mapping all the values values to their names for the enumeration ``enum``.
   
   :param enum: the enumeration containing the names and values to return
   
.. py:function:: members\.names(enum)
   
   Return a set of all the names belonging to the enumeration ``enum``.
   
   :param enum: the enumeration to return the names for
   
.. py:function:: members\.remove(mid)
   
   Remove the member identified by ``mid`` from the enumeration that owns it.
   
   :param mid:
   :type mid: int or long
   
.. py:function:: members\.remove(enum, member)
   
   Remove the specified ``member`` of the enumeration ``enum``.
   
   :param enum: the enumeration containing the member to remove
   :param member: the identifier or index of an enumeration member to remove
   
.. py:function:: members\.values(enum)
   
   Return a set of all the values belonging to the enumeration ``enum``.
   
   If the enumeration is a bitfield, then each item in the result is the value and its bitmask.
   
   :param enum: the enumeration to return the values of