From The Oxygene Language Wiki

What is Cirrus

Cirrus is a way of interacting with the compiler during the compiling process by the use of aspect attributes or method aspects. Aspect attributes are like regular .NET attributes with an aspect: prefix. Cirrus consists of a small library which contains interfaces and simple classes but no logic, and the implementation in the compiler library. Users use the Cirrus library so they don't have to depend on a specific version of the compiler since the Cirrus library does not change versions as often as the compiler does. A Cirrus attribute is always defined in a different assembly than what it's used from, so the compiler can execute the code in the aspect library as part of the compile process. Since Cirrus is part of the compiler, it does the weaving during the compile process, not after it, making it possible to interact with the compiler on multiple levels, for example by introducing new members on classes or even new classes and letting the user access those members directly, as if they were defined in code.

Aspect Attributes

How does it work

When compiling, the compiler will try to load the library containing an aspect when it's referenced with the [aspect: ] syntax and create an instance of the actual aspect attribute class. It will pass the parameter values as they are defined by the user and after the constructor it will assign the named parameters to properties by those names on the aspect.

Callbacks

Attribute classes in Cirrus have to implement the interfaces they want callbacks for. There are several interfaces:

Services

All the Handle* call back methods include a Services instance that can be used to find and create new types, and an instance of the member they can change. The services interface also has methods to emit errors, hints and warnings to the compiler. The GetType api will raise an exception on failure, the FindType api will return nil, both require the full type name, including the `count for generic types, like "System.Collections.Generic.IList`1", the ITypeDefinition and IMemberDefinition interfaces have a FindContextType/GetContextType method that allows passing "array of " and adding generic parameters to classes to instantiate them.

Values and Statements

The Cirrus library contains a class for every kind of value and statement the compiler supports. These classes are defined in the "RemObjects.Oxygene.Cirrus.Values" and "RemObjects.Oxygene.Cirrus.Statements" namespaces and they are used to replace or modify values (like the read or write expression of a property) or replace the body of a method. There is one special kind of statement class called the PlaceHolderStatement, when replacing the body of a method the original body will be inserted in the location of the place holder.

Quoting and Unquoting

While the statement and value classes provide a very powerful way of accessing and replacing code in the compiler, they require rather a lot of code to be written to do simple things. That's why the compiler supports a special kind of anonymous method that will automatically be converted to Statement and Value trees by the compiler. The compiler will automatically do this conversion when the target of the anonymous method is a StatementDelegate. One of the places this delegate call is used is on the SetBody method for the IMethodDeclaration class:

aMethod.SetBody(Services, method begin
      try
        Aspects.OriginalBody;
      finally
        LogMessage('Exiting '+unquote<string>(new DataValue(aMethod.Name)));
      end;
    end);

When the compiler encounters this, it will generate a new BeginStatement, with a TryStatement, a PlaceHolderStatement and ProcValue to call the LogMessage method. In this method you'll notice the use of the unquote compiler function. If I had used "aMethod.Name" directly here, I would have gotten a compiler error, since the method whose body will be replaced won't have a parameter called "aMethod", which is the parameter for the aspect handler. The unquote compiler function will insert a new instance of DataValue which contains the value of aMethodName – the method name as string – in the tree instead, which can be safely inserted here. The generic parameter for this method is what the compiler will use as the type of the expression. Unquote can also be used to insert raw statements into the tree; to do this, use unquote(SomeStatement) as a standalone command.

Special Functions inside aspect anonymous method bodies

The "Aspects" class is a class with methods that are treated specially by the compiler when it converts an anonymous method body to a statement tree. It has several useful methods to make writing aspects easier:

 var aName := Aspects.RequireLocal;

 var aUsername := Aspects.RequireParameter<string>;

 var aName := Aspects.RequireResult;

Method Call Aspects

Method Call Aspects are aspects that change the behavior of a call to a specific method (inside or outside the target assembly), all methods on a specific type or all methods on all types in a given namespace. A method aspect implements the IMethodCallDecorator interface. The ProcessMethodCall method is called each time the target method(s) are called and will allow the implementation to change the call in any way.

See Also

• Cirrus
  • Introduction
  • Overview
  • Namespaces: Cirrus – Cirrus Values – Cirrus Statements
  • Classes
  • Interfaces
  • Enums
• External Links:
  • Prism Aspects to Help with Monobjc Development (RemObjects Blogs)

Area: Oxygene Language
Compiler version: Oxygene 5