Module dev.civl.abc
Package dev.civl.abc.ast.entity.IF

Interface Scope

public interface Scope

A lexical (static) scope in a translation unit. The C11 Standard specifies 4 kinds of scopes: FILE, BLOCK, FUNCTION, and FUNCTION_PROTOTYPE.

A scope contains declarations of various kinds of entities. An "entity" is any conceptual thing which can be named using an identifier. An entity may be declared in more than one scope (though the process of "linkage").

Global declarations are in the FILE scope. A BLOCK scope corresponds to a block. The BLOCK scope corresponding to a function body includes the formal parameters as well as the outermost local parameters. The only entities with FUNCTION scope are (standard) labels---the labels that can be used as a target of a "goto" statement. A FUNCTION_PROTOTYPE scope occurs only in a function prototype, i.e., a function declaration without body; such a scope extends to the end of the declarator for the function prototype.

The set of all scopes in a translation unit forms a tree. The root of the tree is the FILE scope.

There are four kinds of name spaces in a scope: (1) the label namespace, which consists of all the (standard) label names in the scope; (2) the tag namespace, which consists of all the tags used in struct, union, and enumeration definitions; (3) the "member" namespaces (one namespace for each struct or union containing the field names for that struct or union); and (4) the namespace for "ordinary identifiers"---those declared in an ordinary (not struct or union) declarator, or as an enumeration constant---, this includes typedef names, variables, and functions. For example, the same identifier "X" could be used to denote a label, the tag of a struct, a member of that struct, and a variable, all in the same scope. However, "X" could not denote both a variable and a function in the same scope; nor could it denote both a struct tag and an enumeration tag in the same scope; but two different structs in the same scope can both have a field named "X".

Ordinary entities include: functions, variables (that are not fields), enumeration constants, and typedefs.

Note that "label" means standard label: the kind that is specified by an identifier followed by a colon. Not a "case label" (CASE followed by a constant expression then colon, used in switch statements), and not the "default" label (also used in switch statements).

