RubyGems - metaruby - Versions diffs - 1.0.0.rc2 → 1.0.0.rc3 - Mend

metaruby 1.0.0.rc2 → 1.0.0.rc3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

checksums.yaml +4 -4
data/.gitignore +1 -0
data/.travis.yml +4 -0
data/README.md +4 -4
data/lib/metaruby.rb +8 -1
data/lib/metaruby/class.rb +13 -9
data/lib/metaruby/dsls.rb +6 -0
data/lib/metaruby/gui.rb +16 -0
data/lib/metaruby/gui/exception_rendering.rb +281 -0
data/lib/metaruby/gui/exception_view.rb +32 -111
data/lib/metaruby/gui/html.rb +7 -0
data/lib/metaruby/gui/html/button.rb +54 -12
data/lib/metaruby/gui/html/collection.rb +33 -9
data/lib/metaruby/gui/html/exception_view.css +4 -6
data/lib/metaruby/gui/html/list.rhtml +3 -3
data/lib/metaruby/gui/html/page.rb +233 -53
data/lib/metaruby/gui/html/page.rhtml +6 -5
data/lib/metaruby/gui/model_browser.rb +15 -6
data/lib/metaruby/gui/model_selector.rb +57 -11
data/lib/metaruby/gui/rendering_manager.rb +36 -7
data/lib/metaruby/gui/ruby_constants_item_model.rb +155 -42
data/lib/metaruby/inherited_attribute.rb +59 -8
data/lib/metaruby/module.rb +29 -12
data/lib/metaruby/registration.rb +44 -12
data/lib/metaruby/test.rb +6 -10
data/lib/metaruby/version.rb +2 -1
data/lib/yard-metaruby.rb +10 -3
data/manifest.xml +1 -0
data/metaruby.gemspec +1 -1
metadata +5 -4

data/lib/metaruby/gui/html/page.rhtml CHANGED Viewed

@@ -1,15 +1,16 @@
 <% prefix = if ressource_dir[0, 1] == "/" then "file://"
             end
 %>
-<html>
+<head>
     <link rel="stylesheet" href="<%= prefix %><%= File.join(ressource_dir, 'page.css') %>" type="text/css" />
     <script type="text/javascript" src="<%= prefix %><%= File.join(ressource_dir, 'jquery.min.js') %>"></script>
     <script type="text/javascript" src="<%= prefix %><%= File.join(ressource_dir, 'jquery.selectfilter.js') %>"></script>
-    <% javascript.each do |js| %>
-        <script type="text/javascript" src="<%= prefix %><%= File.expand_path(js, ressource_dir) %>"></script>
-    <% end %>
+    <%= head.join("\n").gsub('${RESOURCE_DIR}', "#{prefix}#{ressource_dir}") %>
+<% if page_name %>
     <title><%= page_name %></title>
-</html>
+<% end %>
+</head>
+<%= scripts.join("\n").gsub('${RESOURCE_DIR}', "#{prefix}#{ressource_dir}") %>
 <body>
     <%= html_body(ressource_dir: ressource_dir) %>
 </body>

data/lib/metaruby/gui/model_browser.rb CHANGED Viewed

@@ -54,9 +54,12 @@ module MetaRuby
             #   the model view
             attr_reader :central_splitter
-            # A Page object with a #link_to method that is suitable for the
-            # model browser
+            # A Page object tunes to create URIs for objects that are suitable
+            # for {#model_selector}
             class Page < HTML::Page
+                # Overloaded from {HTML::Page} to resolve object paths (in the
+                #   constant hierarchy, e.g. A::B::C) into the corresponding
+                #   path expected by {#model_selector} (e.g. /A/B/C)
                 def uri_for(object)
                     if object.respond_to?(:name) && (obj_name = object.name) && (obj_name =~ /^[\w:]+$/)
                         path = obj_name.split("::")
@@ -66,7 +69,6 @@ module MetaRuby
                 end
             end
             def initialize(main = nil, exception_view: nil)
                 super(main)
@@ -95,6 +97,10 @@ module MetaRuby
                 update_exceptions
             end
+            # Restore the state of this widget from settings previously saved
+            # with {#save_to_settings}
+            #
+            # @param [Qt::Settings] settings
             def restore_from_settings(settings)
                 %w{central_splitter vertical_splitter}.each do |object_name|
                     sizes = settings.value(object_name)
@@ -107,6 +113,9 @@ module MetaRuby
                 end
             end
+            # Save the current state of this widget in the given settings
+            #
+            # @param [Qt::Settings] settings
             def save_to_settings(settings)
                 %w{central_splitter vertical_splitter}.each do |object_name|
                     sizes = send(object_name).sizes
