yard-sequel 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9284ee1351b6a7f96efc170c14aef164245d849790b08ace886b7e94a86c305f
-  data.tar.gz: 5c3d39bd376f18edf52a20b4d5e729a0c52ced190435161b5a6cf6fb37dce4ad
+  metadata.gz: de753ba555cdc4d50a3529d696acfc430267520084be6be153350a53a7d6f0e0
+  data.tar.gz: a2a0b1b504e2e37dd52e484fdf8880186b13a7d7f28f4db8e11082cec38e86ec
 SHA512:
-  metadata.gz: 846c464a14c21f7f0c415961f6ced942deb2247143a20675a8b22dd7cde9becb2ed017e7d438f538ccb6a098139695cc1fadf96fae608084c0780a9d1bc3bcc8
-  data.tar.gz: 95a2d3e008efc2c0f6b4839465b70eaae1fc10de39cdefac228236ab3a62ebf61773314f381b3570d530a9830a45c773fc51b797cc0eb0ace075ef252ef91e58
+  metadata.gz: 18d50a853a958f1999996ecd350626c778a9be1c9288a37b45167927c8264e61bf5ac2521f7bf80501734dec183192cfac5d7bbcbc326f355dcf62c730810f0d
+  data.tar.gz: 222fcedd00f7b9be0f62ceffa307ca39ce62494447f4be0f76b86cb3ad8e13cad91c5321b0f325f5f5facc88a0d09fd73adf05352be3d10e4340630ee47a6071

data/lib/yard-sequel.rb

@@ -10,4 +10,5 @@ Sequel.extension :inflector
 module YardSequel; end
 
 require_relative 'yard-sequel/associations'
+require_relative 'yard-sequel/association_options'
 require_relative 'yard-sequel/ast_node_hash'

