metasploit-model 0.25.7 → 0.26.1

data/lib/metasploit/model/search/association.rb

@@ -1,29 +1,173 @@
 module Metasploit
   module Model
     module Search
-      # Registers associations that can be searched.
+      # Use search operators registered on an associated class using
+      # {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute},
+      # {Metasploit::Model::Search::With::ClassMethods#search_with}.
+      #
+      # Searchable associations are declared explicitly so that associations cycles can be avoided and the search
+      # interface can be tuned for clarity and complexity.
+      #
+      # # Testing
+      #
+      # {ClassMethods#search_association} calls can be tested with the 'search_association' shared example.  First,
+      # ensure the shared examples from `metasploit-model` are required in your `spec_helper.rb`:
+      #
+      #     # spec/spec_helper.rb
+      #     support_glob = Metasploit::Model::Engine.root.join('spec', 'support', '**', '*.rb')
+      #
+      #     Dir.glob(support_glob) do |path|
+      #       require path
+      #     end
+      #
+      # In the spec for the `Class` that called `search_association`, use the 'search_association' shared example:
+      #
+      #     # spec/app/models/my_class_spec.rb
+      #     require 'spec_helper'
+      #
+      #     describe MyClass do
+      #       context 'search' do
+      #         context 'associations' do
+      #           it_should_be_like 'search_association', :association_name
+      #         end
+      #       end
+      #     end
+      #
+      # @example Search near and far associations
+      #   class Root
+      #     include Metasploit::Model::Association
+      #     include Metasploit::Model::Search
+      #
+      #     #
+      #     # Associations
+      #     #
+      #
+      #     association :children,
+      #                 class_name: 'Child'
+      #
+      #     #
+      #     # Search
+      #     #
+      #
+      #     search_association children: :grandchildren
+      #   end
+      #
+      #   class Child
+      #     include Metasploit::Model::Association
+      #     include Metasploit::Model::Search
+      #
+      #     #
+      #     # Associations
+      #     #
+      #
+      #     association :grandchildren,
+      #                 class_name: 'Grandchild'
+      #
+      #     #
+      #     # Search
+      #     #
+      #
+      #     search_attribute :name,
+      #                      type: :string
+      #   end
+      #
+      #   class Grandchild
+      #     include Metasploit::Model::Search
+      #
+      #     search_attribute :age,
+      #                      type: :integer
+      #   end
+      #
+      #   Root.search_operator_by_name.each_value
+      #   # :'children.name'
+      #   # :'children.grandchildren.age'
+      #
+      #   Child.search_operator_by_name.each_value
+      #   # :name
+      #   # @note ``:'grandchildren.age'`` is not in `Child`'s operators because it didn't declare
+      #   #   `search_association :grandchildren`, only `Root` did.
+      #
+      #   Grandchild.search_operator_name
+      #   # :age
+      #
       module Association
         extend ActiveSupport::Concern
 
         # Adds {#search_association} DSL to make {Metasploit::Model::Search::Operator::Association association search
         # operators}.
         module ClassMethods
+          # @note Use {#search_associations} to declare multiple associations or a tree of far associations as
+          #   searchable.
+          #
           # Registers association for search.
           #
+          # @example a single searchable association
+          #   search_association :children
+          #
           # @param association [#to_sym] name of association to search.
           # @return [void]
+          # @see #search_associations
           def search_association(association)
-            search_association_set.add(association.to_sym)
+            search_association_tree[association.to_sym] ||= nil
           end
 
-          # Set of all associations that are searchable.
+          # Registers a tree of near and far associations for search.  When a tree is used, all intermediate association
+          # on the paths are used, so `search_association children: :grandchildren` makes both `children.granchildren`
+          # *and* `children` as search operator prefixes.
+          #
+          # @example a single search association
+          #   search_associations :children
+          #
+          # @example multiple near associations
+          #   search_associations :first,
+          #                       :second
+          #
+          # @example far association
+          #   search_associations near: :far
+          #
+          # @example multiple far associations
+          #   search_associations near: [
+          #                         :first_far,
+          #                         :second_far
+          #                       ]
+          #
+          # @example mix of near and far associations
+          #   # Keep associations in order by near association names by mixing Symbols and Hash{Symbol => Object}
+          #   search_associations :apple,
+          #                       {
+          #                         banana: :peel
+          #                       },
+          #                       :cucumber
+          #
           #
