yard 0.9.5 → 0.9.6

data/lib/yard/tags/tag.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Tags
     # Represents a metadata tag value (+@tag+). Tags can have any combination of
@@ -41,7 +42,10 @@ module YARD
       #                                for the tag
       # @param [String] name           optional key name which the tag refers to
       def initialize(tag_name, text, types = nil, name = nil)
-        @tag_name, @text, @name, @types = tag_name.to_s, text, name, (types ? [types].flatten.compact : nil)
+        @tag_name = tag_name.to_s
+        @text = text
+        @name = name
+        @types = (types ? [types].flatten.compact : nil)
       end
 
       # Convenience method to access the first type specified. This should mainly
@@ -52,6 +56,16 @@ module YARD
       def type
         types.first
       end
+
+      # Provides a plain English summary of the type specification, or nil
+      # if no types are provided or parseable.
+      #
+      # @return [String] a plain English description of the associated types
+      # @return [nil] if no types are provided or not parseable
+      def explain_types
+        return nil if !types || types.empty?
+        TypesExplainer.explain(*types)
+      end
     end
   end
-end
+end

data/lib/yard/tags/tag_format_error.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
 module YARD
   module Tags
-    class TagFormatError < Exception
+    class TagFormatError < RuntimeError
     end
   end
-end
+end

