Architecture Plugins
====================

Architecture Plugins allow you to create automatic architectures that update
each time the project is analyzed. An Architecture plugin must have a `name`
function and a `build` function.

Automatic architectures are different than most plugins because there can be
multiple instances of a single architecture plugin. So the `name` function is
only the name of the plugin as it appears in the "New Automatic Architecture" list.
Each instance of the architecture is named by the user.

The `build` function should use the :meth:`add <understand.AutomaticArch.add>` method
of the :class:`AutomaticArch <understand.AutomaticArch>` parameter to add
entities to the architecture. Architecture plugins also support
:class:`options <understand.Options>` which can be set from `define_options`
and then read in the `build` function.

A sample architecture plugin is provided below that groups entities by long name.

::

  def name():
    """ Required, the name of the automatic architecture """
    return "Long Name"

  def description():
    """ Optional, a description of the automatic architecture. """

    return '''An architecture for grouping entities by long name.

    <p>By default, this architecture groups class entities by long name
    assuming "::" as a separator, appropriate for C++ projects. The entity
    kind string and separator can be configured. For example,
    the kind string can be set to "functions" to group functions instead of
    classes, or the separator can be set to "." for C# instead of C++.<p>
    '''

  def define_options(arch):
    """ Optional, define options """
    arch.options().text("kinds", "Kind String", "class ~unresolved ~member")
    arch.options().text("sep", "Separator", "::")

  def build(arch, db):
    """ Required, generate the architecture """
    sep = arch.options().lookup("sep")
    for ent in db.ents(arch.options().lookup("kinds")):
      parts = ent.longname().split(sep)
      if len(parts) > 1:
        # The add method is the heart of automatic architectures. Use '/'
        # separated fields to create sub architectures, or leave the name
        # empty to add the entity directly to the root.
        arch.add(ent, '/'.join(parts[:-1]))