-          # @example Adding association to search
-          #   search_association :things
+          # @param associations [Array<Array, Hash, Symbol>, Hash, Symbol]
+          # @return [void]
+          # @see search_association
+          def search_associations(*associations)
+            expanded_associations = Metasploit::Model::Association::Tree.expand(associations)
+
+            @search_association_tree = Metasploit::Model::Association::Tree.merge(
+                search_association_tree,
+                expanded_associations
+            )
+          end
+
+          # The association operators for the searchable associations declared with {#search_association} and
+          # {#search_associations}.
+          #
+          # @return (see Metasploit::Model::Association::Tree.operators)
+          def search_association_operators
+            @search_association_operators ||= Metasploit::Model::Association::Tree.operators(
+                search_association_tree,
+                class: self
+            )
+          end
+
+          # Tree of associations that are searchable.
           #
-          # @return [Set<Symbol>]
-          def search_association_set
-            @search_association_set ||= Set.new
+          # @return [Hash{Symbol => Hash,nil}]
+          def search_association_tree
+            @search_association_tree ||= {}
           end
         end
       end

data/lib/metasploit/model/search/attribute.rb

@@ -1,7 +1,117 @@
 module Metasploit
   module Model
     module Search
-      # Registers attributes that can be searched.
+      # Registers attributes that can be searched.  Attributes must be declared to be searchable as a type from
+      # {Metasploit::Model::Search::Operator::Attribute::TYPES}.  The type of the attribute is used to select a
+      # type-specific {Metasploit::Model::Search::Operation}, which will validate the
+      # {Metasploit::Model::Search::Operation::Base#value} is of the valid type.
+      #
+      # # Set attributes
+      #
+      # Search attributes declared as having an integer set or string set type integer or string set require a
+      # `<attribute>_set` method to be defined on the `Class`, which returns the set of allowed values for the search
+      # attribute's operation.  This method will be called, indirectly by
+      # {Metasploit::Model::Search::Operation::Set::Integer}'s and {Metasploit::Model::Search::Operation::Set::String}'s
+      # validations.
+      #
+      # # Help
+      #
+      # The help for each operator is uses the `I18n` system, so the help for an attribute operator on a given class can
+      # added to `config/locales/<lang>.yml`.  The scope of the lookup, under the language key is the `Class`'s
+      # `i18n_scope`, which is `metasploit.model` if the `Class` includes {Metasploit::Model::Translation} or
+      # `active_record` for `ActiveRecord::Base` subclasses.  Under the `i18n_scope`, any `Module#ancestor`'s
+      # `model_name.i18n_key` can be used to look up the help for an attribute's operator.  This allows for super
+      # classes or mixins to define the search operator help for subclasses.
+      #
+      #     # config/locales/<lang>.yml
+      #     <lang>:
+      #       <Class#i18n_scope>:
+      #         ancestors:
+      #           <ancestor.model_name.i18n_key>:
+      #             search:
+      #               operator:
+      #                 names:
+      #                   <attribute>:
+      #                     help: "The attribute on the class"
+      #
+      # # Testing
+      #
+      # {ClassMethods#search_attribute} calls can be tested with the 'search_attribute' shared example.  First, ensure
+      # the shared examples from `metasploit-model` are required in your `spec_helper.rb`:
+      #
+      #     # spec/spec_helper.rb
+      #     support_glob = Metasploit::Model::Engine.root.join('spec', 'support', '**', '*.rb')
+      #
+      #     Dir.glob(support_glob) do |path|
+      #       require path
+      #     end
+      #
+      # In the spec for the `Class` that called `search_attribute`, use the 'search_attribute' shared example by
+      # passing that arguments passed to {ClassMethods#search_attribute}.
+      #
+      #     # spec/app/models/my_class_spec.rb
+      #     require 'spec_helper'
+      #
+      #     describe MyClass do
+      #       context 'search' do
+      #         context 'attributes' do
+      #           it_should_behave_like 'search_attribute',
+      #                                 type: {
+      #                                   set: :string
+      #                                 }
+      #         end
+      #       end
+      #     end
+      #
+      # @example search an attribute for `true` or `false`
+      #    search_attribute :flag,
+      #                     type: :boolean
+      #
+      # @example search an attribute for an integer
+      #    search_attribute :age,
+      #                     type: :integer
+      #
+      # @example search an attribute for a restricted set of integers
+      #    #
+      #    # Search
+      #    #
+      #
+      #    search_attribute :bits,
+      #                     set: :integer
+      #
+      #    #
+      #    # Class Methods
+      #    #
+      #
+      #    # Return set of allowed values for {#bits} search.
+      #    #
+      #    # @return [Set<Integer>]
+      #    def self.bits_set
+      #      @bits_set ||= Set.new([32, 64])
+      #    end
+      #
+      # @example search an attribute for a restricted set of strings
+      #    #
+      #    # Search
+      #    #
+      #
+      #    search_attribute :endianness,
+      #                     set: :string
+      #
+      #    #
+      #    # Class Methods
+      #    #
+      #
+      #    # Return set of allowed values for {#endianness} search.
+      #    #
+      #    # @return [Set<String>]
+      #    def self.endianness_set
+      #      @endianness_set ||= Set.new(['big', 'litte'])
+      #    end
+      #
+      # @example search an attribute by substring (case-insensitve LIKE)
+      #    search_attribute :description,
+      #                     type: :string
       module Attribute
         extend ActiveSupport::Concern
 