Note: Entities can have no name. It is OK if two distinct entities have no name; they are not the same entity. It is as if each is given a new name distinct from all other names.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    Scope.ScopeKind
    The different kinds of scopes: file, block, function, function-prototype, and contract.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    add(Label label)
    Adds the given label to the list of labels occurring in this scope.
    int
    add(OrdinaryEntity entity)
    Adds an ordinary entity to this scope's collection of entities.
    int
    add(TaggedEntity entity)
    Adds a tagged entity (an enumeration, structure, or union) to this scope.
    boolean
    addFunctionName(String name)
    Adds the name of a function defined in this scope.
    boolean
    contains(Label label)
    Does the given label already belong to this scope?
    AST
    getAST()
    Returns the AST to which this scope belongs.
    Iterator<Scope>
    getChildrenScopes()
    Returns an iterator over the children scope of this scope.
    Scope
    getChildScope(int index)
    Returns the child scope of this scope, indexed from 0.
    Function
    getFunction(int index)
    The functions in this scope are assigned ID numbers 0, 1, 2, ..., at completion time.
    Set<String>
    getFunctionNames()
    Returns the set of names of functions defined in this scope.
    Iterable<Function>
    getFunctions()
    Returns an iterator over the functions defined in this scope, in order of increasing function index.
    int
    getId()
    Returns the ID number of this scope, unique among the scope of its translation unit.
    Label
    getLabel(int labelId)
    Gets the label with the given label ID.
    Label
    getLabel(String name)
    Gets the label declared in this scope with the given name.
    Iterator<Label>
    getLabels()
    Returns iterator over all (standard) labels declared in this scope.
    Label
    getLexicalLabel(String name)
    Finds the label with the given name in this or any ancestor scope.
    OrdinaryEntity
    getLexicalOrdinaryEntity(boolean isType, String name)
    Performs search for ordinary entity with given name using lexical scoping: if entity is not found in this scope, search the parent scope, etc.
    TaggedEntity
    getLexicalTaggedEntity(String tag)
    Performs search for struct/union/enumeration entity with given tag using lexical scoping: if entity is not found in this scope, search the parent scope, etc.
    int
    getNumChildrenScopes()
    The number of children of this scope in the scope tree.
    int
    getNumFunctions()
    Returns the number of functions in this scope.
    int
    getNumLabels()
    Returns the number of (standard) labels declared in this scope.
    int
    getNumVariables()
    Returns the number of variables declared in this scope.
    Iterable<OrdinaryEntity>
    getOrdinaryEntities()
    Gets the set of all ordinary entities declared in this scope, represented as an iterable object.
    OrdinaryEntity
    getOrdinaryEntity(boolean isType, String name)
    Gets the ordinary entity (variable/function/enumeration constant/typedef) in this scope with the given name, or null if there is not one.
    Scope
    getParentScope()
    The parent scope, i.e., the scope directly containing this one.
    int
    getScopeDepth()
    Returns the depth of this scope as a node in the scope tree.
    Scope.ScopeKind
    getScopeKind()
    Returns the kind of scope this is.
    Iterable<TaggedEntity>
    getTaggedEntities()
    Gets the set of all tagged entities declared in this scope, represented as an iterable object.
    TaggedEntity
    getTaggedEntity(String tag)
    Gets the tagged entity (struct/union/enumeration) in this scope with the given tag, or null if there is not one.
    Variable
    getVariable(int index)
    The variables in this scope are assigned variable ID numbers 0, 1, 2, ..., at completion time.
    Iterable<Variable>
    getVariables()
    Returns an iterator over the variables in this scope, in order of increasing variable ID.
    boolean
    isDescendantOf(Scope that)
    Determines whether this scope is equal to or a descendant of the given scope.
    void
    print(PrintStream out)
    Prints complete description of this scope.
    void
    print(String prefix, PrintStream out)
    Prints complete description of this scope, with each line preceded by the string prefix.
    void
    setId(int id)
    Sets the ID number of this scope, which should be unique among the ID numbers of the scopes of its translation unit.

  • Method Details

    • getScopeKind

      Scope.ScopeKind getScopeKind()
      Returns the kind of scope this is.
      Returns:
      the scope kind

    • getId

      int getId()
      Returns the ID number of this scope, unique among the scope of its translation unit.
      Returns:
      the scope ID

    • setId

      void setId(int id)
      Sets the ID number of this scope, which should be unique among the ID numbers of the scopes of its translation unit.
      Parameters:
      id - value to which ID number will be set

    • getAST

      AST getAST()
      Returns the AST to which this scope belongs.
      Returns:
      the AST to which this scope belongs

    • getParentScope

      Scope getParentScope()
      The parent scope, i.e., the scope directly containing this one. Null if this is the root scope.
      Returns:
      the parent scope

    • getNumChildrenScopes

      int getNumChildrenScopes()
      The number of children of this scope in the scope tree.
      Returns:
      the number of children scopes of this scope

    • getChildScope

      Scope getChildScope(int index)
      Returns the child scope of this scope, indexed from 0.
      Parameters:
      index - integer between 0 and numChildrenScope-1, inclusive
      Returns:
      child scope number index
      Throws:
      IllegalArgumentException - if index is out of bounds

    • getChildrenScopes

      Iterator<Scope> getChildrenScopes()
      Returns an iterator over the children scope of this scope.
      Returns:
      an iterator over all children scopes

    • getScopeDepth

      int getScopeDepth()
      Returns the depth of this scope as a node in the scope tree. The FILE scope has depth 0. Its immediate children have depth 1. Etc.
      Returns:
      depth of this scope as node in scope tree

    • getFunctionNames

      Set<String> getFunctionNames()
      Returns the set of names of functions defined in this scope. This is computed BEFORE the complete information on this scope is formed.
      Returns:
      the set of names of functions defined in this scope.

    • addFunctionName

      boolean addFunctionName(String name)
      Adds the name of a function defined in this scope.
      Parameters:
      name - the name of the function
      Returns:
      true iff that name was not already used to define a function in this scope

    • getOrdinaryEntities

      Iterable<OrdinaryEntity> getOrdinaryEntities()
      Gets the set of all ordinary entities declared in this scope, represented as an iterable object.
      Returns:
      iterable over all ordinary entities declared in this scope

    • add

      int add(OrdinaryEntity entity) throws UnsourcedException
      Adds an ordinary entity to this scope's collection of entities.
      Parameters:
      entity - an ordinary entity to be added to this scope
      Returns:
      the number of ordinary entities beloning to this scope before the new one was added; this number becomes the index of the ordinary entity
      Throws:
      UnsourcedException - if the entity cannot be added to this scope for some reason, for example, because there is already an ordinary entity with that name in this scope

    • getOrdinaryEntity

      OrdinaryEntity getOrdinaryEntity(boolean isType, String name)
      Gets the ordinary entity (variable/function/enumeration constant/typedef) in this scope with the given name, or null if there is not one. This does not look in ancestor or descendant scopes.
      Parameters:
      isType - true iff this is to get an entity of typedef; if false then the first entity from the bottom of the scope is returned, regardless of whether it is typedef or not
      name - the name of the ordinary entity
      Returns:
      the ordinary entity in this scope with that name or null if none exists

    • getLexicalOrdinaryEntity

      OrdinaryEntity getLexicalOrdinaryEntity(boolean isType, String name)
      Performs search for ordinary entity with given name using lexical scoping: if entity is not found in this scope, search the parent scope, etc. Returns first occurrence of ordinary entity with this name, searching in that order. If not found all the way up the scopes, returns null.
      Parameters:
      isType - true iff this is to get an entity of typedef; if false then the first entity from the bottom of the scope is returned, regardless of whether it is typedef or not
      name - name of the entity
      Returns:
      the first ordinary entity encountered with given name looking up the scope tree, or null

    • getNumVariables

      int getNumVariables()
      Returns the number of variables declared in this scope. The set of variables is a subset of the set of entities. Variables include global variables, local variables declared in any block scope, including formal parameters to a function. They do not include members of structures or unions (aka "fields"). They do not include enumeration constants. Note this does not include variables in ancestors or descendants of this scope.
      Returns:
      the number of variables declared in this scope

    • getVariable

      Variable getVariable(int index)
      The variables in this scope are assigned variable ID numbers 0, 1, 2, ..., at completion time. This method returns the variable with the given ID. Note that the variable ID is not necessarily the same as the entity ID.
      Returns:
      the index-th variable in this scope, indexed from 0

    • getVariables

      Iterable<Variable> getVariables()
      Returns an iterator over the variables in this scope, in order of increasing variable ID.
      Returns:
      an iterable over the variables in this scope.

    • getNumFunctions

      int getNumFunctions()
      Returns the number of functions in this scope. Note this does not include functions in ancestors of this scope. The functions are of course a subset of the set of Entities.
      Returns:
      the number of functions in this scope

    • getFunction

      Function getFunction(int index)
      The functions in this scope are assigned ID numbers 0, 1, 2, ..., at completion time. This method returns the function with the given index.
      Returns:
      the index-th function in this scope, counting from 0

    • getFunctions

      Iterable<Function> getFunctions()
      Returns an iterator over the functions defined in this scope, in order of increasing function index.
      Returns:
      iterator over functions in this scope

    • getTaggedEntities

      Iterable<TaggedEntity> getTaggedEntities()
      Gets the set of all tagged entities declared in this scope, represented as an iterable object.
      Returns:
      iterable over all tagged entities declared in this scope

    • add

      int add(TaggedEntity entity) throws SyntaxException
      Adds a tagged entity (an enumeration, structure, or union) to this scope. Tagged entities occupy a separate name space from ordinary entities.
      Parameters:
      entity - a tagged entity
      Returns:
      the number of tagged entities belonging to this scope before the new one was added; this number is the index of the newly added tagged entity in the tagged entity list
      Throws:
      SyntaxException - if the entity cannot be added to this scope for some reason, for example, because there is already a tagged entity with the same name in this scope

    • getTaggedEntity

      TaggedEntity getTaggedEntity(String tag)

      Gets the tagged entity (struct/union/enumeration) in this scope with the given tag, or null if there is not one. This does not look in parent or descendant scopes.

      Once you get the tagged entity, you can get its member entities (enumeration constants or fields). Those member entities are also part of this scope. The enumeration constants share the same name space as ordinary identifiers in this scope, but the fields are in their own entity-specific namespace.

      Parameters:
      tag - the tag
      Returns:
      the tagged entity in this scope with that name or null if none exists

    • getLexicalTaggedEntity

      TaggedEntity getLexicalTaggedEntity(String tag)
      Performs search for struct/union/enumeration entity with given tag using lexical scoping: if entity is not found in this scope, search the parent scope, etc. Returns first occurrence of entity with this tag, searching in that order. If not found in any ancestor, returns null.
      Returns:
      the first tagged entity encountered with the given tag, lookin up the scope tree

    • add

      int add(Label label) throws UnsourcedException
      Adds the given label to the list of labels occurring in this scope.
      Parameters:
      label - a label
      Returns:
      the number of labels belonging to this scope before the new one was added; this is the index of the new label in the list of labels
      Throws:
      UnsourcedException - if the label cannot be added for some reasons, for example, because there is already a label with the same name

    • contains

      boolean contains(Label label)
      Does the given label already belong to this scope?
      Parameters:
      label - a label
      Returns:
      true iff the list of labels belonging to this scope contains the given label

    • getLabel

      Label getLabel(String name)
      Gets the label declared in this scope with the given name. Labels only exist in a FUNCTION scope. A Label is an entity.
      Parameters:
      name - the label name
      Returns:
      the label in this scope with that name or null if none exists

    • getLexicalLabel

      Label getLexicalLabel(String name)
      Finds the label with the given name in this or any ancestor scope.
      Parameters:
      name - label name
      Returns:
      label with name or null

    • getLabels

      Iterator<Label> getLabels()
      Returns iterator over all (standard) labels declared in this scope.
      Returns:
      iterator over all standard labels declared in this scope

    • getNumLabels

      int getNumLabels()
      Returns the number of (standard) labels declared in this scope.
      Returns:
      number of labels in this scope

    • getLabel

      Label getLabel(int labelId)
      Gets the label with the given label ID.
      Parameters:
      labelId - the label's id
      Returns:
      the label with the given id
      Throws:
      IllegalArgumentException - if the labelId is less than 0 or greater than or equal to the number of labels in this scope

    • print

      void print(String prefix, PrintStream out)
      Prints complete description of this scope, with each line preceded by the string prefix.
      Parameters:
      prefix - any string
      out - PrintStream to which output is directed

    • print

      void print(PrintStream out)
      Prints complete description of this scope.
      Parameters:
      out - PrintStream to which output is directed

    • isDescendantOf

      boolean isDescendantOf(Scope that)
      Determines whether this scope is equal to or a descendant of the given scope. This mean either this == that or the parent of this is a descendant of that.
      Parameters:
      that - another scope, not null
      Returns:
      true iff this scope is a descendant (or equal to) that scope