metasploit-model 0.27.3 → 0.27.4

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

@@ -1,176 +1,170 @@
-module Metasploit
-  module Model
-    module Search
-      # 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
+# 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 Metasploit::Model::Search::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_tree[association.to_sym] ||= nil
-          end
+  # 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_tree[association.to_sym] ||= nil
+    end
 
-          # 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
-          #
-          #
-          # @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)
+    # 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
+    #
+    #
+    # @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
+      @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
+    # 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 [Hash{Symbol => Hash,nil}]
-          def search_association_tree
-            @search_association_tree ||= {}
-          end
-        end
-      end
+    # Tree of associations that are searchable.
+    #
+    # @return [Hash{Symbol => Hash,nil}]
+    def search_association_tree
+      @search_association_tree ||= {}
     end
   end
-end
+end

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

@@ -1,143 +1,135 @@
-require 'metasploit/model/search/with'
+# 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 Metasploit::Model::Search::Attribute
+  extend ActiveSupport::Concern
 
-module Metasploit
-  module Model
-    module Search
-      # 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
+  include Metasploit::Model::Search::With
 
-        include Metasploit::Model::Search::With
-
-        # Adds {#search_attribute} DSL to make {Metasploit::Model::Search::Operator::Attribute attribute search
-        # operators}.
-        module ClassMethods
-          # {include:Metasploit::Model::Search::Attribute}
-          #
-          # @param attribute [#to_sym] name of attribute to search.
-          # @param options [Hash{Symbol => String}]
-          # @option options [Symbol] :type The type of the attribute.  Used to determine how to parse the search values
-          #   and which modifiers are supported.
-          # @return (see Metasploit::Model::Search::With::ClassMethods#search_with)
-          # @raise [Metasploit::Model::Invalid] unless attribute is present
-          # @raise [Metasploit::Model::Invalid] unless :type is present
-          def search_attribute(attribute, options={})
-            search_with Metasploit::Model::Search::Operator::Attribute,
-                        :attribute => attribute,
-                        :type => options[:type]
-          end
-        end
-      end
+  # Adds {#search_attribute} DSL to make {Metasploit::Model::Search::Operator::Attribute attribute search
+  # operators}.
+  module ClassMethods
+    # {include:Metasploit::Model::Search::Attribute}
+    #
+    # @param attribute [#to_sym] name of attribute to search.
+    # @param options [Hash{Symbol => String}]
+    # @option options [Symbol] :type The type of the attribute.  Used to determine how to parse the search values
+    #   and which modifiers are supported.
+    # @return (see Metasploit::Model::Search::With::ClassMethods#search_with)
+    # @raise [Metasploit::Model::Invalid] unless attribute is present
+    # @raise [Metasploit::Model::Invalid] unless :type is present
+    def search_attribute(attribute, options={})
+      search_with Metasploit::Model::Search::Operator::Attribute,
+                  :attribute => attribute,
+                  :type => options[:type]
     end
   end
-end
+end