@@ -10,27 +120,7 @@ module Metasploit
         # Adds {#search_attribute} DSL to make {Metasploit::Model::Search::Operator::Attribute attribute search
         # operators}.
         module ClassMethods
-          # Registers attribute for search.  Help for the operator supports i18n.
-          #
-          # @example defining help
-          #    # lib/metasploit/model/module/instance.rb
-          #    module Metasploit::Model::Module::Instance
-          #      include Metasploit::Model::Search
-          #
-          #      included do
-          #        search_attribute :description, :type => :string
-          #      end
-          #    end
-          #
-          #    # config/locales/en.yml
-          #    en:
-          #      metasploit:
-          #        model:
-          #          module:
-          #            instance:
-          #              search_attribute:
-          #                description:
-          #                  help: "A long, paragraph description of what the module does."
+          # {include:Metasploit::Model::Search::Attribute}
           #
           # @param attribute [#to_sym] name of attribute to search.
           # @param options [Hash{Symbol => String}]

data/lib/metasploit/model/search/operator.rb

@@ -1,7 +1,59 @@
 module Metasploit
   module Model
     module Search
-      # Namespace for search operators
+      # # Declaring operator classes
+      #
+      # ## Interface
+      #
+      # Operators do not need to subclass any specific superclass, but they are expected to define certain methods.
+      #
+      #     class MyOperator
+      #       #
+      #       # Instance Methods
+      #       #
+      #
+      #       # @param klass [Class] The klass on which `search_with` was called.
+      #       def initialize(attributes={})
+      #         # ...
+      #       end
+      #
+      #       # Description of what this operator searches for.
+      #       #
+      #       # @return [String]
+      #       def help
+      #         # ...
+      #       end
+      #
+      #       # Name of this operator.  The name of the operator is matched to the string before the ':' in a formatted
+      #       # operation.
+      #       #
+      #       # @return [Symbol]
+      #       def name
+      #         # ...
+      #       end
+      #
+      #       # Creates a one or more operations based on `formatted_value`.
+      #       #
+      #       # @return [#operator, Array<#operator>] Operation with this operator as the operation's `operator`.
+      #       def operate_on(formatted_value)
+      #         # ...
+      #       end
+      #     end
+      #
+      # ## Help
+      #
+      # Instead of having define your own `#help` method for your operator `Class`, you can `include`
+      # {Metasploit::Model::Search::Operator::Help}.
+      #
+      # {include:Metasploit::Model::Search::Operator::Help}
+      #
+      # ## {Metasploit::Model::Search::Operator::Base}
+      #
+      # {include:Metasploit::Model::Search::Operator::Base}
+      #
+      # ## {Metasploit::Model::Search::Operator::Single}
+      #
+      # {include:Metasploit::Model::Search::Operator::Single}
       module Operator
 
       end

