ruby-uml 0.2.2

data/lib/uml/lowlevel_backtracer.rb

@@ -0,0 +1,56 @@
+require 'singleton'
+require 'observer'
+
+module UML
+
+  class LowlevelBacktracer
+    include Singleton
+    include Observable
+        
+    attr_reader :call_stack
+    
+    def initialize
+      @call_stack = []
+      set_trace_func method(:tracer).to_proc
+    end
+
+  private
+  
+    def tracer(event, filename, linenumber, method_symbol, binding, klass)
+      begin
+
+        case event
+        when 'call', 'c-call'
+          # args describe the endpoint of call
+
+          actual_information = {
+            :filename      => filename,
+            :linenumber    => linenumber,
+            :method_symbol => method_symbol,
+            :binding       => binding,
+            :klass         => klass,
+          }
+          @call_stack.push actual_information
+          
+          changed
+          notify_observers :call, self
+          
+        when 'return', 'c-return'
+          # args describe the startingpoint of return,
+          # should be equal to last stack-element
+          
+          changed
+          notify_observers :return, self
+          
+          @call_stack.pop
+
+        end
+      rescue Exception => exception
+        puts exception
+        puts exception.backtrace
+      end
+
+    end
+
+  end # class Backtracer
+end # module UML

data/lib/uml/method_helper.rb

@@ -0,0 +1,138 @@
+module UML
+
+  # Contains helper methods to work with receivers and methods.
+  # 
+  # These methods would better match in class Method, if it had access to its receiver.
+  # (Waiting for Ruby v1.9)
+  module MethodHelper
+
+    # :section: Receiver
+    
+    # Find out, if +receiver+ is an instance of some class.
+    # 
+    # :call-seq:
+    #   is_receiver_instance_of_class?(receiver) -> true or false
+    #
+    def is_receiver_instance_of_class?(receiver)
+      not(is_receiver_class?(receiver) or is_receiver_module?(receiver))
+    end
+    
+    # Find out, if +receiver is a Class
+    # 
+    # :call-seq:
+    #   is_receiver_class?(receiver) -> true or false
+    #
+    def is_receiver_class?(receiver)
+      receiver.instance_of? Class
+    end
+    
+    # Find out, if +receiver is a Module
+    # 
+    # :call-seq:
+    #   is_receiver_module?(receiver) -> true | false
+    #
+    def is_receiver_module?(receiver)
+      receiver.instance_of? Module
+    end
+    
+    # Find real receiver of method.
+    # 
+    # Searches included and extended Modules and Superclasses.
+    # 
+    # :call-seq:
+    #   get_real_receiver_of_method(top_receiver, method_symbol) -> class | module | nil
+    # 
+    def get_real_receiver_of_method(*args)
+      klass, message = prepare_args(*args)
+
+      # As Module::instance_methods just returns public instance methods, all three
+      # visibilities have to be tested
+      
+      # test all included modules in topmost class
+      klass.included_modules.each do |mod|
+        return mod if mod.singleton_methods(false).include? message or 
+                      mod.public_instance_methods(false).include? message or
+                      mod.protected_instance_methods(false).include? message or
+                      mod.private_instance_methods(false).include? message
+      end
+      
+      # also check extended modules
+      class << klass; included_modules; end.each do |mod|
+        return mod if mod.singleton_methods(false).include? message or 
+                      mod.public_instance_methods(false).include? message or
+                      mod.protected_instance_methods(false).include? message or
+                      mod.private_instance_methods(false).include? message
+      end
+      
+      # then check class and superclasses
+      while klass
+        return klass if klass.singleton_methods(false).include? message or
+                        klass.public_instance_methods(false).include? message or
+                        klass.protected_instance_methods(false).include? message or
+                        klass.private_instance_methods(false).include? message
+                         
+        klass = klass.respond_to?(:superclass) ? klass.superclass : nil
+      end
+      nil
+    end
+
+    # :section: Method
+
+    # Find out if method is singleton
+    # 
+    # :call-seq:
+    #   is_method_singleton?(top_receiver, method_symbol) -> true | false
+    #
+    def is_method_singleton?(*args)
+      klass, message = prepare_args(*args)
+      klass.singleton_methods.include? message
+    end
+    
+    # Get visibility of an instance method
+    # 
+    # :call-seq:
+    #   get_visibility_of_instance_method(top_receiver, method_symbol) -> :public | :protected | :private
+    #
+    def get_visibility_of_instance_method(*args)
+      klass, message = prepare_args(*args)
+      case
+      when klass.public_instance_methods.include?(message) : :public
+      when klass.protected_instance_methods.include?(message) : :protected
+      when klass.private_instance_methods.include?(message) : :private
+      else nil
+      end
+    end
+
+    # Get visibility of a singleton method
+    # 
+    # :call-seq:
+    #   get_visibility_of_singleton_method(top_receiver, method_symbol) -> :public | :protected | :private
+    #
+    def get_visibility_of_singleton_method(*args)
+      klass, message = prepare_args(*args)
+      case
+      when klass.public_methods.include?(message) : :public
+      when klass.protected_methods.include?(message) : :protected
+      when klass.private_methods.include?(message) : :private
+      else nil
+      end
+    end
+    
+    # Get visibility of a method.
+    # 
+    # :call-seq:
+    #   get_visibility_of_method(top_receiver, method_symbol) -> :public | :protected | :private
+    #
+    def get_visibility_of_method(*args)
+      is_method_singleton?(*args)? get_visibility_of_singleton_method(*args) : get_visibility_of_instance_method(*args)
+    end
+
+  private
+  
+    def prepare_args(klass, method_symbol)
+      return [is_receiver_instance_of_class?(klass) ? klass.class : klass, method_symbol.to_s]
+    end
+
+    
+  end
+end