data/lib/yard/tags/types_explainer.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+require 'strscan'
+
+module YARD
+  module Tags
+    class TypesExplainer
+      # (see Tag#explain_types)
+      # @param types [Array<String>] a list of types to parse and summarize
+      def self.explain(*types)
+        explain!(*types)
+      rescue SyntaxError
+        nil
+      end
+
+      # (see explain)
+      # @raise [SyntaxError] if the types are not parseable
+      def self.explain!(*types)
+        Parser.parse(types.join(", ")).join("; ")
+      end
+
+      class << self
+        private :new
+      end
+
+      # @private
+      class Type
+        attr_accessor :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def to_s(singular = true)
+          if name[0, 1] == "#"
+            singular ? "an object that responds to #{name}" : "objects that respond to #{name}"
+          elsif name[0, 1] =~ /[A-Z]/
+            singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
+          else
+            name
+          end
+        end
+
+        private
+
+        def list_join(list)
+          index = 0
+          list.inject(String.new) do |acc, el|
+            acc << el.to_s
+            acc << ", " if index < list.size - 2
+            acc << " or " if index == list.size - 2
+            index += 1
+            acc
+          end
+        end
+      end
+
+      # @private
+      class CollectionType < Type
+        attr_accessor :types
+
+        def initialize(name, types)
+          @name = name
+          @types = types
+        end
+
+        def to_s(_singular = true)
+          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} of (" + list_join(types.map {|t| t.to_s(false) }) + ")"
+        end
+      end
+
+      # @private
+      class FixedCollectionType < CollectionType
+        def to_s(_singular = true)
+          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} containing (" + types.map(&:to_s).join(" followed by ") + ")"
+        end
+      end
+
+      # @private
+      class HashCollectionType < Type
+        attr_accessor :key_types, :value_types
+
+        def initialize(name, key_types, value_types)
+          @name = name
+          @key_types = key_types
+          @value_types = value_types
+        end
+
+        def to_s(_singular = true)
+          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with keys made of (" +
+            list_join(key_types.map {|t| t.to_s(false) }) +
+            ") and values of (" + list_join(value_types.map {|t| t.to_s(false) }) + ")"
+        end
+      end
+
+      # @private
+      class Parser
+        TOKENS = {
+          :collection_start => /</,
+          :collection_end => />/,
+          :fixed_collection_start => /\(/,
+          :fixed_collection_end => /\)/,
+          :type_name => /#\w+|((::)?\w+)+/,
+          :type_next => /[,;]/,
+          :whitespace => /\s+/,
+          :hash_collection_start => /\{/,
+          :hash_collection_next => /=>/,
+          :hash_collection_end => /\}/,
+          :parse_end => nil
+        }
+
+        def self.parse(string)
+          new(string).parse
+        end
+
+        def initialize(string)
+          @scanner = StringScanner.new(string)
+        end
+
+        def parse
+          types = []
+          type = nil
+          name = nil
+          loop do
+            found = false
+            TOKENS.each do |token_type, match|
+              # TODO: cleanup this code.
+              # rubocop:disable Lint/AssignmentInCondition
+              next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
+              found = true
+              case token_type
+              when :type_name
+                raise SyntaxError, "expecting END, got name '#{token}'" if name
+                name = token
+              when :type_next
+                raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
+                type = Type.new(name) unless type
+                types << type
+                type = nil
+                name = nil
+              when :fixed_collection_start, :collection_start
+                name ||= "Array"
+                klass = token_type == :collection_start ? CollectionType : FixedCollectionType
+                type = klass.new(name, parse)
+              when :hash_collection_start
+                name ||= "Hash"
+                type = HashCollectionType.new(name, parse, parse)
+              when :hash_collection_next, :hash_collection_end, :fixed_collection_end, :collection_end, :parse_end
+                raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
+                type = Type.new(name) unless type
+                types << type
+                return types
+              end
+            end
+            raise SyntaxError, "invalid character at #{@scanner.peek(1)}" unless found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/templates/engine.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'ostruct'
 
 module YARD
@@ -53,7 +54,7 @@ module YARD
           full_paths ||= [path]
           full_paths = [full_paths] unless full_paths.is_a?(Array)
           name = template_module_name(full_paths.first)
-          begin; return const_get(name); rescue NameError; end
+          begin; return const_get(name); rescue NameError; nil end
 
           mod = const_set(name, Module.new)
           mod.send(:include, Template)
@@ -111,7 +112,7 @@ module YARD
         # @yield a block whose result will be serialize
         # @yieldreturn [String] the contents to serialize
         # @see Serializers::Base
-        def with_serializer(object, serializer, &block)
+        def with_serializer(object, serializer)
           output = nil
           filename = serializer.serialized_path(object)
           if serializer.respond_to?(:basepath)

data/lib/yard/templates/erb_cache.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
 module YARD
   module Templates
     # @since 0.5.4
     module ErbCache
-      def self.method_for(filename, &block)
+      def self.method_for(filename)
         @methods ||= {}
         return @methods[filename] if @methods[filename]
         @methods[filename] = name = "_erb_cache_#{@methods.size}"
@@ -14,7 +15,7 @@ module YARD
       end
 
       def self.clear!
-        return unless @methods
+        return unless defined?(@methods) && @methods
         @methods.clear
       end
     end

data/lib/yard/templates/helpers/base_helper.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD::Templates::Helpers
   # The base helper module included in all templates.
   module BaseHelper
@@ -7,7 +8,7 @@ module YARD::Templates::Helpers
     #   page. Might not be the current {#object} when inside sub-templates.
     attr_reader :owner
     undef owner
-    def owner; @owner || object.namespace end
+    def owner; (defined?(@owner) && @owner) || object.namespace end
 
     # @group Managing Global Template State
 
@@ -55,7 +56,7 @@ module YARD::Templates::Helpers
       if args.first.is_a?(String)
         case args.first
         when %r{://}, /^mailto:/
-          link_url(args[0], args[1], {:target => '_parent'}.merge(args[2]||{}))
+          link_url(args[0], args[1], {:target => '_parent'}.merge(args[2] || {}))
         when /^include:file:(\S+)/
           file = $1
           relpath = File.relative_path(Dir.pwd, File.expand_path(file))
@@ -70,7 +71,8 @@ module YARD::Templates::Helpers
           end
         when /^include:(\S+)/
           path = $1
-          if obj = YARD::Registry.resolve(object.namespace, path)
+          obj = YARD::Registry.resolve(object.namespace, path)
+          if obj
             link_include_object(obj)
           else
             log.warn "Cannot find object at `#{path}' for inclusion"
@@ -78,7 +80,8 @@ module YARD::Templates::Helpers
           end
         when /^render:(\S+)/
           path = $1
-          if obj = YARD::Registry.resolve(object, path)
+          obj = YARD::Registry.resolve(object, path)
+          if obj
             opts = options.dup
             opts.delete(:serializer)
             obj.format(opts)
@@ -135,7 +138,7 @@ module YARD::Templates::Helpers
     # @param [String] title the optional title to display the link as
     # @param [Hash] params optional parameters for the link
     # @return [String] the linked URL
-    def link_url(url, title = nil, params = nil)
+    def link_url(url, title = nil, params = nil) # rubocop:disable Lint/UnusedMethodArgument
       url
     end
 
@@ -146,7 +149,7 @@ module YARD::Templates::Helpers
     # @param [String] anchor optional anchor
     # @return [String] the link to the file
     # @since 0.5.5
-    def link_file(filename, title = nil, anchor = nil)
+    def link_file(filename, title = nil, anchor = nil) # rubocop:disable Lint/UnusedMethodArgument
       return filename.filename if CodeObjects::ExtraFileObject === filename
       filename
     end

data/lib/yard/templates/helpers/filter_helper.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Templates::Helpers
     # Helpers for various object types

data/lib/yard/templates/helpers/html_helper.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'cgi'
 
 module YARD
@@ -7,6 +8,9 @@ module YARD
       include MarkupHelper
       include HtmlSyntaxHighlightHelper
 
+      # @private
+      URLMATCH = /[^\w\s~!\*'\(\):;@&=\$,\[\]<>-]/
+
       # @group Escaping Template Data
 
       # Escapes HTML entities
@@ -22,9 +26,23 @@ module YARD
       # @param [String] text the URL
       # @return [String] the escaped URL
       def urlencode(text)
-        CGI.escape(text.to_s)
+        text = text.dup
+        enc = nil
+        if text.respond_to?(:force_encoding)
+          enc = text.encoding
+          text = text.force_encoding('binary')
+        end
+
+        text = text.gsub(/%[a-z0-9]{2}|#{URLMATCH}/i) do
+          $&.size > 1 ? $& : "%" + $&.ord.to_s(16).upcase
+        end.tr(' ', '+')
+
+        text = text.force_encoding(enc) if enc
+        text
       end
 
+      module_function :urlencode
+
       # @group Converting Markup to HTML
 
       # Turns text into HTML using +markup+ style formatting.
@@ -38,7 +56,7 @@ module YARD
         return text unless respond_to?(markup_meth)
         return "" unless text
         return text unless markup
-        html = send(markup_meth, text)
+        html = send(markup_meth, text).dup
         if html.respond_to?(:encode)
           html = html.force_encoding(text.encoding) # for libs that mess with encoding
           html = html.encode(:invalid => :replace, :replace => '?')
@@ -188,8 +206,13 @@ module YARD
       # @return [String] HTML with linkified references
       def resolve_links(text)
         code_tags = 0
-        text.gsub(/<(\/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+<\/|$)/m) do |str|
-          closed, tag, escape, name, title, match = $1, $2, $3, $4, $5, $&
+        text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+</|$)}m) do |str|
+          closed = $1
+          tag = $2
+          escape = $3
+          name = $4
+          title = $5
+          match = $&
           if tag
             code_tags += (closed ? -1 : 1)
             next str
@@ -198,10 +221,11 @@ module YARD
 
           next(match[1..-1]) if escape
 
-          next(match) if name[0,1] == '|'
+          next(match) if name[0, 1] == '|'
 
-          if name == '<a' && title =~ /href=["'](.+?)["'].*>.*<\/a>\s*(.*)\Z/
-            name, title = $1, $2
+          if name == '<a' && title =~ %r{href=["'](.+?)["'].*>.*</a>\s*(.*)\Z}
+            name = $1
+            title = $2
             title = nil if title.empty?
           end
 
@@ -211,12 +235,12 @@ module YARD
             object
           else
             link = linkify(name, title)
-            if (link == name || link == title) && (name+' '+link !~ /\A<a\s.*>/)
+            if (link == name || link == title) && (name + ' ' + link !~ /\A<a\s.*>/)
               match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text)
-              file = (@file ? @file.filename : object.file) || '(unknown)'
-              line = (@file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0)
-              log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".")
-              log.warn((match[1] ? '...' : '') + match[2].gsub("\n","") + (match[3] ? '...' : '')) if match
+              file = (defined?(@file) && @file ? @file.filename : object.file) || '(unknown)'
+              line = (defined?(@file) && @file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0)
+              log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".") +
+                       "\n\t" + (match[1] ? '...' : '') + match[2].delete("\n") + (match[3] ? '...' : '') if match
             end
 
             link
@@ -252,7 +276,7 @@ module YARD
 
       # Inserts an include link while respecting inlining
       def insert_include(text, markup = options.markup)
-        htmlify(text, markup).gsub(/\A\s*<p>|<\/p>\s*\Z/, '')
+        htmlify(text, markup).gsub(%r{\A\s*<p>|</p>\s*\Z}, '')
       end
 
       # (see BaseHelper#link_object)
@@ -286,12 +310,12 @@ module YARD
       # (see BaseHelper#link_url)
       def link_url(url, title = nil, params = {})
         title ||= url
-        title.gsub!(/[\r\n]/, ' ')
+        title = title.gsub(/[\r\n]/, ' ')
         params = SymbolHash.new(false).update(
           :href => url,
-          :title  => h(title)
+          :title => h(title)
         ).update(params)
-        params[:target] ||= '_parent' if url =~ /^(\w+):\/\//
+        params[:target] ||= '_parent' if url =~ %r{^(\w+)://}
         "<a #{tag_attrs(params)}>#{title}</a>".gsub(/[\r\n]/, ' ')
       end
 
@@ -327,7 +351,8 @@ module YARD
 
         if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
           # If the obj is not a namespace obj make it the anchor.
-          anchor, obj = obj, obj.namespace
+          anchor = obj
+          obj = obj.namespace
         end
 
         objpath = serializer.serialized_path(obj)
@@ -337,7 +362,7 @@ module YARD
         if relative
           fromobj = object
           if object.is_a?(CodeObjects::Base) &&
-              !object.is_a?(CodeObjects::NamespaceObject)
+             !object.is_a?(CodeObjects::NamespaceObject)
             fromobj = owner
           end
 
@@ -350,6 +375,9 @@ module YARD
         link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
       end
 
+      alias mtime_url url_for
+      def mtime(_file) nil end
+
       # Returns the URL for a specific file
       #
       # @param [String, CodeObjects::ExtraFileObject] filename the filename to link to
@@ -362,11 +390,8 @@ module YARD
           fromobj = fromobj.namespace
         end
         from = serializer.serialized_path(fromobj)
-        if filename == options.readme
-          path = 'index.html'
-        else
-          path = serializer.serialized_path(filename)
-        end
+        path = filename == options.readme ?
+          'index.html' : serializer.serialized_path(filename)
         link = File.relative_path(from, path)
         link += (anchor ? '#' + urlencode(anchor) : '')
         link
@@ -492,7 +517,8 @@ module YARD
         extras = []
         extras_text = ''
         if show_extras
-          if rw = meth.attr_info
+          rw = meth.attr_info
+          if rw
             attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
             attname = attname.size == 1 ? attname.join('') + 'only' : nil
             extras << attname if attname
@@ -526,16 +552,18 @@ module YARD
       # @since 0.5.4
       def charset
         has_encoding = defined?(::Encoding)
-        if @file && has_encoding
+        if defined?(@file) && @file && has_encoding
           lang = @file.contents.encoding.to_s
         else
-          return 'utf-8' unless has_encoding || lang = ENV['LANG']
-          if has_encoding
-            lang = ::Encoding.default_external.name.downcase
-          else
-            lang = lang.downcase.split('.').last
-          end
+          return 'utf-8' unless has_encoding || ENV['LANG']
+          lang =
+            if has_encoding
+              ::Encoding.default_external.name.downcase
+            else
+              ENV['LANG'].downcase.split('.').last
+            end
         end
+
         case lang
         when "ascii-8bit", "us-ascii", "ascii-7bit"; 'iso-8859-1'
         when "utf8"; 'utf-8'
@@ -552,7 +580,7 @@ module YARD
       # @param [Hash{String => String}] opts the tag options
       # @return [String] the tag attributes of an HTML tag
       def tag_attrs(opts = {})
-        opts.sort_by {|k, v| k.to_s }.map {|k,v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
+        opts.sort_by {|k, _v| k.to_s }.map {|k, v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
       end
 
       # Converts a {CodeObjects::MethodObject} into an overload object
@@ -575,7 +603,8 @@ module YARD
       def parse_lang_for_codeblock(source)
         type = nil
         if source =~ /\A(?:[ \t]*\r?\n)?[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/
-          type, source = $1, $'
+          type = $1
+          source = $'
         end
 
         [type, source]
@@ -588,20 +617,19 @@ module YARD
       # @return [String] highlighted html
       # @see #html_syntax_highlight
       def parse_codeblocks(html)
-        html.gsub(/<pre\s*(?:lang="(.+?)")?>(?:\s*<code\s*(?:class="(.+?)")?\s*>)?(.+?)(?:<\/code>\s*)?<\/pre>/m) do
+        html.gsub(%r{<pre\s*(?:lang="(.+?)")?>(?:\s*<code\s*(?:class="(.+?)")?\s*>)?(.+?)(?:</code>\s*)?</pre>}m) do
           string = $3
           # handle !!!LANG prefix to send to html_syntax_highlight_LANG
-          language, _ = parse_lang_for_codeblock(string)
+          language, = parse_lang_for_codeblock(string)
           language ||= $1 || $2 || object.source_type
 
           if options.highlight
             string = html_syntax_highlight(CGI.unescapeHTML(string), language)
           end
           classes = ['code', language].compact.join(' ')
-          %Q{<pre class="#{classes}"><code class="#{language}">#{string}</code></pre>}
+          %(<pre class="#{classes}"><code class="#{language}">#{string}</code></pre>)
         end
       end
     end
   end
 end
-