root/cobra/trunk/Source/Cobra.Lang/Visitor.cobra

use System.Reflection


namespace Cobra.Lang

    class Visitor
        is abstract
        """
        The visitor design pattern is a way of separating an algorithm from an object structure upon
        which it operates. This enables the addition of new operations to existing object structures
        without modifying those structures. [1]
    
        This class implements the visitor pattern, but via reflection so as to not require that the
        classes being visited implement any additional methods for "double dispatch". This approach
        enables less coding and an even greater degree of modularity. It also enables visitation
        directly on final classes, structs, library classes, etc. with no wrapper classes. [2]
    
        In order to leverage this class, you must create a concrete subclass.
    
        Subclasses must override .methodName and then simply implement visitation methods with that
        name and the appropriate parameter types.
    
        When enumerating through subobjects, invoke .dispatch to get type specific dispatch. You can
        also .dispatch on a sequence of objects which will .dispatch on each specific one.
    
        If you add a subclass to the class hierarchy that is being visited then you must either
            (1) remember to implement a method in your visitor class for that specific type, or
            (2) be content when a visitation method for one of its ancestor classes is invoked for it.
    
        If you look at the example much further below, you will get a better idea of what to do.
        Another read of the notes after examining the example could be useful.
    
        Alternatives to the visitor pattern:
    
            * Class extensions. You could put multiple, related class extensions in the same file.
              A pro is that this can make the additional functionality feel like a natural part of the
              classes. A con is that state must be passed from method to method. Also, method signatures
              will have to be updated if additional state is added (unless state is grouped into a
              single context/container object). With the visitor pattern, the state can be stored in the
              instance of the visitor.
    
            * Partial classes. These have the same advantages of class extensions, but without the
              disadvantage of having to pass state around. However, the con is that this is not
              available if the classes are external to your project. For example, if the classes come
              from a library or you are writing a plugin for an application, then partial classes are
              not available.
    
        References:
    
            [1] http://en.wikipedia.org/wiki/Visitor_pattern
            [2] http://www.javaworld.com/javaworld/javatips/jw-javatip98.html
    
        Future:
    
            * Could add a 'strict' mode where if the argument type is not an exact match for the found
              method, an exception is raised. This would help when you don't desire that subclasses are
              silently handled as described above.
        """
    
        var _willCache = true
        var _methods = Dictionary<of Type, MethodInfo>()
        var _methodName as String
        
        cue init
            base.init
            _methodName = .methodName
            if _methodName[0].isLower
                _methodName = _methodName[0].toUpper.toString + _methodName[1:]
    
        get methodName as String is abstract
            """
            Returns the method name looked up in .dispatch.
            """
            # ensure result.length > 0
    
        def dispatch(obj as Object?)
            """
            Performs type specific dispatch on the given object.
            A subclass can override this method to change the dispatch logic.
            """
            if obj is nil, return
            objType = obj.getType
            methInfo as MethodInfo?
            if _willCache, _methods.tryGetValue(objType, out methInfo)
            if methInfo is nil
                methInfo = .getType.getMethod(_methodName, @[objType])
                if methInfo is nil
                    throw InvalidOperationException('Cannot find a method "[_methodName]" with arg type "[objType]"')
                _methods[objType] = methInfo to !
            methInfo.invoke(this, @[obj])  # would be nice to speed this up
    
        def dispatch(objects as System.Collections.IEnumerable)
            """
            Performs type specific dispatch on each object in order.
            """
            for obj in objects, .dispatch(obj)