metaruby 1.0.0.rc2 → 1.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: edefd7e59dcbf75b2cd69877ae482a9cb6838b96
-  data.tar.gz: 4d1263ce781eec239a82dbf30c470e95b9e5030d
+  metadata.gz: 0f6d60aa23a3e9e790ac1613c65fc2a0b446f0de
+  data.tar.gz: e22d9104e853727888c91504b5d25dbf29234e9a
 SHA512:
-  metadata.gz: 2e687ba3e7144b5f21f6ce767ed38364b9baf863ca8bc0b03ee353fbc159265f79569e1f8c7819365f78443e4a2650b40bdb96ae2e2d6653e2b23c6e5bf0643e
-  data.tar.gz: 7da81dcac85b7e7546734d5eafebe64fa280d59fa5eb579d1ee15b71b2282db7c7aeb09d6c53fa0d018dd2b0368b79a061a30d449b77ada89b9f5ed7ff4e0e95
+  metadata.gz: e59cba378c250b744c75cd654c426cbbd801812df83e45a07fe2ba22ef15a903490d61d039ea67cdfc275e2dbf629739f1507f30ef16aacd79b52f8948be0c3f
+  data.tar.gz: 58bee189d56019dab2103b3944d3ec24001e044ce16dd76ca3101f9ff097652c44dbdabc6862affeed7f1a522fd7b839c54da0a016236c57447adb1591126de5

data/.gitignore

@@ -1,3 +1,4 @@
 .yardoc
 coverage/
 doc/
+.*.sw?

data/.travis.yml

@@ -1,5 +1,9 @@
+sudo: false
 language: ruby
 rvm:
   - 2.0.0
   - 2.1.6
   - 2.2.2
+script:
+    - bundle exec rake
+    - bundle exec rake test

data/README.md

@@ -96,7 +96,7 @@ purpose, that we strongly recommend you use:
 ~~~
 class Module
   def color(name, &block)
-    MetaRuby::ModelAsModule.create_ang_register_submodel(self, name, Color, &block)
+    MetaRuby::ModelAsModule.create_and_register_submodel(self, name, Color, &block)
   end
 end
 ~~~