@@ -115,7 +124,7 @@ module MetaRuby
                 end
             end
-            # Update the model selector after {register_type} got called
+            # Update the model selector after {#register_type} got called
             def update_model_selector
                 model_selector.update
             end
@@ -126,7 +135,7 @@ module MetaRuby
             # It registers the given type on the model browser so that it gets
             # displayed there.
             #
-            # You must call {update_model_selector} after this call for the
+            # You must call {#update_model_selector} after this call for the
             # modification to have any effect (i.e. for the newly registered
             # models to appear on the selector)
             #
@@ -204,7 +213,7 @@ module MetaRuby
             # Call to render the given model
             #
             # @param [Model] mod the model that should be rendered
-            # @raises [ArgumentError] if there is no view available for the
+            # @raise [ArgumentError] if there is no view available for the
             #   given model
             def render_model(mod, options = Hash.new)
                 page.clear

data/lib/metaruby/gui/model_selector.rb CHANGED Viewed

@@ -1,20 +1,42 @@
 module MetaRuby
     module GUI
-        # A Qt widget that allows to browse the models registered in the Ruby
-        # constanat hierarchy
+        # A Qt widget based on {RubyConstantsItemModel} to browse a set of
+        # models, and display them when the user selects one
         class ModelSelector < Qt::Widget
-            attr_reader :btn_type_filter_menu
+            # A per-type matching of the type to the actio that allows to
+            # filter/unfilter on this type
+            #
+            # @return [Hash<Module,Qt::Action>]
             attr_reader :type_filters
+            # The view that shows the object hierarchy
+            #
+            # @return [Qt::TreeView]
             attr_reader :model_list
+            # Qt model filter
+            # @return [Qt::SortFilterProxyModel]
             attr_reader :model_filter
+            # (see {RubyConstantsItemModel#type_info)
+            attr_reader :type_info
+            # The Qt item model that represents the object hierarchy
+            # @return [RubyConstantsItemModel]
+            attr_reader :browser_model
+            # @return [Qt::PushButton] a button allowing to filter models by
+            #   type
+            attr_reader :btn_type_filter_menu
             # @return [Qt::LineEdit] the line edit widget that allows to modify
             #   the tree view filter
             attr_reader :filter_box
-            # @return [Qt::Completer] auto-completion for {filter_box}
+            # @return [Qt::Completer] auto-completion for {#filter_box}
             attr_reader :filter_completer
-            attr_reader :type_info
-            attr_reader :browser_model
+            # Create a new widget with an optional parent
+            #
+            # @param [Qt::Widget,nil] parent
             def initialize(parent = nil)
                 super
@@ -35,6 +57,14 @@ module MetaRuby
                 setTabOrder(filter_button, model_list)
             end
+            # Register a new object type
+            #
+            # @param [Module] model_base a module or class whose all objects of
+            #   this type have as superclass
+            # @param [String] name the string that should be used to represent
+            #   objects of this type
+            # @param [Integer] priority if an object's ancestry matches multiple
+            #   types, only the ones of the highest priority will be retained
             def register_type(model_base, name, priority = 0)
                 type_info[model_base] = RubyConstantsItemModel::TypeInfo.new(name, priority)
                 action = Qt::Action.new(name, self)
@@ -47,11 +77,15 @@ module MetaRuby
                 end
             end
+            # Update the view, reloading the underlying model
             def update
                 update_model_filter
                 reload
             end
+            # @api private
+            #
+            # Update {#model_filter} to match the current filter setup
             def update_model_filter
                 type_rx = type_filters.map do |model_base, act|
                     if act.checked?
@@ -74,6 +108,10 @@ module MetaRuby
                 auto_open
             end
+            # Auto-open in the current state
+            #
+            # @param [Integer] threshold the method opens items whose number of
+            #   children is lower than this threshold
             def auto_open(threshold = 5)
                 current_level = [Qt::ModelIndex.new]
                 while !current_level.empty?
@@ -97,6 +135,7 @@ module MetaRuby
                 end
             end
+            # Tests if an object if a model
             def model?(obj)
                 type_info.any? do |model_base, _|
                     obj.kind_of?(model_base) ||
@@ -113,6 +152,9 @@ module MetaRuby
                 end
             end
+            # @api private
+            #
+            # Helper method for {#select_first_item}
             def all_leaves(model, limit = nil, item = Qt::ModelIndex.new, result = [])
                 if !model.hasChildren(item)
                     result << item