data/lib/uml/sequence_diagram.rb

@@ -0,0 +1,157 @@
+require 'uml/highlevel_backtracer'
+require 'uml/sequence_diagram_helper'
+
+module UML
+
+  # Generates pic representation of program execution.
+  class SequenceDiagram
+    include SequenceDiagramHelper
+    
+    # Options:
+    # basename:: You can give the actor a name. Default is 'Actor'.
+    # multiple_activation:: If +true+, and an activated object calls method with receiver +self+,
+    #                       object can be activated multiple times. Default is +false+.
+    # object_sequence:: You can sort the sequence of objects in output, if you give their names here.
+    # 
+    #                   Every object not included, will be printed after given ones in random order.
+    #                   
+    #                   Defaults to <tt>['Actor']</tt>, which ensures that 'Actor' is always the leftmost object.
+    # pic_variables:: Hash with variables for sequence.pic. See UMLGraph's documentation
+    #                 for valid variables. Default +{}+.
+    # sequence_pic:: give the position and name of UMLGraph's sequence.pic file.
+    # 
+    #                Default is 'sequence.pic', which means that the file has to
+    #                be in the directory where pic2plot is called.
+    # split_inherited:: If +true+ included modules and superclasses are printed as discrete objects.
+    # 
+    #                   Default is +false+.
+    # use_create_message:: If method initialize is caught, a create_message is built
+    #                      instead of a normal call. Have in mind, that initialize is
+    #                      not allways used as constructor.
+    #                      
+    #                      Default is +false+.
+    # parameter_callback:: To get a pretty print of method args and returnvalues,
+    #                      you can give a proc here, that gets called for each argument
+    #                      or returnvalue.
+    #                      
+    #                      Default is <tt>lambda { |p| p.to_s }</tt>, but have a look
+    #                      at method callback in examples/sequence_diagram_generator.rb for a
+    #                      more sophisticated and recursive example.
+    def initialize(config = nil)
+      @config = {
+        :basename            => 'Actor',
+        :split_inherited     => false,
+        :use_create_message  => false,
+        :multiple_activation => false,
+        :sequence_pic        => 'sequence.pic',
+        :pic_variables       => {},
+        :object_sequence     => ['Actor'],
+        :parameter_callback  => lambda { |p| p.to_s }
+      }
+      @config.update(config) if config
+      
+      @object_definitions = {}
+      @object_definitions[@config[:basename]] = ObjectDefinition.new(@config[:basename], :actor)
+      @messages = ''
+      
+      @tracer = HighlevelBacktracer.new
+      @tracer.add_observer self
+    end
+
+    # Include methods of class or instance.
+    # 
+    # The parameters are handed on to <tt>AspectR::wrap</tt>, so refer to the according
+    # documentation for how you can e.g. use Regexp.
+    # 
+    # :call-seq: include(klass, *methods)
+    # 
+    def include(*args)
+      @tracer.include(*args)
+    end
+    
+    def to_pic
+      result = ''
+      result << ".PS\n"
+      result << "copy \"#{@config[:sequence_pic]}\";\n"
+      result << pic_variable_definitions(@config[:pic_variables])
+      result << pic_object_definitions(object_definitions)
+      result << pic_message_exchange(@messages)
+      result << pic_object_completions(@object_definitions.values)
+      result << '.PE'
+      result
+    end
+
+    def update(event, tracer) # :nodoc: #
+      begin
+        right = tracer.call_stack[-1]
+        left = tracer.call_stack[-2]
+        
+        used_object = @config[:split_inherited] ? :real_object : :object
+        right_label = right[used_object].name
+        left_label  = (left) ? left[used_object].name : @config[:basename]
+        
+        case event
+        when :call
+  
+          if @config[:use_create_message] and right[:method_symbol] == :initialize
+            @object_definitions[right_label] ||= ObjectDefinition.new(right_label,
+              :placeholder_object
+            )
+            @messages << pic_create_message(@object_definitions[left_label],
+              @object_definitions[right_label]
+            )
+          else
+            @object_definitions[right_label] ||= ObjectDefinition.new(right_label)
+            @messages << pic_message(@object_definitions[left_label],
+              @object_definitions[right_label],
+              right[:method_symbol],
+              right[:args].collect(&@config[:parameter_callback]).join(',')
+            )
+          end
+          
+        when :return
+          @messages << pic_return_message(@object_definitions[left_label],
+            @object_definitions[right_label],
+            @config[:parameter_callback].call(right[:returns])
+          )
+        end
+      rescue Exception => e
+        puts e
+        puts e.backtrace
+        exit 1
+      end
+    end
+        
+private
+
+    def object_definitions
+      result = []
+      labels = @config[:object_sequence] + (@object_definitions.keys - @config[:object_sequence])
+      labels.each do |label|
+        result << @object_definitions[label] if @object_definitions[label]
+      end
+      result
+    end
+    
+  end
+end
+
+class UML::SequenceDiagram::ObjectDefinition # :nodoc:
+
+  attr_reader   :type, :label
+  attr_accessor :active
+  
+  def initialize(label, type = :object)
+    @label = label
+    @type = type
+    @active = 0
+  end
+  
+  # does nothing more, than ensure that label can be used as name for pic
+  def name
+    @label.gsub(/::/, '_')
+  end
+  
+  alias to_s name
+  
+end

