Package ghidra.program.model.listing

# Interface ProgramModule

All Superinterfaces:
  `Group`

All Known Implementing Classes:
  `DBTraceProgramViewRootModule`

public interface ProgramModule extends Group
A `ProgramModule` is a group of `ProgramFragment`s and/or other `ProgramModule`s together with some related information such as a name, comment, and alias. Users create modules to overlay the program with a hierarchical structure. A child of a module is a fragment or module which it directly contains. A parent of a module is a module which has this module as a child. A module may be contained in more than one module. A `Program` always has at least one module, the root module. The root module cannot be removed and is the ancestor for all other modules and fragments in the program.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(ProgramFragment fragment)`
  Adds the given fragment as a child of this module.
  `void`
  `add(ProgramModule module)`
  Adds the given module as a child of this module.
  `boolean`
  `contains(ProgramFragment fragment)`
  Returns whether this module directly contains the given fragment as a child.
  `boolean`
  `contains(ProgramModule module)`
  Returns whether this module directly contains the given module as a child.
  `ProgramFragment`
  `createFragment(String fragmentName)`
  Creates a new fragment and makes it a child of this module.
  `ProgramModule`
  `createModule(String moduleName)`
  Creates a new module and makes it a child of this module.
  `AddressSetView`
  `getAddressSet()`
  Returns the set of addresses for this module which will be the combined set of addresses from the set of all fragments which are descendants of this module.
  `Group[]`
  `getChildren()`
  Returns an array containing this module's children.
  `Address`
  `getFirstAddress()`
  Returns the first address of this module which will be the minimum address of the first descendant fragment which is non-empty.
  `int`
  `getIndex(String name)`
  Get the index of the child with the given name.
  `Address`
  `getLastAddress()`
  Returns the last address of this module which will be the maximum address of the last descendant fragment which is non-empty.
  `Address`
  `getMaxAddress()`
  Returns the maximum address of this module which will be the maximum address from the set of all fragments which are descendants of this module.
  `Address`
  `getMinAddress()`
  Returns the minimum address of this module which will be the minimum address from the set of all fragments which are descendants of this module.
  `long`
  `getModificationNumber()`
  Get the current modification number of the module tree; the number is updated when ever a change is made to any module or fragment that is part of this module's root tree.
  `int`
  `getNumChildren()`
  Returns the number of children of this module.
  `long`
  `getTreeID()`
  Get the ID for the tree that this module belongs to.
  `Object`
  `getVersionTag()`
  Returns an object that can be used to detect when the module tree has been affected by an undo or redo.
  `boolean`
  `isDescendant(ProgramFragment fragment)`
  Returns whether the given fragment is a descendant of this module.
  `boolean`
  `isDescendant(ProgramModule module)`
  Returns whether the given module is a descendant of this module.
  `void`
  `moveChild(String name, int index)`
  Changes the ordering of this module's children by moving the child with the given name to position given by index.
  `boolean`
  `removeChild(String name)`
  Removes a child module or fragment from this Module.
  `void`
  `reparent(String name, ProgramModule oldParent)`
  Reparents child with the given name to this Module; removes the child from oldParent.

  ### Methods inherited from interface ghidra.program.model.listing.Group

  `contains, getComment, getGroupPath, getName, getNumParents, getParentNames, getParents, getTreeName, isDeleted, setComment, setName`

- ## Method Details

  - ### contains

    boolean contains(ProgramFragment fragment)
    Returns whether this module directly contains the given fragment as a child.
    Parameters:
      `fragment` - the fragment to check.

  - ### contains

    boolean contains(ProgramModule module)
    Returns whether this module directly contains the given module as a child.
    Parameters:
      `module` - the module to check.
    Returns:
      true if module is the same as this module, or if module is a child of this module.

  - ### getNumChildren

    int getNumChildren()
    Returns the number of children of this module.

  - ### getChildren

    Group[] getChildren()
    Returns an array containing this module's children.

  - ### getIndex

    int getIndex(String name)
    Get the index of the child with the given name.
    Parameters:
      `name` - name of child
    Returns:
      int index or -1 if this Module does not have a child with the given name

  - ### add

    void add(ProgramModule module) throws CircularDependencyException, DuplicateGroupException
    Adds the given module as a child of this module.
    Parameters:
      `module` - the module to be added.
    Throws:
      `CircularDependencyException` - thrown if the module being added is an ancestor of this module. The module structure of a program does not allow "cycles" of this sort to be created.
      `DuplicateGroupException` - thrown if the module being added is already a child of this module.

  - ### add

    void add(ProgramFragment fragment) throws DuplicateGroupException
    Adds the given fragment as a child of this module.
    Throws:
      `DuplicateGroupException` - thrown if the fragment being added is already a child of this module.

  - ### createModule

    ProgramModule createModule(String moduleName) throws DuplicateNameException
    Creates a new module and makes it a child of this module.
    Parameters:
      `moduleName` - the name to use for the new module.
    Returns:
      the newly created module.
    Throws:
      `DuplicateNameException` - thrown if the given name is already used by an existing module or fragment.

  - ### createFragment

    ProgramFragment createFragment(String fragmentName) throws DuplicateNameException
    Creates a new fragment and makes it a child of this module.
    Parameters:
      `fragmentName` - the name to use for the new fragment.
    Returns:
      the newly created fragment.
    Throws:
      `DuplicateNameException` - thrown if the given name is already used by an existing module or fragment.

  - ### reparent

    void reparent(String name, ProgramModule oldParent) throws NotFoundException
    Reparents child with the given name to this Module; removes the child from oldParent.
    Parameters:
      `name` - name of child to reparent
      `oldParent` - old parent
    Throws:
      `NotFoundException` - if name is not the name of a child in oldParent

  - ### moveChild

    void moveChild(String name, int index) throws NotFoundException
    Changes the ordering of this module's children by moving the child with the given name to position given by index.
    Parameters:
      `name` - the name of the child to move.
      `index` - the index to move it to.
    Throws:
      `NotFoundException` - thrown if a child with the given name cannot be found in this module.

  - ### removeChild

    boolean removeChild(String name) throws NotEmptyException
    Removes a child module or fragment from this Module.
    Returns:
      true if successful, false if no child in this module has the given name.
    Throws:
      `NotEmptyException` - thrown if the module appears in no other modules and it is not empty.

  - ### isDescendant

    boolean isDescendant(ProgramModule module)
    Returns whether the given module is a descendant of this module.
    Parameters:
      `module` - the module to check.
    Returns:
      true if the module is a descendant, false otherwise.

  - ### isDescendant

    boolean isDescendant(ProgramFragment fragment)
    Returns whether the given fragment is a descendant of this module.
    Parameters:
      `fragment` - the fragment to check.
    Returns:
      true if the fragment is a descendant, false otherwise.

  - ### getMinAddress

    Address getMinAddress()
    Returns the minimum address of this module which will be the minimum address from the set of all fragments which are descendants of this module.
    Specified by:
      `getMinAddress` in interface `Group`
    Returns:
      the minimum address, this will be null if all of the module's descendant fragments are empty.

  - ### getMaxAddress

    Address getMaxAddress()
    Returns the maximum address of this module which will be the maximum address from the set of all fragments which are descendants of this module.
    Specified by:
      `getMaxAddress` in interface `Group`
    Returns:
      the maximum address, this will be null if all of the module's descendant fragments are empty.

  - ### getFirstAddress

    Address getFirstAddress()
    Returns the first address of this module which will be the minimum address of the first descendant fragment which is non-empty. In other words this returns the first address for this module as defined by the user ordering of the module's children.
    Returns:
      the first address, this will be null if all of the module's descendant fragments are empty.

  - ### getLastAddress

    Address getLastAddress()
    Returns the last address of this module which will be the maximum address of the last descendant fragment which is non-empty. In other words this returns the last address for this module as defined by the user ordering of the module's children.
    Returns:
      the last address, this will be null if all of the module's descendant fragments are empty.

  - ### getAddressSet

    AddressSetView getAddressSet()
    Returns the set of addresses for this module which will be the combined set of addresses from the set of all fragments which are descendants of this module.
    Returns:
      the complete address set for this module.

  - ### getVersionTag

    Object getVersionTag()
    Returns an object that can be used to detect when the module tree has been affected by an undo or redo. After an undo/redo, if this module was affected, then a new verionTag object is created.

  - ### getModificationNumber

    long getModificationNumber()
    Get the current modification number of the module tree; the number is updated when ever a change is made to any module or fragment that is part of this module's root tree.

  - ### getTreeID

    long getTreeID()
    Get the ID for the tree that this module belongs to.
    Returns:
      ID for the tree