@@ -305,9 +305,9 @@ 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
+{MetaRuby::ModelAsModule.create_and_register_submodel}
+are marked as
+{MetaRuby::Registration#permanent_model?} and therefore
 protected from removal by #clear_submodel
 
 # Adding options to the submodel creation process

data/lib/metaruby.rb

@@ -1,17 +1,24 @@
 require 'utilrb/object/attribute'
+require 'weakref'
 
 require 'metaruby/inherited_attribute'
 require 'metaruby/registration'
 require 'metaruby/module'
 require 'metaruby/class'
 
+require 'utilrb/logger'
+
 # The toplevel namespace for MetaRuby
 #
 # MetaRuby is an implementation of a (very small) modelling toolkit that uses
 # the Ruby type system as its meta-metamodel
-require 'utilrb/logger'
 module MetaRuby
+    # Path to the metaruby.rb file (i.e. the root of the MetaRuby library)
+    #
+    # This is used to find ressources (css, javascript) that is bundled in the
+    # metaruby repository
     LIB_DIR = File.expand_path('metaruby', File.dirname(__FILE__))
+
     extend Logger::Root('MetaRuby', Logger::WARN)
 end
 

data/lib/metaruby/class.rb

@@ -28,6 +28,8 @@ module MetaRuby
         # @return [String] set or get the documentation text for this model
         inherited_single_value_attribute :doc
 
+        # @!attribute [rw] name
+        #
         # Sets a name on this model
         #
         # Only use this on 'anonymous models', i.e. on models that are not
@@ -35,6 +37,9 @@ module MetaRuby
         #
         # @return [String] the assigned name
         def name=(name)
+            # This is dynamically defined. The reason is that there is no way to
+            # call 'super' to get the default Class#name, so we define our name
+            # only when it is explicitely assigned
             def self.name
                 if @name then @name
                 else super
@@ -69,17 +74,14 @@ module MetaRuby
         #   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
-
+        def new_submodel(name: nil, **submodel_options, &block)
             Thread.current[FROM_NEW_SUBMODEL_TLS] = true
             model = self.class.new(self)
             model.permanent_model = false
-            if options[:name]
-                model.name = options[:name]
+            if name
+                model.name = name
             end
-            setup_submodel(model, submodel_options, &block)
+            setup_submodel(model, **submodel_options, &block)
             model
         end
 
@@ -89,8 +91,10 @@ module MetaRuby
         end
 
         # Called at the end of the definition of a new submodel
-        def setup_submodel(submodel, options = Hash.new, &block)
-            register_submodel(submodel)
+        def setup_submodel(submodel, register: true, **options, &block)
+            if register
+                register_submodel(submodel)
+            end
 
             if block_given?
                 submodel.apply_block(&block)

data/lib/metaruby/dsls.rb

@@ -1,2 +1,8 @@
 require 'metaruby/dsls/doc'
 require 'metaruby/dsls/find_through_method_missing'
+
+module MetaRuby
+    # Helper functions to build DSLs
+    module DSLs
+    end
+end

data/lib/metaruby/gui.rb

@@ -1,9 +1,25 @@
 require 'Qt4'
 require 'qtwebkit'
 require 'kramdown'
+require 'pp'
 require 'metaruby/gui/html'
 require 'metaruby/gui/ruby_constants_item_model'
 require 'metaruby/gui/rendering_manager'
 require 'metaruby/gui/model_browser'
 require 'metaruby/gui/model_selector'
 require 'metaruby/gui/exception_view'
+
+module MetaRuby
+    # Set of widgets and classes that are used to view/browse MetaRuby-based models using Qt
+    #
+    # Model views are using HTML, the rendering of which is done through
+    # {GUI::HTML::Page}. The main functionality centers around
+    # {GUI::ModelBrowser} which allows to browse models in a hierarchy, and
+    # display them in a HTML::Page.
+    #
+    # {GUI::ExceptionRendering} allows to render exceptions into a HTML page as
+    # well, the formatting being delegated to the exception's #pretty_print
+    # method.
+    module GUI
+    end
+end

data/lib/metaruby/gui/exception_rendering.rb

@@ -0,0 +1,281 @@
+module MetaRuby
+    module GUI
+        # Functionality to render exceptions in an HTML view
+        #
+        # On top of properly formatting the exception, it introduces backtrace
+        # filtering and javascript-based buttons to enable backtraces on or off.
+        #
+        # It is usually not used directly, but through {HTML::Page}
+        #
+        # @see HTML::Page#enable_exception_rendering
+        # @see HTML::Page#push_exception
+        class ExceptionRendering
+            # The directory relative to which ressources (such as css or javascript
+            # files) are resolved by default
+            RESSOURCES_DIR = File.expand_path('html', File.dirname(__FILE__))
+
+            # @return [#link_to] an object that allows to render a link to an
+            #   object
+            attr_reader :linker
+
+            # @return [#[]] an object that can be used to determine whether a
+            #   file is a user or framework file. It is used in backtrace
+            #   filtering and rendering. The default returns true for any file.
+            attr_reader :user_file_filter
+
+            # Sets {#user_file_filter} or resets it to the default
+            #
+            # @param [nil,#[]] filter
+            def user_file_filter=(filter)
+                @user_file_filter = filter || Hash.new(true)
+            end
+
+            # Create an exception rendering object using the given linker object
+            #
+            # @param [#link_to] linker
+            def initialize(linker)
+                @linker = linker
+                self.user_file_filter = nil
+            end
+
+            # Necessary header content
+            HEADER = <<-EOD
+            <link rel="stylesheet" href="file://#{File.join(RESSOURCES_DIR, 'exception_view.css')}" type="text/css" />
+            <script type="text/javascript" src="file://#{File.join(RESSOURCES_DIR, 'jquery.min.js')}"></script>
+            EOD
+
+            # The scripts that are used by the other exception templates
+            SCRIPTS = <<-EOD
+            <script type="text/javascript">
+            $(document).ready(function () {
+                $(".backtrace").hide()
+                $("a.backtrace_toggle_filtered").click(function (event) {
+                        var eventId = $(this).attr("id");
+                        $("#backtrace_full_" + eventId).hide();
+                        $("#backtrace_filtered_" + eventId).toggle();
+                        event.preventDefault();
+                        });
+                $("a.backtrace_toggle_full").click(function (event) {
+                        var eventId = $(this).attr("id");
+                        $("#backtrace_full_" + eventId).toggle();
+                        $("#backtrace_filtered_" + eventId).hide();
+                        event.preventDefault();
+                        });
+            });
+            </script>
+            EOD
+
+            # Contents necessary in the <head> ... </head> section
+            #
+            # It is used when enabling the renderer on a [Page] by calling
+            # {HTML::Page#add_to_setup}
+            def head
+                HEADER
+            end
+
+            # Scripts block to be added to the HTML document
+            #
+            # It is used when enabling the renderer on a [Page] by calling
+            # {HTML::Page#add_to_setup}
+            def scripts
+                SCRIPTS
+            end
+
+            # Parse a backtrace into its file, line and method consistuents
+            #
+            # @return [Array<(String,Integer,String)>]
+            def self.parse_backtrace(backtrace)
+                BacktraceParser.new(backtrace).parse
+            end
+
+            # Shim class that parses a backtrace into its constituents
+            #
+            # This is an internal class, that should not be used directly. Use
+            # {ExceptionRendering.parse_backtrace} instead.
+            #
+            # It provides the methods required for facet's #call_stack method to
+            # work, thus allowing to use it to parse an arbitrary backtrace
+            class BacktraceParser
+                # Create a parser for the given backtrace
+                def initialize(backtrace)
+                    @backtrace = backtrace || []
+                end
+
+                # Parse the backtrace into file, line and method
+                #
+                # @return [Array<(String,Integer,String)>]
+                def parse
+                    call_stack(0)
+                end
+
+                # Returns the backtrace
+                #
+                # This is required by facet's #call_stack
+                def pp_callstack(level)
+                    @backtrace[level..-1]
+                end
+
+                # Returns the backtrace
+                #
+                # This is required by facet's #call_stack
+                def pp_call_stack(level)
+                    @backtrace[level..-1]
+                end
+            end
+
+            # Template used to render an exception that does not have backtrace
+            EXCEPTION_TEMPLATE_WITHOUT_BACKTRACE = <<-EOF
+            <div class="message" id="<%= id %>"><pre><%= message.join("\n") %></pre></div>
+            EOF
+
+            # Template used to render an exception that does have a backtrace
+            EXCEPTION_TEMPLATE_WITH_BACKTRACE = <<-EOF
+            <div class="message" id="<%= id %>">
+                <pre><%= message.join("\n") %></pre>
+                <span class="backtrace_links">
+                    (show: <a class="backtrace_toggle_filtered" id="<%= id %>">filtered backtrace</a>,
+                           <a class=\"backtrace_toggle_full\" id="<%= id %>">full backtrace</a>)
+                </span>
+            </div>
+            <div class="backtrace_summary">
+                from <%= origin_file %>:<%= origin_line %>:in <%= HTML.escape_html(origin_method.to_s) %>
+            </div>
+            <div class="backtrace" id="backtrace_filtered_<%= id %>">
+                <%= render_backtrace(filtered_backtrace) %>
+            </div>
+            <div class="backtrace" id="backtrace_full_<%= id %>">
+                <%= render_backtrace(full_backtrace) %>
+            </div>
+            EOF
+
+            # Filters the backtrace to remove framework parts that are not
+            # relevant
+            #
+            # @param [Array<(String,Integer,Symbol)>] parsed_backtrace the parsed backtrace
+            # @param [Array<(String,Integer,Symbol)>] raw_backtrace the raw backtrace
+            def filter_backtrace(parsed_backtrace, raw_backtrace)
+                head = parsed_backtrace.take_while { |file, _| !user_file?(file) }
+                tail = parsed_backtrace[head.size..-1].find_all { |file, _| user_file?(file) }
+                head + tail
+            end
+
+            # Return true if the given file is a user file or a framework file
+            #
+            # An object used to determine this can be set with
+            # {#user_file_filter=}
+            #
+            # This is used by {#render_backtrace} to choose the style of a
+            # backtrace line
+            def user_file?(file)
+                user_file_filter[file]
+            end
+
+            @@exception_id = 0
+
+            # Automatically generate an exception ID
+            def allocate_exception_id
+                @@exception_id += 1
+            end
+
+            # Render an exception into HTML
+            #
+            # @param [Exception] e the exception to be rendered
+            # @param [String] reason additional string that describes the
+            #   exception reason
+            # @param [String] id the ID that should be used to identify the
+            #   exception. Since a given exception can "contain" more than one
+            #   (see {#each_exception_from}), a -#counter pattern is added to
+            #   the ID.
+            # @return [String]
+            def render(e, reason = nil, id = allocate_exception_id)
+                counter = 0
+                html = []
+                seen = Set.new
+                each_exception_from(e) do |exception|
+                    if !seen.include?(exception)
+                        seen << exception
+                        html << render_single_exception(e, "#{id}-#{counter += 1}")
+                    end
+                end
+                html.join("\n")
+            end
+
+            # Method used by {#render} to discover all exception objects that
+            # are linked to another exception, in cases where exceptions cause
+            # one another
+            #
+            # The default implementation only yields 'e', reimplement in
+            # subclasses
+            #
+            # @yieldparam [Exception] exception an exception
+            def each_exception_from(e)
+                return enum_for(__method__) if !block_given?
+                yield(e)
+            end
+
+            # @api private
+            #
+            # Parses the exception backtrace, and generate a parsed raw and
+            # parsed filtered version of it
+            #
+            # @return [(Array<(String,Integer,String)>,Array<(String,Integer,String))>
+            #   the full and filtered backtraces, as list of tuples
+            #   (file,line,method)
+            def parse_and_filter_backtrace(backtrace)
+                full_backtrace = ExceptionRendering.parse_backtrace(backtrace)
+                filtered_backtrace = filter_backtrace(full_backtrace, backtrace)
+                if filtered_backtrace.first.respond_to?(:to_str)
+                    filtered_backtrace = ExceptionRendering.parse_backtrace(filtered_backtrace)
+                end
+                return full_backtrace, filtered_backtrace
+            end
+
+            # @api private
+            #
+            # Render a single exception object into a HTML block
+            #
+            # @param [Exception] e the exception
+            # @param [String] id the block ID
+            # @return [String]
+            def render_single_exception(e, id)
+                message = PP.pp(e, "").split("\n").
+                    map { |line| HTML.escape_html(line) }
+
+                full_backtrace, filtered_backtrace =
+                    parse_and_filter_backtrace(e.backtrace || Array.new)
+
+                if !full_backtrace.empty?
+                    origin_file, origin_line, origin_method =
+                        filtered_backtrace.find { |file, _| user_file?(file) } ||
+                        filtered_backtrace.first ||
+                        full_backtrace.first
+
+                    origin_file = linker.link_to(Pathname.new(origin_file), origin_file, lineno: origin_line)
+                    ERB.new(EXCEPTION_TEMPLATE_WITH_BACKTRACE).result(binding)
+                else
+                    ERB.new(EXCEPTION_TEMPLATE_WITHOUT_BACKTRACE).result(binding)
+                end
+            end
+
+            # @api private
+            #
+            # Render a backtrace
+            #
+            # It uses {#linker} to generate links, and {#user_file?} to change
+            # the style of the backtrace line.
+            def render_backtrace(backtrace)
+                result = []
+                backtrace.each do |file, line, method|
+                    file_link = linker.link_to(Pathname.new(file), file, lineno: line)
+                    if user_file?(file)
+                        result << "  <span class=\"user_file\">#{file_link}:#{line}:in #{HTML.escape_html(method.to_s)}</span><br/>"
+                    else
+                        result << "  #{file_link}:#{line}:in #{HTML.escape_html(method.to_s)}<br/>"
+                    end
+                end
+                result.join("\n")
+            end
+        end
+    end
+end
+