@@ -131,12 +173,16 @@ module MetaRuby
                 return result
             end
+            # Select the first displayed item
             def select_first_item
                 if item = all_leaves(model_filter, 1).first
                     model_list.setCurrentIndex(item)
                 end
             end
+            # @api private
+            #
+            # Create and setup {#model_list}
             def setup_tree_view(layout)
                 @model_list = Qt::TreeView.new(self)
                 @model_filter = Qt::SortFilterProxyModel.new
@@ -169,6 +215,7 @@ module MetaRuby
             end
             signals 'model_selected(QVariant)'
+            # Reload the object model, keeping the current selection if possible
             def reload
                 if current = current_selection
                     current_module = current.this
@@ -202,12 +249,11 @@ module MetaRuby
             # control whether the filter should be reset if the index given as
             # parameter is currently filtered out
             #
-            # @param [Qt::ModelIndex] an index valid in {browser_model}
-            # @option options [Boolean] :reset_filter (true) if true, the filter
+            # @param [Qt::ModelIndex] source_index an index valid in {#browser_model}
+            # @param [Boolean] reset_filter if true, the filter
             #   is reset if the requested index is currently filtered out
-            # @return [Qt::ModelIndex] an index filtered by {model_filter}
-            def map_index_from_source(source_index, options = Hash.new)
-                options = Kernel.validate_options options, :reset_filter => true
+            # @return [Qt::ModelIndex] an index filtered by {#model_filter}
+            def map_index_from_source(source_index, reset_filter: true)
                 index = model_filter.map_from_source(source_index)
                 if !index
                     return

data/lib/metaruby/gui/rendering_manager.rb CHANGED Viewed

@@ -1,5 +1,10 @@
 module MetaRuby
     module GUI
+        # Management of HTML rendering of objects of different types
+        #
+        # Objects of this class allow to register a set of renderers, dedicated
+        # to rendering objects of a certain type (defined as a superclass) and
+        # automatically switch between the rendering objects.
         class RenderingManager < Qt::Object
             # @return [#push] the page object on which we render
             attr_reader :page
@@ -10,15 +15,19 @@ module MetaRuby
             #   matches will be used.
             #   Do not modify directly, use {#register_type} instead
             attr_reader :available_renderers
-            # The last used rendering objects
+            # The rendering object used last in {#render}
             attr_reader :current_renderer
+            # Create a rendering manager that acts on a given page
             def initialize(page = nil)
                 super()
                 @page = page
                 @available_renderers = Hash.new
             end
+            # A list of exceptions that happened during rendering
+            #
+            # @return [Array<Exception>]
             def registered_exceptions
                 if current_renderer.respond_to?(:registered_exceptions)
                     current_renderer.registered_exceptions
@@ -32,12 +41,15 @@ module MetaRuby
             # It registers the given type on the model browser so that it gets
             # displayed there.
             #
-            # @param [Class] type the base model class for the models that are
-            #   considered here
+            # @param [Class] type objects whose class or ancestry include 'type'
+            #   will be rendered using the provided rendering class. If more tha
+            #   none matches, the first one is used.
             # @param [Class] rendering_class a class from which a relevant
             #   rendering object can be created. The generated instances must
             #   follow the rules described in the documentation of
             #   {ModelBrowser}
+            # @param [Hash] render_options a set of options that must be passed
+            #   to the renderer's #render method
             def register_type(type, rendering_class, render_options = Hash.new)
                 render = if rendering_class.kind_of?(Class)
                              rendering_class.new(page)
@@ -60,37 +72,54 @@ module MetaRuby
                 end
             end
+            # @api private
+            #
+            # Find a rendering object for the given object
+            #
+            # @param [Object] mod the object we need to render
+            # @return [(Class,(#render,Hash)),nil] either the base class,
+            #   rendering object and rendering options that should be used for
+            #   the given object, or nil if there are no matching rendering
+            #   objects
             def find_renderer(mod)
                 available_renderers.find do |model, _|
                     mod.kind_of?(model) || (mod.kind_of?(Module) && model.kind_of?(Module) && mod <= model)
                 end
             end
+            # Disable the current renderer
             def disable
                 if current_renderer
                     current_renderer.disable
                 end
             end
+            # Enable the current renderer
             def enable
                 if current_renderer
                     current_renderer.enable
                 end
             end
+            # Clear the current renderer
             def clear
                 if current_renderer
                     current_renderer.clear
                 end
             end
             # Call to render the given model
             #
