Examples
========

The following examples are meant to be complete, yet simplistic
scripts that demonstrate one or more features each. For the sake of
brevity, most error handling is ommitted.

.. _exSortedEnts:

Sorted List of All Entities
---------------------------

::

  import understand

  # Open Database
  db = understand.open("test.udb")

  for ent in sorted(db.ents(),key= lambda ent: ent.name()):
    print (ent.name(),"  [",ent.kindname(),"]",sep="",end="\n")

.. _exFileList:

List of Files
-------------

::

  import understand

  # Open Database
  db = understand.open("test.udb")

  for file in db.ents("File"):
    # print directory name
    print (file.longname())

.. _exEntLookup:

Lookup an Entity (Case Insensitive)
-----------------------------------

::

  import understand
  import re

  db = understand.open("test.udb")

  # Create a regular expression that is case insensitive
  searchstr = re.compile("test*.cpp",re.I)
  for file in db.lookup(searchstr,"File"):
    print (file)

.. _exGlobalVarUsage:

Global Variable Usage
---------------------

::

  import understand

  db = understand.open("test.udb")

  for ent in db.ents("Global Object ~Static"):
    print (ent,":",sep="")
    for ref in ent.refs():
      print (ref.kindname(),ref.ent(),ref.file(),"(",ref.line(),",",ref.column(),")")
    print ("\n",end="")

.. _exFuncWithParam:

List of Functions with Parameters
---------------------------------

::

  import understand

  def sortKeyFunc(ent):
    return str.lower(ent.longname())

  db = understand.open("test.udb")

  ents = db.ents("function,method,procedure")
  for func in sorted(ents,key = sortKeyFunc):
    print (func.longname()," (",sep="",end="")
    first = True
    for param in func.ents("Define","Parameter"):
      if not first:
        print (", ",end="")
      print (param.type(),param,end="")
      first = False
    print (")")

.. _exFuncWithComments:

List of Functions with Associated Comments
------------------------------------------

::

  import understand

  db = understand.open("test.udb")

  for func in db.ents("function ~unresolved ~unknown"):
    comments = func.comments("after")
    if comments:
      print (func.longname(),":\n  ",comments,"\n",sep="")

.. _exAdaPackages:

List of Ada Packages
--------------------

::

  import understand

  db = understand.open("test.udb")

  print ("Standard Packages:")
  for package in db.ents("Package"):
    if package.library() == "Standard":
      print ("  ",package.longname())

  print ("\nUser Packages:")
  for package in db.ents("Package"):
    if package.library() != "Standard":
      print("  ",package.longname())

.. _exProjectMetrics:

All Project Metrics
-------------------

::

  import understand

  db = understand.open("test.udb")

  metrics = db.metric(db.metrics())
  for k,v in sorted(metrics.items()):
    print (k,"=",v)

.. _exCyclomaticFuncs:

Cyclomatic Complexity of Functions
----------------------------------

::

  import understand

  db = understand.open("test.udb")

  for func in db.ents("function,method,procedure"):
    metric = func.metric(("Cyclomatic",))
    if metric["Cyclomatic"] is not None:
      print (func," = ",metric["Cyclomatic"],sep="")

.. _exCalledByGraphs:

"Called By" Graphs of Functions
-------------------------------

::

  import understand

  db = understand.open("test.udb")

  for func in db.ents("function,method,procedure"):
    file = "callby_" + func.name() + ".png"
    print (func.longname(),"->",file)
    func.draw("Called By",file)

.. _exInfoBrowser:

Info Browser View of Functions
------------------------------

::

  import understand

  db = understand.open("test.udb")

  for func in db.ents("function,method,procedure"):
    for line in func.ib():
      print(line,end="")

.. _exLexicalStream:

Lexical Stream
--------------

::

  import understand

  db = understand.open("test.udb")

  file = db.lookup("test.cpp")[0]
  for lexeme in file.lexer():
    print (lexeme.text(),end="")
    if lexeme.ent():
      print ("@",end="")