data/lib/yard-sequel/association_options.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module YardSequel
+  # Holds the options of an association macro call and makes them easily
+  # accessible.
+  # @author Kai Moschcau
+  class AssociationOptions
+    # @param [Hash<Yard::Parser::Ruby::AstNode>] ast_node_hash A Hash created
+    #   with the {AstNodeHash} module, to get the options from.
+    def initialize(ast_node_hash)
+      @ast_node_hash = {}
+      ast_node_hash.each do |name, parameter|
+        @ast_node_hash[parse_symbol_node name] = parse_symbol_node parameter
+      end
+    end
+
+    # @param [Symbol] option_name The name of the option, to get the parameter
+    #   of.
+    # @return [Yard::Parser::Ruby::AstNode] the option parameter value.
+    def [](option_name)
+      @ast_node_hash[option_name]
+    end
+
+    private
+
+    # Extracts the String content of a Symbol literal AstNode as a Symbol. It
+    # gets the source, then removes the leading or trailing colon. Afterwards it
+    # removes the leading and trailing quotes, if there are any and returns the
+    # result as a Symbol.
+    # @param [Yard::Parser::Ruby::AstNode] ast_node The Symbol literal AstNode
+    #   to get the content from.
+    # @return [Symbol] the Symbol literal's content as a Symbol.
+    def extract_symbol_content(ast_node)
+      ast_node.source.gsub(/(?:^:|:$)/, '').gsub(/(?:^['"]|['"]$)/, '').to_sym
+    end
+
+    # Parses a Symbol literal AstNode, if possible. This will return a Symbol
+    # with the Symbol literal's content String, if the literal is a Hash label,
+    # a normal Symbol literal or a dynamic Symbol literal without interpolation.
+    # @param [Yard::Parser::Ruby::AstNode] symbol_node The AstNode to get the
+    #   content String from.
+    # @return [Symbol] the parsed Symbol.
+    # @return [Yard::Parser::Ruby::AstNode] the passed node, if it could not be
+    #   parsed.
+    def parse_symbol_node(symbol_node)
+      if %i[symbol_literal label dyna_symbol].include? symbol_node.type
+        # Return if the literal contains interpolation
+        return symbol_node if symbol_node.jump(:string_embexpr) != symbol_node
+
+        return extract_symbol_content(symbol_node)
+      end
+
+      symbol_node
+    end
+  end
+end

data/lib/yard-sequel/associations/association_handler.rb

@@ -7,13 +7,14 @@ module YardSequel
     class AssociationHandler < YARD::Handlers::Ruby::DSLHandler
       def process
         log.debug { "#{self.class.name}#process call" }
+        @association_options = association_options
       end
 
       protected
 
       # Adds a parameter tag to a method object.
-      # @param [YARD::CodeObjects::MethodObject] method
-      #   The method to add the parameter tag to.
+      # @param [YARD::CodeObjects::MethodObject] method The method to add the
+      #   parameter tag to.
       # @param [String] name The name of the parameter.
       # @param [String] class_name The class name of the parameter.
       # @param [String] description The description of the parameter.
@@ -25,15 +26,46 @@ module YardSequel
         )
       end
 
+      # @return [String] the association Class without namespace.
+      def association_class
+        class_param = @association_options&.[](:class)
+        return class_param.to_s.split('::').last if
+          [String, Symbol].include? class_param.class
+
+        association_name.classify
+      end
+
+      # @return [String] the namespace of the association class.
+      def association_class_namespace
+        class_namespace_param = @association_options&.[](:class_namespace)
+        return class_namespace_param.to_s if
+          [String, Symbol].include? class_namespace_param.class
+
+        class_param = @association_options&.[](:class)
+        return class_param.to_s.rpartition('::').first if
+          [String, Symbol].include? class_param.class
+      end
+
+      # @return [String] the association Class with namespace.
+      def association_full_class
+        [association_class_namespace, association_class].compact.join('::')
+      end
+
       # @return [String] the name of the association
       def association_name
         @statement.parameters.first.jump(:ident).source
       end
 
-      # @return [Array<YARD::Parser::Ruby::AstNode>] the association nodes
-      #   of the options Hash.
+      # @return [nil] If the association does not have an options parameter or
+      #   it is empty.
+      # @return [AssociationOptions] the AssociationOptions of the association.
       def association_options
-        @statement.parameters[1].filter { |node| node.type == :assoc }
+        option_param = @statement.parameters[1] || return
+        AssociationOptions.new AstNodeHash.from_ast(option_param)
+      rescue ArgumentError, TypeError => error
+        log.warn 'Could not parse association options due to syntax error.'
+        log.debug error.message
+        nil
       end
 
       # @param [String] name The name of the method object.

data/lib/yard-sequel/associations/many_to_one_handler.rb

@@ -9,11 +9,15 @@ module YardSequel
       include YardSequel::Associations::ToOneMethods
       handles method_call(:many_to_one)
       namespace_only
+
       def process
         super
+        original_group = extra_state.group
+        extra_state.group = "Many to one #{association_name} association"
         create_to_one_getter
         create_to_one_setter
         create_dataset_method
+        extra_state.group = original_group
       end
     end
   end

data/lib/yard-sequel/associations/modules/dataset_method.rb

@@ -9,8 +9,7 @@ module YardSequel
       #   object.
       def create_dataset_method
         method = create_method_object("#{association_name}_dataset")
-        return_tag(method, 'Sequel::Dataset', 'the association\'s'\
-                                                    'dataset.')
+        return_tag(method, 'Sequel::Dataset', 'the association\'s dataset.')
         method
       end
     end

data/lib/yard-sequel/associations/modules/to_many_methods.rb

@@ -10,12 +10,12 @@ module YardSequel
       def create_to_many_adder
         name             = association_name
         method           = create_method_object "add_#{name.singularize}"
-        method.docstring += "Associates the passed #{name.classify} "\
+        method.docstring += "Associates the passed #{association_class} "\
                             'with `self`.'
-        add_param_tag(method, name.singularize, name.classify,
-                      "The #{name.classify} to associate with `self`.")
-        return_tag(method, name.classify,
-                   "the associated #{name.classify}.")
+        add_param_tag(method, name.singularize, association_full_class,
+                      "The #{association_class} to associate with `self`.")
+        return_tag(method, association_full_class,
+                   "the associated #{association_class}.")
         method
       end
 
@@ -25,7 +25,7 @@ module YardSequel
         name             = association_name
         method           = create_method_object "remove_all_#{name}"
         method.docstring += 'Removes the association of all '\
-                            "#{name.classify.pluralize} with `self`."
+                            "#{association_class.pluralize} with `self`."
         void_return_tag method
         method
       end
@@ -35,8 +35,8 @@ module YardSequel
       def create_to_many_getter
         name   = association_name
         method = create_method_object name
-        return_tag(method, "Array<#{name.classify}>",
-                   "the associated #{name.classify.pluralize}.")
+        return_tag(method, "Array<#{association_full_class}>",
+                   "the associated #{association_class.pluralize}.")
         method
       end
 
@@ -46,9 +46,9 @@ module YardSequel
         name             = association_name
         method           = create_method_object "remove_#{name.singularize}"
         method.docstring += 'Removes the association of the passed '\
-                            "#{name.classify} with `self`."
-        add_param_tag(method, name.singularize, name.classify,
-                      "The #{name.classify} to remove the association "\
+                            "#{association_class} with `self`."
+        add_param_tag(method, name.singularize, association_full_class,
+                      "The #{association_class} to remove the association "\
                       'with `self` from.')
         void_return_tag method
         method

data/lib/yard-sequel/associations/modules/to_one_methods.rb

@@ -10,8 +10,8 @@ module YardSequel
       def create_to_one_getter
         name   = association_name
         method = create_method_object name
-        return_tag(method, name.classify,
-                   "the associated #{name.classify}.")
+        return_tag(method, association_full_class,
+                   "the associated #{association_class}.")
         method
       end
 
@@ -20,12 +20,12 @@ module YardSequel
       def create_to_one_setter
         name             = association_name
         method           = create_method_object "#{name}="
-        method.docstring += "Associates the passed #{name.classify} "\
+        method.docstring += "Associates the passed #{association_class} "\
                             'with `self`.'
-        add_param_tag(method, name, name.classify,
-                      "The #{name.classify} to associate with `self`.")
-        return_tag(method, name.classify,
-                   "the associated #{name.classify}.")
+        add_param_tag(method, name, association_full_class,
+                      "The #{association_class} to associate with `self`.")
+        return_tag(method, association_full_class,
+                   "the associated #{association_class}.")
         method
       end
     end

data/lib/yard-sequel/associations/one_to_many_handler.rb

@@ -9,13 +9,17 @@ module YardSequel
       include YardSequel::Associations::ToManyMethods
       handles method_call(:one_to_many)
       namespace_only
+
       def process
         super
+        original_group = extra_state.group
+        extra_state.group = "One to many #{association_name} association"
         create_to_many_adder
         create_to_many_clearer
         create_to_many_getter
         create_to_many_remover
         create_dataset_method
+        extra_state.group = original_group
       end
     end
   end

data/lib/yard-sequel/ast_node_hash.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
 module YardSequel
-  # Offers methods to convert an Abstract Syntax Tree to a Hash consisting
-  # of `YARD::Parser::Ruby::AstNode`s.
+  # Offers methods to convert an Abstract Syntax Tree of a Hash literal or named
+  # method parameters to a Hash consisting of `YARD::Parser::Ruby::AstNode`s.
   # @author Kai Moschcau
   module AstNodeHash
     class << self
+      # Creates a new Hash from the passed AstNode. This is the main method to
+      # use, to create a new Hash.
+      # @param (see .node_hash_from_node)
+      # @raise (see .check_ast)
+      # @return (see .node_hash_from_node)
       def from_ast(ast)
         check_ast ast
         node_hash_from_node ast
       end
 
+      # Checks the passed AstNode for validity. If the AstNode is valid, this
+      # method does not raise an error.
+      # @raise [TypeError, ArgumentError] If the AstNode is not valid.
+      # @param [YARD::Parser::Ruby::AstNode] ast The AstNode to check for
+      #   validity.
       def check_ast(ast)
         check_is_ast_node ast
         check_is_hash_or_list ast
@@ -22,12 +32,19 @@ module YardSequel
 
       private
 
+      # Checks if the given child AstNode has exactly two children.
+      # @raise [ArgumentError] If if does not have 2 children.
+      # @return [void]
       def check_assoc_child_has_two_children(child_ast)
         return if child_ast.children.size == 2
 
         raise(ArgumentError, 'each `:assoc` child must have two children')
       end
 
+      # Checks the children of the given AstNode. Mainly it first checks, if the
+      # AstNode has only `:assoc` type children and if each child has two
+      # further children.
+      # @return [void]
       def check_children(ast)
         check_has_only_assoc_children ast
         ast.children.each do |child_ast|
@@ -35,6 +52,9 @@ module YardSequel
         end
       end
 
+      # Checks if the children of the passed AstNode are all of type `:assoc`.
+      # @raise [ArgumentError] If there is at least one not of type `:assoc`.
+      # @return [void]
       def check_has_only_assoc_children(ast)
         return unless ast.children.any? { |child| child.type != :assoc }
 
@@ -42,12 +62,18 @@ module YardSequel
               'all children of the passed `ast` have to have the type `:assoc`')
       end
 
+      # Checks the children of a `:hash` type AstNode. If the AstNode has no
+      # children, this does nothing. Otherwise it runs {.check_children}.
+      # @return [void]
       def check_hash_children(ast)
         return if ast.children.empty?
 
         check_children ast
       end
 
+      # Checks, whether the passed Object is a `YARD::Parser::Ruby::AstNode`.
+      # @raise [TypeError] If the passed Object is not of the correct type.
+      # @return [void]
       def check_is_ast_node(ast)
         return if ast.is_a? YARD::Parser::Ruby::AstNode
 
@@ -55,6 +81,9 @@ module YardSequel
               'the passed `ast` has to be a `YARD::Parser::Ruby::AstNode`')
       end
 
+      # Checks, whether the passed AstNode is of Type `:hash` or `:list`.
+      # @raise [ArgumentError] If the passed AstNode is not of the correct type.
+      # @return [void]
       def check_is_hash_or_list(ast)
         return if %i[hash list].include? ast.type
 
@@ -62,6 +91,10 @@ module YardSequel
               "the passed `ast`'s type has to be `:hash` or `:list`")
       end
 