-            # @param [Model] mod the model that should be rendered
-            # @raises [ArgumentError] if there is no view available for the
+            # The renderer that has been used is made active (enabled) and
+            # stored in {#current_renderer}. The previous one is disabled and
+            # cleared.
+            #
+            # @param [Model] object the model that should be rendered
+            # @param [Hash] push_options options that should be passed to the
+            #   object's renderer {#render} method
+            # @raise [ArgumentError] if there is no view available for the
             #   given model
-            def render(object, push_options = Hash.new)
+            def render(object, **push_options)
                 _, (renderer, render_options) = find_renderer(object)
                 if renderer
                     if current_renderer

data/lib/metaruby/gui/ruby_constants_item_model.rb CHANGED Viewed

@@ -1,21 +1,69 @@
 module MetaRuby
     module GUI
-        # A Qt item model that lists Ruby modules that match a given predicate
-        # (given at construction time)
+        # A Qt item model that enumerates models stored in the Ruby constant
+        # hierarchy
+        #
+        # The model exposes all registered constants for which {#predicate}
+        # returns true in a hierarchy, allowing the user to interact with it.
+        #
+        # Discovery starts at Object
         class RubyConstantsItemModel < Qt::AbstractItemModel
+            # Stored per-module information test
             ModuleInfo = Struct.new :id, :name, :this, :parent, :children, :row, :types, :full_name, :keyword_string, :path
+            # Information about different model types
             TypeInfo   = Struct.new :name, :priority, :color
+            # Predicate that filters objects in addition to {#excludes}
+            #
+            # Only objects for which #call returns true and the constants that
+            # contain them are exposed by this model
+            #
+            # @return [#call]
             attr_reader :predicate
+            # Explicitely excluded objects
+            #
+            # Set of objects that should be excluded from discovery, regardless
+            # of what {#predicate} would return from them.
+            #
+            # Note that such objects are not discovered at all, meaning that if
+            # they contain objects that should have been discovered, they won't
+            # be.
+            #
+            # @return [Set]
+            attr_reader :excludes
+            # A list of expected object types
+            #
+            # This is used to decide where a given object should be "attached"
+            # in the hierarchy. Matching types are stored in {ModuleInfo#types}.
+            #
+            # @return [{Class=>TypeInfo}]
+            attr_reader :type_info
+            # Mapping from module ID to a module object
+            #
+            # @return [{Integer=>ModuleInfo}]
             attr_reader :id_to_module
+            # Set of objects that have been filtered out by {#predicate}
             attr_reader :filtered_out_modules
-            attr_reader :type_info
+            # Name of the root item
+            #
+            # @return [String]
             attr_accessor :title
+            # List of paths for each of the discovered objects
+            #
+            # @return [{Object=>String}]
             attr_reader :object_paths
-            # @return [Set<Object>] a set of objects that should not be
-            #   discovered
-            attr_reader :excludes
+            # Initialize this model for objects of the given type
+            #
+            # @param [Hash] type_info value for {#type_info}
+            # @param [#call] predicate the filter {#predicate}
             def initialize(type_info = Hash.new, &predicate)
                 super()
                 @predicate = predicate || proc { true }
@@ -28,6 +76,7 @@ module MetaRuby
                 @object_paths = Hash.new
             end
+            # Discovers or rediscovers the objects
             def reload
                 begin_reset_model
                 @id_to_module = []
@@ -46,10 +95,19 @@ module MetaRuby
                 end_reset_model
             end
+            # {ModuleInfo} for the root
             def root_info
                 id_to_module.last
             end
+            # @api private
+            #
+            # Generate the path information, i.e. per-object path string
+            #
+            # @param [Hash] paths the generated paths (matches {#object_paths})
+            # @param [ModuleInfo] info the object information for the object to
+            #   be discovered
+            # @param [String] current the path of 'info'
             def generate_paths(paths, info, current)
                 info.children.each do |child|
                     child_uri = current + '/' + child.name
@@ -58,6 +116,12 @@ module MetaRuby
                 end
             end
+            # @api private
+            #
+            # Updates {ModuleInfo#types} so that it includes the type of its
+            #   children
+            #
+            # @param [ModuleInfo] info the object info that should be updated
             def update_module_type_info(info)
                 types = info.types.to_set
                 info.children.each do |child_info|
@@ -68,6 +132,13 @@ module MetaRuby
                 end.reverse
             end
+            # @api private
+            #
+            # Discovers an object and its children
+            #
+            # @param [Object] mod an object that should be discovered
+            # @param [Array] stack the current stack (to avoid infinite recursions)
+            # @return [ModuleInfo]
             def discover_module(mod, stack = Array.new)
                 return if excludes.include?(mod)
                 stack.push mod
