metaruby 1.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 58ab70780a173a248a3f2a14a86d9b210e740f14
+  data.tar.gz: 178e85ee93eb3727f53afc7d8b0c1505cd01fa0d
+SHA512:
+  metadata.gz: e320d1c8f9b52c88d7f3d24939210ebce53777711cc3909a48a7d7512e7e1724adf8bfde091e80695137d598aa23bd82c0232bb7c7e2538918bda3a721c23487
+  data.tar.gz: 28eb0b645abbaa873e93f5fb138e2df333d913e9adb791f8229a4edc0edce87630f54db2f36dc8a4a1454b178b1bab00559a42acbd68dceb374ba205dcb32884

data/History.txt

@@ -0,0 +1 @@
+===

data/Manifest.txt

@@ -0,0 +1,40 @@
+History.txt
+Manifest.txt
+README.md
+Rakefile
+lib/metaruby.rb
+lib/metaruby/class.rb
+lib/metaruby/dsls.rb
+lib/metaruby/dsls/doc.rb
+lib/metaruby/dsls/find_through_method_missing.rb
+lib/metaruby/gui.rb
+lib/metaruby/gui/exception_view.rb
+lib/metaruby/gui/html.rb
+lib/metaruby/gui/html/button.rb
+lib/metaruby/gui/html/collection.rb
+lib/metaruby/gui/html/exception_view.css
+lib/metaruby/gui/html/jquery.min.js
+lib/metaruby/gui/html/jquery.selectfilter.js
+lib/metaruby/gui/html/jquery.tagcloud.min.js
+lib/metaruby/gui/html/jquery.tinysort.min.js
+lib/metaruby/gui/html/list.rhtml
+lib/metaruby/gui/html/page.css
+lib/metaruby/gui/html/page.rb
+lib/metaruby/gui/html/page.rhtml
+lib/metaruby/gui/html/page_body.rhtml
+lib/metaruby/gui/html/rock-website.css
+lib/metaruby/gui/model_browser.rb
+lib/metaruby/gui/model_selector.rb
+lib/metaruby/gui/rendering_manager.rb
+lib/metaruby/gui/ruby_constants_item_model.rb
+lib/metaruby/inherited_attribute.rb
+lib/metaruby/module.rb
+lib/metaruby/registration.rb
+lib/metaruby/test.rb
+manifest.xml
+test/suite.rb
+test/test_attributes.rb
+test/test_class.rb
+test/test_dsls.rb
+test/test_module.rb
+test/test_registration.rb

data/README.md