data/lib/metasploit/model/search/operator/help.rb

@@ -2,7 +2,45 @@ module Metasploit
   module Model
     module Search
       module Operator
-        # Methods to lookup help text for an operator with a given `#name` registered to a given `#klass`.
+        # This allows the help to be looked up using `I18n`, and for the
+        # help to be customized based on the following criteria:
+        #
+        # `klass` on which the operator is declared, including any `Module#ancestors` and the operator `name`
+        #
+        #     # config/locales/<lang>.yml
+        #     <lang>:
+        #       <klass.i18n_scope>:
+        #         ancestors:
+        #           <klass_ancestor.model_name.i18n_key>:
+        #             search:
+        #               operator:
+        #                 names:
+        #                   <name>:
+        #                     help: "Help for searching <name> on <klass>"
+        #
+        # `class` of the operator, including any `Module#ancestors` and the operator `name`
+        #
+        #     # config/locales/<lang>.yml
+        #     <lang>:
+        #       <operator.class.i18n_scope>:
+        #         search:
+        #           operator:
+        #             ancestors:
+        #               <operator_class_ancestor.model_name.i18n_key>:
+        #                 <name>:
+        #                   help: "Help for searching <name> using <operator.class>"
+        #
+        # `class` of the operator, including any `Module#ancestors` without the operator `name`
+        #
+        #     # config/locales/<lang>.yml
+        #     <lang>:
+        #       <operator.class.i18n_scope>:
+        #         search:
+        #           operator:
+        #             ancestors:
+        #               <operator_class_ancestor.model_name.i18n_key>:
+        #                 help: "Help for searching using <operator.class>"
+        #
         module Help
           # @note This uses I18n.translate along with {Metasploit::Model::Translation#search_i18n_scope},
           #   the value is not cached to support changing the I18n.locale and getting the correct help message for that

data/lib/metasploit/model/search/with.rb

@@ -1,7 +1,50 @@
 module Metasploit
   module Model
     module Search
-      # Generalizes operators from attributes to anything directly registered as an operator on a class.
+      # Generalizes {Metasploit::Model::Search::Attribute operators from attributes} to anything directly registered as
+      # an operator on a class.
+      #
+      # {include:Metasploit::Model::Search::Operator}
+      #
+      # # Testing
+      #
+      # {ClassMethods#search_with} calls can be tested with the 'search_with' shared example.  First, ensure
+      # the shared examples from `metasploit-model` are required in your `spec_helper.rb`:
+      #
+      #     # spec/spec_helper.rb
+      #     support_glob = Metasploit::Model::Engine.root.join('spec', 'support', '**', '*.rb')
+      #
+      #     Dir.glob(support_glob) do |path|
+      #       require path
+      #     end
+      #
+      # In the spec fo the `Class` that called `search_with`, use the 'search_with' shared example by passing the
+      # arguments passed to {ClassMethods#search_attribute}.
+      #
+      #     # app/models/my_class.rb
+      #     class MyClass
+      #       include Metasploit::Model::Search
+      #
+      #       #
+      #       # Search
+      #       #
+      #
+      #       search_with MyOperatorClass,
+      #                   foo: :bar
+      #     end
+      #
+      #     # spec/app/models/my_class_spec.rb
+      #     require 'spec_helper'
+      #
+      #     describe MyClass do
+      #       context 'search' do
+      #         context 'attributes' do
+      #           it_should_behave_like 'search_with',
+      #                                 MyOperatorClass,
+      #                                 foo: :bar
+      #         end
+      #       end
+      #     end
       module With
         extend ActiveSupport::Concern