The Falcon compiler's IDefinition API is a very important part of the compiler to understand. The following text is a work in progress. Please feel free to correct any mistakes that might be found.

IDefinition

The IDefinition API is located in the org.apache.flex.compiler.definitions package. In this package you will find a high level abstraction of the ActionScript language. A definition is an element found within the source code that can be referred to by name; package, namespace, class, interface, function, getter, setter, parameter, variable, constant, event, style, or effect.

All definitions contain;

  • A source code location.
  • Optional metadata annotations. ( [Metadata] )
  • Namespace visibility ( public, protected, private or internal ).
  • Modifiers ( static, override )
  • A base name, this name is considered the unqualified name of the definition. ( FooBar not foo.bar.FooBar ) 
  • A reference to the containing ITypeDefinition, the class or interface owner. The type can be null for some definitions.

API Hierarchy

The IDefinition has the following basic structure;

  • IDefinition
    • IDocumentableDefinition
      • IMetadataDefinition
        • IEffectDefinition
        • IEventDefinition
        • ISkinPartDefinition
        • ISkinStateDefinition
        • IStyleDefinition
      • INamespaceDefinition
      • IScopedDefinition
        • More on the scopes below.
      • IVariableDefinition
        • IAccessorDefinition
          • IGetterDefinition
          • ISetterDefinition
        • IConstantDefinition
        • IParameterDefinition

The IScopedDefinition has the following basic structure;

  • IScopedDefinition
    • IFunctionDefinition, IVariableDefinition (not a scope but is super to accessor definition)
      • IAccessorDefinition
        • IGetterDefinition
        • ISetterDefinition
      • IMemberedDefinition
        • IPackageDefinition
        • ITypeDefinition
          • IClassDefinition
            • IAppliedVectorDefinition
            • ITypedClassNode
          • IInterfaceDefinition

A non-scroped definition does not contain a programing scope. A scoped definition will contain an IASScope. The IASScope together with the IDefinition API represents the Falcon compiler's symbol table. With access to these packages, almost anything is possible in dealing with analyzing how an ActionScript source file relates to itself and to it's dependencies.

IDocumentableDefinition

Note that most all definitions are an IDocumentableDefinition. This means that definitions can contain ASDoc comments. Currently there is zero support for asdoc in the Falcon compiler. There has already been experiments in creating a highlevel asdoc program working with the Falcon compiler.

The parser does collect the asdoc tokens but there is no work done actually parsing the asdoc String token and creating a model.

The IDocumentableDefinition contains the following

  • IASDocComment getExplicitSourceComment()
  • boolean hasExplicitComment()

IASDocComment

What is the IASDocComment?

For now, the IASDocComment is a placeholder for the real asdoc model that will be accessed from definitions. The implementation needs to be agreed upon I guess before methods are placed in it. Essentially the IASDocComment will need to be able to read-write;

  • Description
  • Short Description
  • Long Description
  • Add/Remove DocTag
  • Retrieve a Doctag by name
  • Retrieve a Collection of DocTags by name.

For more information on implementing asdoc you will need to see the IASDocDelegate and IASParserASDocDelegate. These classes will need to be registered with the parser in order to receive and digest asdoc comments during parsing so they can be saved onto the IDocumentableDefinition.

Note: Michael Schmalle has done extensive work with ASDoc and these delegates, feel free to contact him if interested in working on this type of implementation.

IFileNode

The IFileNode is not a definition but the api is important to understand. The file node usually contains the single public IPackageDefinition.

IPackageDefinition

The IPackageDefinition is the toplevel definition in the definition framework. Note that the package is not the root IASNode though, the IFileNode is the root node of a compiled File's AST.

ITypeDefinition

  • No labels