@@ -0,0 +1,318 @@
+# Metamodelling in the Ruby type system
+
+* https://gitorious.org/rock-toolchain/metaruby
+
+MetaRuby is a library that allows to (ab)use the Ruby type system to create
+reflexive programs: create a specialized modelling API (a.k.a. "a DSL") at the
+class/module level and then get access to this model information from the
+objects.
+
+This page will describe the various functionality that metaruby provides to help
+modelling in Ruby.
+
+This page will reuse one of the most overused example of modelling: a car and
+colors.
+
+## Models
+
+Using MetaRuby, models can either be represented by Ruby classes or by Ruby
+modules. You use the first one when you want to model something from which an
+object can be created, in our example: a car. You use the second for things that
+cannot be instanciated, but can be used as attributes of another object, in our
+example: a color.
+
+Another point of terminology: _metamodel_. The metamodel is the
+model-of-the-model, i.e. it is the bits and pieces that allow to describe a
+model (the model itself describing an object). As you will see, metamodels in
+MetaRuby are all described in modules.
+
+## Models as classes
+
+The metamodel of models that are represented by classes must include
+{MetaRuby::ModelAsClass} and are then used to extend said class
+
+~~~
+module Models
+  module Car
+    include MetaRuby::ModelAsClass
+  end
+end
+class Car
+  extend Models::Car
+end
+~~~
+
+Then, creating a new Car model is done by subclassing the Car class:
+
+~~~
+class Peugeot < Car
+  # Call methods from the modelling DSL defined by Models::Car
+end
+~~~
+
+This creates a _named model_, i.e. a model that can be accessed by name. Another
+way is to create an anonymous model by calling {MetaRuby::ModelAsClass#new_submodel new_submodel}:
+
+~~~
+model = Car.new_submodel do
+  # Call methods from the modelling DSL defined by Models::Car
+end
+~~~
+
+Note that this mechanism naturally extends to submodels-of-submodels, e.g.
+
+~~~
+class P806 < Peugeot
+  # Call methods from the modelling DSL defined by Models::Car
+end
+~~~
+
+## Models as modules
+
+The metamodel of models that are represented by modules must include
+{MetaRuby::ModelAsModule} and are then used to extend said module
+
+~~~
+module Models
+  module Color
+    include MetaRuby::ModelAsModule
+  end
+end
+module Color
+  extend Models::Color
+end
+~~~
+
+Then, creating a new Color model is done by calling {MetaRuby::ModelAsModule#new_submodel new_submodel} on Color
+
+~~~
+red = Color.new_submodel
+~~~
+
+A common pattern is to define a method on the Module class, that creates new
+models and assigns them to constants. MetaRuby provides a helper method for this
+purpose, that we strongly recommend you use:
+
+~~~
+class Module
+  def color(name, &block)
+    MetaRuby::ModelAsModule.create_ang_register_submodel(self, name, Color, &block)
+  end
+end
+~~~
+
+Which can then be used with:
+
+~~~
+module MyNamespace
+  color 'Red' do
+    # Call methods from the color modelling DSL defined by Models::Color
+  end
+end
+~~~
+
+The new Red color model can then be accessed with MyNamespace::Red
+
+A model hierarchy can be built by telling MetaRuby that a given model _provides_
+another one, for instance:
+
+~~~
+color 'Yellow' do
+  provides Red
+  provides Green
+end
+~~~
+
+And, finally, a class-based model can provide a module-based one:
+   
+~~~
+class Peugeot < Car
+  # All peugeots are yellow
+  provides Yellow
+end
+~~~
+
+# Attributes
+
+One important part of the whole modelling is to list _attributes_ of the things
+that are getting modelled. The important bit being the definition of what should
+happen when creating a new submodel for an existing model. Even though we will
+use the class-as-model representation in all the following examples, the exact
+same mechanisms are available in the model-as-module. The only difference is
+that a class-as-model is a submodel of all its parent classes while a
+class-as-module is a submodel of all the other modules it provides.
+
+# Zero-or-one attributes
+
+These are attributes that hold at most one value (and possibly none). The
+typical example is the predicate (boolean attribute)
+
+~~~
+module Models::Car
+  include MetaRuby::ModelAsClass
+ 
+  # Attribute inherited along the hierarchy of models
+  inherited_single_value_attribute("number_of_doors")
+end
+~~~
+~~~
+class SportsCar < Car
+  # Make the default number of doors of all sports car 2
+  number_of_doors 2
+end
+class ASportsCar < SportsCar
+  # Actually, this one has a trunk
+  number_of_doors 3
+end
+class AnotherSportsCar < SportsCar
+end
+~~~
+~~~
+Car.number_of_doors => nil
+SportsCar.number_of_doors => 2
+ASportsCar.number_of_doors => 3
+AnotherSportsCar.number_of_doors => 2 # Inherited from SportsCar
+~~~
+
+## Set attributes
+These are attributes that hold a set of values. When taking into account the
+hierarchy of models, the set for a model X is the union of all the sets of X and
+all its parents:
+
+~~~
+module Models::Car
+  include MetaRuby::ModelAsClass
+  # Attribute inherited along the hierarchy of models
+  inherited_attribute("material", "materials")
+end
+~~~
+~~~
+class Car
+  extend Models::Car
+  materials << 'iron' # all cars contain iron
+end
+class Peugeot < Car
+  materials << 'plastic' # additionally, all peugeot cars contain plastic
+end
+~~~
+~~~
+Car.each_material.to_a => ['iron']
+Peugeot.each_material.to_a => ['iron', 'plastic']
+Car.all_materials => ['iron']
+Peugeot.all_materials => ['iron', 'plastic']
+Car.self_materials => ['iron']
+Peugeot.self_materials => ['plastic']
+~~~
+
+## Named attributes
+In certain situations, elements of the sets that we represented in the previous
+section can actually have names (where the names are actually part of the
+modelling). 
+
+~~~
+module Models::Car
+  include MetaRuby::ModelAsClass
+  # Attribute inherited along the hierarchy of models
+  inherited_attribute("door_color", "door_colors")
+  def number_of_doors
+    all_door_colors.to_a.size
+  end
+end
+~~~
+
+~~~
+class Car
+  extend Models::Car
+  door_colors['driver'] = Color # There is a driver door, but we don't know
+                                # the color
+  door_colors['other'] = Color # There is another door, but we don't know
+                                # the color
+end
+class Peugeot < Car
+  # All peugeot have a red driver door and a green trunk door
+  door_colors['driver'] = Red
+  door_colors['trunk'] = Green
+end
+~~~
+
+~~~
+Car.self_door_colors => {'driver' => Color, 'other' => Color }
+Car.all_door_colors => {'driver' => Color, 'other' => Color }
+Peugeot.self_door_colors => {'driver' => Red, 'trunk' => Green }
+Peugeot.self_door_colors => {'driver' => Red, 'other' => Color, 'trunk' => Green }
+~~~
+
+## Value promotion
+In some cases, one need to modify the values inherited from the parent models
+before they can become proper attributes of the child model, commonly because
+the objects stored in the attributes refer to the model they are part of. For
+instance, let's assume we have a Door object defined thus:
+
+~~~
+Door = Struct :car_model, :color
+~~~
+
+and
+
+~~~
+Car.doors['driver'] = Door.new(Car, Color)
+Car.doors['other'] = Door.new(Car, Color)
+~~~
+
+Now,
+
+~~~
+Peugeot.find_door('driver').car_model => Car
+~~~
+
+In most cases, we would like to have this last value be Peugeot. This can be
+done by defining a promotion method on the metamodel _before_ the inherited
+attribute is defined:
+
+~~~
+module Models::Car
+  # Called to promote a door model from its immediate supermodel to this
+  # model
+  def promote_door(door_name, door)
+    # You have to create a new door object !
+    door = door.dup
+    door.car_model = self
+    door
+  end
+
+  # Define the attribute *after* the promotion method
+  inherited_attribute("door", "doors")
+end
+~~~
+
+# Model Registration
+The last bit that MetaRuby takes care of is to register all models that have
+been defined, allowing to browse them by type. For instance, all models based on
+the Car model can be enumerated with:
+
+~~~
+Car.each_submodel
+~~~
+
+Because this mechanism keeps a reference on all model objects, it is necessary
+to clear the registered submodels dealing with e.g. tests that create submodels
+on the fly. This is done by calling {MetaRuby::Registration#clear_submodels
+clear_submodels} in the tests teardown:
+
+~~~
+Car.clear_submodels
+~~~
+
+This will only clear anonymous models. Models that are created either by
+subclassing a model class or by using
+{MetaRuby::ModelAsModule#create_ang_register_submodel
+create_ang_register_submodel} are marked as
+{MetaRuby::Registration#permanent_model? permanent models} and therefore
+protected from removal by #clear_submodel
+
+# Adding options to the submodel creation process
+
+If you need to customize the submodel creation process, for instance by
+providing options to the subprocess, do so by overloading #setup_submodel. Do
+NOT overload #new_submodel unless you really know what you are doing, and pass
+the options as an option hash

data/Rakefile

@@ -0,0 +1,39 @@
+task 'default'
+require 'metaruby/version'
+
+require 'utilrb/doc/rake'
+Utilrb.doc :include => ['lib/**/*.rb']
+
+begin
+    require 'hoe'
+    Hoe::plugin :yard
+
+    config = Hoe.spec 'metaruby' do
+        self.version = MetaRuby::VERSION
+        self.developer "Sylvain Joyeux", "sylvain.joyeux@m4x.org"
+        self.summary = 'Modelling using the Ruby language as a metamodel'
+        self.description = paragraphs_of('README.md', 3..6).join("\n\n")
+        self.changes     = paragraphs_of('History.txt', 0..1).join("\n\n")
+        self.readme_file = 'README.md'
+        self.history_file = 'History.txt'
+        self.license 'LGPLv3+'
+
+        extra_deps <<
+            ['utilrb',   '>= 1.3.4']
+        extra_dev_deps <<
+            ['rake',     '>= 0.8'] <<
+            ['hoe-yard', '>= 0.1.2']
+    end
+
+    Rake.clear_tasks(/^default$/)
+    task :default => []
+    task :doc => :yard
+rescue LoadError
+    STDERR.puts "cannot load the Hoe gem. Distribution is disabled"
+rescue Exception => e
+    puts e.backtrace
+    if e.message !~ /\.rubyforge/
+        STDERR.puts "WARN: cannot load the Hoe gem, or Hoe fails. Publishing tasks are disabled"
+        STDERR.puts "WARN: error message is: #{e.message}"
+    end
+end

data/lib/metaruby/class.rb

@@ -0,0 +1,120 @@
+module MetaRuby
+    # Extend in classes that are used to represent models
+    #
+    # @example
+    #   class MyBaseClass
+    #     extend MetaRuby::ModelAsClass
+    #   end
+    #
+    # Alternatively, you can create a module that describes the metamodel and
+    # extend the base model class with it
+    #
+    # @example
+    #   module MyBaseMetamodel
+    #     include MetaRuby::ModelAsModule
+    #   end
+    #   class MyBaseModel
+    #     extend MyBaseMetamodel
+    #   end
+    #
+    module ModelAsClass
+        include Attributes
+        include Registration
+        extend Attributes
+
+        # The call stack at the point of definition of this model
+        attr_accessor :definition_location
+
+        # @return [String] set or get the documentation text for this model
+        inherited_single_value_attribute :doc
+
+        # Sets a name on this model
+        #
+        # Only use this on 'anonymous models', i.e. on models that are not
+        # meant to be assigned on a Ruby constant
+        #
+        # @return [String] the assigned name
+        def name=(name)
+            def self.name
+                if @name then @name
+                else super
+                end
+            end
+            @name = name
+        end
+
+        # The model next in the ancestry chain, or nil if +self+ is root
+        #
+        # @return [Class]
+        def supermodel
+            if superclass.respond_to?(:supermodel)
+                return superclass
+            end
+        end
+        
+        # This flag is used to notify {#inherited} that it is being called from
+        # new_submodel, in which case it should not 
+        #
+        # This mechanism works as:
+        #   - inherited(subclass) is called right away after class.new is called
+        #     (so, we don't have to take recursive calls into account)
+        #   - it is a TLS, so thread safe
+        #
+        FROM_NEW_SUBMODEL_TLS = :metaruby_class_new_called_from_new_submodel
+
+        # Creates a new submodel of +self+
+        #
+        # @option options [String] name forcefully set a name on the new
+        #   model. Use this only for models that are not meant to be
+        #   assigned on a Ruby constant
+        #
+        # @return [Module] a subclass of self
+        def new_submodel(options = Hash.new, &block)
+            options, submodel_options = Kernel.filter_options options,
+                :name => nil
+
+            Thread.current[FROM_NEW_SUBMODEL_TLS] = true
+            model = self.class.new(self)
+            model.permanent_model = false
+            if options[:name]
+                model.name = options[:name]
+            end
+            setup_submodel(model, submodel_options, &block)
+            model
+        end
+
+        # Called to apply a DSL block on this model
+        def apply_block(&block)
+            class_eval(&block)
+        end
+
+        # Called at the end of the definition of a new submodel
+        def setup_submodel(submodel, options = Hash.new, &block)
+            register_submodel(submodel)
+
+            if block_given?
+                submodel.apply_block(&block)
+            end
+        end
+
+        # Registers submodels when a subclass is created
+        def inherited(subclass)
+            from_new_submodel = Thread.current[FROM_NEW_SUBMODEL_TLS]
+            Thread.current[FROM_NEW_SUBMODEL_TLS] = false
+
+            subclass.definition_location = call_stack
+            super
+            subclass.permanent_model = subclass.accessible_by_name? &&
+                subclass.permanent_definition_context?
+            if !from_new_submodel
+                setup_submodel(subclass)
+            end
+        end
+
+        # Call to declare that this model provides the given model-as-module
+        def provides(model_as_module)
+            include model_as_module
+        end
+    end
+end
+

data/lib/metaruby/dsls/doc.rb

@@ -0,0 +1,78 @@
+require 'facets/kernel/call_stack'
+module MetaRuby
+    module DSLs
+        # Looks for the documentation block for the element that is being built.
+        #
+        # @param [#===] file_match an object (typically a regular expression)
+        #   that matches the file name in which the DSL is being used
+        # @param [#===] trigger_method an object (typically a regular expression)
+        #   that matches the name of the method that initiates the creation of
+        #   the element whose documentation we are looking for.
+        # @return [String,nil] the parsed documentation, or nil if there is no
+        #   documentation
+        def self.parse_documentation_block(file_match, trigger_method = /.*/)
+            last_method_matched = false
+            call_stack.each do |call|
+                this_method_matched =
+                    if trigger_method === call[2].to_s
+                        true
+                    elsif call[2] == :method_missing
+                        last_method_matched
+                    else
+                        false
+                    end
+
+                if !this_method_matched && last_method_matched && (file_match === call[0])
+                    if File.file?(call[0])
+                        return parse_documentation_block_at(call[0], call[1])
+                    else return
+                    end
+                end
+                last_method_matched = this_method_matched
+            end
+            nil
+        end
+
+        # Parses upwards a Ruby documentation block whose last line starts at or
+        # just before the given line in the given file
+        #
+        # @param [String] file
+        # @param [Integer] line
+        # @return [String,nil] the parsed documentation, or nil if there is no
+        #   documentation
+        def self.parse_documentation_block_at(file, line)
+            lines = File.readlines(file)
+
+            block = []
+            # Lines are given 1-based (as all editors work that way), and we
+            # want the line before the definition. Remove two
+            line = line - 2
+            while true
+                case l = lines[line]
+                when /^\s*$/
+                    break
+                when /^\s*#/
+                    block << l
+                else break
+                end
+                line = line - 1
+            end
+            block = block.map do |l|
+                l.strip.gsub(/^\s*#/, '')
+            end
+            # Now remove the same amount of spaces in front of each lines
+            space_count = block.map do |l|
+                l =~ /^(\s*)/
+                if $1.size != l.size
+                    $1.size
+                end
+            end.compact.min
+            block = block.map do |l|
+                l[space_count..-1]
+            end
+            if !block.empty?
+                block.reverse.join("\n")
+            end
+        end
+    end
+end

data/lib/metaruby/dsls/find_through_method_missing.rb

@@ -0,0 +1,76 @@
+module MetaRuby
+    module DSLs
+        # Generic implementation to create suffixed accessors for child objects
+        # on a class
+        #
+        # Given an object category (let's say 'state'), this allows to properly
+        # implement a method-missing based accessor of the style
+        #
+        #     blabla_state
+        #
+        # using a find_state method that the object should respond to
+        #
+        # @param [Object] object the object on which the find method is going to
+        #   be called
+        # @param [Symbol] m the method name
+        # @param [Array] args the method arguments
+        # @param [Array<String>] suffixes the accessor suffixes that should be
+        #   resolved. The last argument can be a hash, in which case the keys
+        #   are used as suffixes and the values are the name of the find methods
+        #   that should be used.
+        # @return [Object,nil] an object if one of the listed suffixes matches
+        #   the method name, or nil if the method name does not match the
+        #   requested pattern.
+        #
+        # @raise [NoMethodError] if the requested object does not exist (i.e. if
+        #   the find method returns nil)
+        # @raise [ArgumentError] if the method name matches one of the suffixes,
+        #   but arguments were given. It is raised regardless of the existence
+        #   of the requested object
+        #
+        # @example
+        #   class MyClass
+        #     def find_state(name)
+        #       states[name]
+        #     end
+        #     def find_transition(name)
+        #       transitions[name]
+        #     end
+        #     def method_missing(m, *args, &block)
+        #       MetaRuby::DSLs.find_through_method_missing(self, m, args,
+        #         'state', 'transition') || super
+        #     end
+        #   end
+        #   object = MyClass.new
+        #   object.add_state 'my'
+        #   object.my_state # will resolve the 'my' state
+        #
+        def self.find_through_method_missing(object, m, args, *suffixes)
+            suffix_match = Hash.new
+            if suffixes.last.kind_of?(Hash)
+                suffix_match.merge!(suffixes.pop)
+            end
+            suffixes.each do |name|
+                suffix_match[name] = "find_#{name}"
+            end
+
+            m = m.to_s
+            suffix_match.each do |s, find_method_name|
+                if m == find_method_name
+                    raise NoMethodError.new("#{object} has no method called #{find_method_name}", m)
+                elsif m =~ /(.*)_#{s}$/
+                    name = $1
+                    if !args.empty?
+                        raise ArgumentError, "expected zero arguments to #{m}, got #{args.size}", caller(4)
+                    elsif found = object.send(find_method_name, name)
+                        return found
+                    else
+                        msg = "#{object} has no #{s} named #{name}"
+                        raise NoMethodError.new(msg, m), msg, caller(4)
+                    end
+                end
+            end
+            nil
+        end
+    end
+end

data/lib/metaruby/dsls.rb

@@ -0,0 +1,2 @@
+require 'metaruby/dsls/doc'
+require 'metaruby/dsls/find_through_method_missing'