IReport Plugins
===============

Interactive Reports (IReports) are plugins that generate output for Understand
to display. Report output and :class:`options <understand.Options>` are accessed
through the :class:`IReport <understand.IReport>` object provided as a parameter to the
`init` and `generate` functions.

The generated output can link to
:meth:`entities <understand.IReport.entity>`,
:meth:`locations <understand.IReport.syncfile>` and comparison database
:meth:`difference views <understand.IReport.compare>`. There are style options
such as :meth:`bold <understand.IReport.bold>`,
:meth:`italic <understand.IReport.italic>`, and
:meth:`color <understand.IReport.fontcolor>`. The output can also be structured
as a :meth:`tree <understand.IReport.tree>`.

An IReport plugin must have a `name` function and a `generate` function. The
`name` function identifies the report and the `generate` function creates
the output. At least one `test_` function should be defined to indicate
when the report is available. A sample plugin is below.

::

  def name():
    """
    Required, the name of the ireport.
    """
    return "Test Report"

  #
  # The following three functions determine when the report is available.
  # If ommitted, they're assumed false.
  #
  def test_global(db):
    """
    Optional method, return true for project level reports
    """
    return True

  def test_entity(ent):
    """
    Optional method, return true if report is valid for the entity
    """
    return True

  def test_architecture(arch):
    """
    Optional method, return true if report is valid for the architecture
    """
    return True

  #
  # Optional methods to support abort
  #
  def support_abort():
    """
    Optional method, return True if this report can be aborted.

    Use report.is_aborted() to check if an abort has been requested
    """
    return False;

  def pages(report,target):
    """
    Optional method for multi-page reports.

    A report can have multiple pages which each become their own html
    page, or are concantenated together in a pdf export. Implement this
    function to return all the pageIds that belong to this report. The
    pageId is used to construct links, and is not shown to the user.
    """
    return []

  # Report Options
  def init(report,target):
    """
    Optional method, define options that can be changed by the user
    """
    # Define options for the user to configure like this:
    report.options().checkbox("test", "This is a test", True)

  # Report generation
  def generate(report, target, pageId):
    """
    Required, generate the report

    The pageId parameter is optional. It will be an empty string the first
    time a report is generated. On subsequent generations, it can be any
    value returned from pages() or provided as a pageId to report.pagelink()
    or report.breadcrumbs() functions.
    """
    # If the report can be valid for multiple types of objects, use
    # isinstance to determine the target type.
    if isinstance(target, understand.Arch):
      report.print("arch: ")
    if isinstance(target, understand.Ent):
      report.print("ent: ")
    if isinstance(target, understand.Db):
      report.print("db: ")
    report.bold()
    # This take advantage of the fact that there is a name method
    # for entities, architectures, and datases.
    report.print(target.name())
    report.nobold()
    report.print("\n")

    # retrieve options defined in init like this:
    option = report.options().lookup("test")
    report.print("option: {}\n".format(option))