data/lib/uml/sequence_diagram_helper.rb

@@ -0,0 +1,100 @@
+module UML
+  module SequenceDiagramHelper
+  
+    def pic_object_definitions(definitions)
+      result = "\n# Object definition\n"
+      definitions.each do |definition|
+        result << pic_object_definition(definition)
+      end
+      result << pic_step
+    end
+    
+    def pic_message_exchange(string)
+      result = "\n# Message exchange\n"
+      result << string
+      result << pic_step
+    end
+    
+    def pic_object_completions(definitions)
+      result = "\n# Object lifeline completion\n"
+      definitions.each do |definition|
+        result << pic_complete(definition)
+      end
+      result
+    end
+    
+    def pic_object_definition(definition)
+      case definition.type
+      when :placeholder_object
+        pic_placeholder_object(definition)
+      when :actor
+        pic_actor(definition)
+      else
+        pic_object(definition)
+      end
+    end
+    
+    def pic_actor(definition)
+      "actor(#{definition},\"#{definition.label}\");\n"
+    end
+    
+    def pic_complete(definition)
+      "complete(#{definition});\n"
+    end
+    
+    def pic_object(definition)
+      "object(#{definition},\"#{definition.label}\");\n"
+    end
+  
+    def pic_placeholder_object(definition)
+      "placeholder_object(#{definition});\n"
+    end
+    
+    def pic_step
+      "step();\n"
+    end
+    
+    def pic_variable(variable, value)
+      "#{variable} = #{value};\n"
+    end
+    
+    # hash format :variable, value
+    def pic_variable_definitions(hash)
+      result = "\n# Variable definitions\n"
+      hash.each do |variable, value|
+        result << pic_variable(variable, value)
+      end
+      result
+    end
+    
+    def pic_active(definition)
+      definition.active += 1
+      (@config[:multiple_activation] or definition.active == 1) ? "active(#{definition});\n" : ''
+    end
+    
+    def pic_inactive(definition)
+      definition.active -= 1
+      (@config[:multiple_activation] or definition.active == 0) ? "inactive(#{definition});\n" : ''
+    end
+    
+    def pic_message(from, to, message, value)
+      result = "message(#{from},#{to},\"#{message}(#{value})\");\n"
+      result << pic_active(to)
+    end
+    
+    def pic_return_message(left, right, value)
+      result = "return_message(#{right},#{left},\"#{value}\");\n"
+      result << pic_inactive(right)
+    end
+    
+    def pic_create_message(from, to)
+      result = "create_message(#{from},#{to},\"#{to.label}\");\n"
+      result << pic_active(to)
+    end
+    
+#    def escape(string)
+#      string.gsub(/(["])/, '\\\\\1')
+#    end
+    
+  end
+end