+      # Checks the children of a `:list` type AstNode. If the AstNode has no
+      # children, this raises an error. Otherwise it runs {.check_children}.
+      # @raise [ArgumentError] If the passed AstNode has no children.
+      # @return [void]
       def check_list_children(ast)
         if ast.children.empty?
           raise(ArgumentError,
@@ -70,6 +103,10 @@ module YardSequel
         check_children ast
       end
 
+      # Converts the passed AstNode to a Hash.
+      # @param [YARD::Parser::Ruby::AstNode] ast The AstNode to convert to a
+      #   Hash.
+      # @return [Hash<YARD::Parser::Ruby::AstNode>] the converted Hash.
       def node_hash_from_node(ast)
         hash = {}
         ast.children.each { |cn| hash[cn.children[0]] = cn.children[1] }

data/lib/yard-sequel/version.rb

@@ -7,11 +7,11 @@ module YardSequel
 
   # The minor version number.
   # Used for changes that are backwards compatible.
-  V_MINOR = 1
+  V_MINOR = 2
 
   # The build version number.
   # Used for internal changes.
-  V_BUILD = 1
+  V_BUILD = 0
 
   # The version of the Sequel models.
   VERSION = Gem::Version.new("#{V_MAJOR}.#{V_MINOR}.#{V_BUILD}")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-sequel
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Kai Moschcau
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-04 00:00:00.000000000 Z
+date: 2018-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: coveralls
@@ -122,6 +122,7 @@ extra_rdoc_files: []
 files:
 - ".yardopts"
 - lib/yard-sequel.rb
+- lib/yard-sequel/association_options.rb
 - lib/yard-sequel/associations.rb
 - lib/yard-sequel/associations/association_handler.rb
 - lib/yard-sequel/associations/many_to_one_handler.rb