@@ -143,13 +214,13 @@ module MetaRuby
             ensure stack.pop
             end
-            def headerData(section, orientation, role)
-                if role == Qt::DisplayRole && section == 0
-                    Qt::Variant.new(title)
-                else Qt::Variant.new
-                end
-            end
+            # @api private
+            #
+            # Lazily computes the full name of a discovered object. It updates
+            # {ModuleInfo#full_name}
+            #
+            # @param [ModuleInfo] info
+            # @return [String]
             def compute_full_name(info)
                 if name = info.full_name
                     return name
@@ -164,6 +235,13 @@ module MetaRuby
                 end
             end
+            # @api private
+            #
+            # Lazily compute the path of a discovered object. The result is
+            # stored in {ModuleInfo#path}
+            #
+            # @param [ModuleInfo] info
+            # @return [String]
             def compute_path(info)
                 if path = info.path
                     return path
@@ -173,6 +251,57 @@ module MetaRuby
                 end
             end
+            # Resolves a {ModuleInfo} from a Qt::ModelIndex
+            def info_from_index(index)
+                if !index.valid?
+                    return id_to_module.last
+                else
+                    id_to_module[index.internal_id >> 1]
+                end
+            end
+            # Return the Qt::ModelIndex that represents a given object
+            #
+            # @return [Qt::ModelIndex,nil] the index, or nil if the object is
+            #   not included in this model
+            def find_index_by_model(model)
+                if info = id_to_module.find { |info| info.this == model }
+                    return create_index(info.row, 0, info.id)
+                end
+            end
+            # Returns the Qt::ModelIndex that matches a given path
+            #
+            # @param [Array<String>] path path to the desired object
+            # @return [Qt::ModelIndex,nil] the index, or nil if the path does
+            #   not resolve to an object included in this model
+            def find_index_by_path(*path)
+                current = id_to_module.last
+                if path.first == current.name
+                    path.shift
+                end
+                path.each do |name|
+                    current = id_to_module.find do |info|
+                        info.name == name && info.parent == current
+                    end
+                    return if !current
+                end
+                create_index(current.row, 0, current.id)
+            end
+            # @api private
+            #
+            # Lazily compute a comma-separated string that can be used to search
+            # for the given node. The result is stored in
+            # {ModuleInfo#keyword_string}
+            #
+            # The returned string is of the form
+            #     type0[,type1...]:name0[,name1...]
+            #
+            # @param [ModuleInfo] info
+            # @return [String]
             def compute_keyword_string(info)
                 if keywords = info.keyword_string
                     return keywords
@@ -186,6 +315,15 @@ module MetaRuby
                 end
             end
+            # Reimplemented for Qt model interface
+            def headerData(section, orientation, role)
+                if role == Qt::DisplayRole && section == 0
+                    Qt::Variant.new(title)
+                else Qt::Variant.new
+                end
+            end
+            # Reimplemented for Qt model interface
             def data(index, role)
                 if info = info_from_index(index)
                     if role == Qt::DisplayRole
@@ -199,6 +337,7 @@ module MetaRuby
                 return Qt::Variant.new
             end
+            # Reimplemented for Qt model interface
             def index(row, column, parent)
                 if info = info_from_index(parent)
                     if child_info = info.children[row]
@@ -208,6 +347,7 @@ module MetaRuby
                 Qt::ModelIndex.new
             end
+            # Reimplemented for Qt model interface
             def parent(child)
                 if info = info_from_index(child)
                     if info.parent && info.parent != root_info
@@ -217,6 +357,7 @@ module MetaRuby
                 Qt::ModelIndex.new
             end
+            # Reimplemented for Qt model interface
             def rowCount(parent)
                 if info = info_from_index(parent)
                     info.children.size
@@ -224,38 +365,10 @@ module MetaRuby
                 end
             end
+            # Reimplemented for Qt model interface
             def columnCount(parent)
                 return 1
             end
-            def info_from_index(index)
-                if !index.valid?
-                    return id_to_module.last
-                else
-                    id_to_module[index.internal_id >> 1]
-                end
-            end
-            def find_index_by_model(model)
-                if info = id_to_module.find { |info| info.this == model }
-                    return create_index(info.row, 0, info.id)
-                end
-            end
-            def find_index_by_path(*path)
-                current = id_to_module.last
-                if path.first == current.name
-                    path.shift
-                end
-                path.each do |name|
-                    current = id_to_module.find do |info|
-                        info.name == name && info.parent == current
-                    end
-                    return if !current
-                end
-                create_index(current.row, 0, current.id)
-            end
         end
     end
 end