deg-yard 0.8.7.1

data/lib/yard/templates/helpers/markup/rdoc_markup.rb

@@ -0,0 +1,106 @@
+require 'thread'
+
+module YARD
+  module Templates
+    module Helpers
+      module Markup
+        begin require 'rdoc'; rescue LoadError; end
+        begin
+          require 'rdoc/markup'
+          require 'rdoc/markup/to_html'
+          class RDocMarkup; MARKUP = RDoc::Markup end
+          class RDocMarkupToHtml < RDoc::Markup::ToHtml
+            if defined?(RDoc::VERSION) && RDoc::VERSION >= '4.0.0' &&
+               defined?(RDoc::Options)
+            then
+              def initialize
+                options = RDoc::Options.new
+                options.pipe = true
+                super(options)
+              end
+            end
+          end
+        rescue LoadError
+          begin
+            require 'rdoc/markup/simple_markup'
+            require 'rdoc/markup/simple_markup/to_html'
+            class RDocMarkup; MARKUP = SM::SimpleMarkup end
+            class RDocMarkupToHtml < SM::ToHtml; end
+          rescue LoadError
+            raise NameError, "could not load RDocMarkup (rdoc is not installed)"
+          end
+        end
+
+        class RDocMarkup
+          attr_accessor :from_path
+
+          @@formatter = nil
+          @@markup = nil
+          @@mutex = nil
+
+          def initialize(text)
+            @text = text
+
+            @@formatter ||= RDocMarkupToHtml.new
+            @@markup ||= MARKUP.new
+            @@mutex ||= Mutex.new
+          end
+
+          def to_html
+            html = nil
+            @@mutex.synchronize do
+              @@formatter.from_path = from_path
+              html = @@markup.convert(@text, @@formatter)
+            end
+            html = fix_dash_dash(html)
+            html = fix_typewriter(html)
+            html
+          end
+
+          private
+
+          # Fixes RDoc behaviour with ++ only supporting alphanumeric text.
+          #
+          # @todo Refactor into own SimpleMarkup subclass
+          def fix_typewriter(text)
+            code_tags = 0
+            text.gsub(/<(\/)?(pre|code|tt)|(\s|^|>)\+(?! )([^\n\+]{1,900})(?! )\+/) do |str|
+              closed, tag, first_text, type_text, pre_text, no_match = $1, $2, $3, $4, $`, $&
+
+              if tag
+                code_tags += (closed ? -1 : 1)
+                next str
+              end
+              next str unless code_tags == 0
+              first_text + '<tt>' + type_text + '</tt>'
+            end
+          end
+
+          # Don't allow -- to turn into &#8212; element. The chances of this being
+          # some --option is far more likely than the typographical meaning.
+          #
+          # @todo Refactor into own SimpleMarkup subclass
+          def fix_dash_dash(text)
+            text.gsub(/&#8212;(?=\S)/, '--')
+          end
+        end
+
+        class RDocMarkupToHtml
+          attr_accessor :from_path
+
+          # Disable auto-link of URLs
+          def handle_special_HYPERLINK(special)
+            @hyperlink ? special.text : super
+          end
+
+          def accept_paragraph(*args)
+            par = args.last
+            text = par.respond_to?(:txt) ? par.txt : par.text
+            @hyperlink = !!(text =~ /\{(https?:|mailto:|link:|www\.)/)
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+require 'rubygems'
+
+module YARD
+  module Templates::Helpers
+    # Helper methods for loading and managing markup types.
+    module MarkupHelper
+      class << self
+        # Clears the markup provider cache information. Mainly used for testing.
+        # @return [void]
+        def clear_markup_cache
+          self.markup_cache = {}
+        end
+
+        # @return [Hash{Symbol=>{(:provider,:class)=>Object}}] the cached markup providers
+        # @private
+        # @since 0.6.4
+        attr_accessor :markup_cache
+      end
+
+      MarkupHelper.clear_markup_cache
+
+      # The default list of markup providers for each markup type
+      MARKUP_PROVIDERS = {
+        :markdown => [
+          {:lib => :redcarpet, :const => 'RedcarpetCompat'},
+          {:lib => :rdiscount, :const => 'RDiscount'},
+          {:lib => :kramdown, :const => 'Kramdown::Document'},
+          {:lib => :bluecloth, :const => 'BlueCloth'},
+          {:lib => :maruku, :const => 'Maruku'},
+          {:lib => :'rpeg-markdown', :const => 'PEGMarkdown'},
+          {:lib => :rdoc, :const => 'YARD::Templates::Helpers::Markup::RDocMarkdown'},
+        ],
+        :textile => [
+          {:lib => :redcloth, :const => 'RedCloth'},
+        ],
+        :textile_strict => [
+          {:lib => :redcloth, :const => 'RedCloth'},
+        ],
+        :rdoc => [
+          {:lib => nil, :const => 'YARD::Templates::Helpers::Markup::RDocMarkup'},
+        ],
+        :asciidoc => [
+          {:lib => :asciidoctor, :const => 'Asciidoctor'}
+        ],
+        :ruby => [],
+        :text => [],
+        :pre  => [],
+        :html => [],
+        :none => [],
+      }
+
+      # Returns a list of extensions for various markup types. To register
+      # extensions for a type, add them to the array of extensions for the
+      # type.
+      # @since 0.6.0
+      MARKUP_EXTENSIONS = {
+        :html => ['htm', 'html', 'shtml'],
+        :text => ['txt'],
+        :textile => ['textile', 'txtile'],
+        :asciidoc => ['asciidoc'],
+        :markdown => ['markdown', 'md', 'mdown', 'mkd'],
+        :rdoc => ['rdoc'],
+        :ruby => ['rb', 'ru']
+      }
+
+      # Contains the Regexp object that matches the shebang line of extra
+      # files to detect the markup type.
+      MARKUP_FILE_SHEBANG = /\A#!(\S+)\s*$/
+
+      # Attempts to load the first valid markup provider in {MARKUP_PROVIDERS}.
+      # If a provider is specified, immediately try to load it.
+      #
+      # On success this sets `@markup_provider` and `@markup_class` to
+      # the provider name and library constant class/module respectively for
+      # the loaded provider.
+      #
+      # On failure this method will inform the user that no provider could be
+      # found and exit the program.
+      #
+      # @return [Boolean] whether the markup provider was successfully loaded.
+      def load_markup_provider(type = options.markup)
+        return true if MarkupHelper.markup_cache[type]
+        MarkupHelper.markup_cache[type] ||= {}
+
+        providers = MARKUP_PROVIDERS[type.to_sym]
+        return true if providers && providers.empty?
+        if providers && options.markup_provider
+          providers = providers.select {|p| p[:lib] == options.markup_provider }
+        end
+
+        if providers == nil || providers.empty?
+          log.error "Invalid markup type '#{type}' or markup provider " +
+            "(#{options.markup_provider}) is not registered."
+          return false
+        end
+
+        # Search for provider, return the library class name as const if found
+        providers.each do |provider|
+          begin require provider[:lib].to_s; rescue LoadError; next end if provider[:lib]
+          begin klass = eval("::" + provider[:const]); rescue NameError; next end
+          MarkupHelper.markup_cache[type][:provider] = provider[:lib] # Cache the provider
+          MarkupHelper.markup_cache[type][:class] = klass
+          return true
+        end
+
+        # Show error message telling user to install first potential provider
+        name, lib = *[providers.first[:const], providers.first[:lib] || type]
+        log.error "Missing '#{lib}' gem for #{type.to_s.capitalize} formatting. Install it with `gem install #{lib}`"
+        false
+      end
+
+      # Checks for a shebang or looks at the file extension to determine
+      # the markup type for the file contents. File extensions are registered
+      # for a markup type in {MARKUP_EXTENSIONS}.
+      #
+      # A shebang should be on the first line of a file and be in the form:
+      #
+      #   #!markup_type
+      #
+      # Standard markup types are text, html, rdoc, markdown, textile
+      #
+      # @param [String] contents Unused. Was necessary prior to 0.7.0.
+      #   Newer versions of YARD use {CodeObjects::ExtraFileObject#contents}
+      # @return [Symbol] the markup type recognized for the file
+      # @see MARKUP_EXTENSIONS
+      # @since 0.6.0
+      def markup_for_file(contents, filename)
+        if contents && contents =~ MARKUP_FILE_SHEBANG # Shebang support
+          return $1.to_sym
+        end
+
+        ext = (File.extname(filename)[1..-1] || '').downcase
+        MARKUP_EXTENSIONS.each do |type, exts|
+          return type if exts.include?(ext)
+        end
+        options.markup
+      end
+
+      # Strips any shebang lines on the file contents that pertain to
+      # markup or preprocessing data.
+      #
+      # @deprecated Use {CodeObjects::ExtraFileObject#contents} instead
+      # @return [String] the file contents minus any preprocessing tags
+      # @since 0.6.0
+      def markup_file_contents(contents)
+        contents =~ MARKUP_FILE_SHEBANG ? $' : contents
+      end
+
+      # Gets the markup provider class/module constant for a markup type
+      # Call {#load_markup_provider} before using this method.
+      #
+      # @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
+      # @return [Class] the markup class
+      def markup_class(type = options.markup)
+        load_markup_provider(type)
+        MarkupHelper.markup_cache[type][:class]
+      end
+
+      # Gets the markup provider name for a markup type
+      # Call {#load_markup_provider} before using this method.
+      #
+      # @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
+      # @return [Symbol] the markup provider name (usually the gem name of the library)
+      def markup_provider(type = options.markup)
+        MarkupHelper.markup_cache[type][:provider]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module YARD
+  module Templates::Helpers
+    # Helper methods for method objects.
+    module MethodHelper
+      # @return [String] formatted arguments for a method
+      def format_args(object)
+        return if object.parameters.nil?
+        params = object.parameters
+        if object.has_tag?(:yield) || object.has_tag?(:yieldparam)
+          params.reject! do |param|
+            param[0].to_s[0,1] == "&" &&
+              !object.tags(:param).any? {|t| t.name == param[0][1..-1] }
+          end
+        end
+
+        unless params.empty?
+          args = params.map do |n, v|
+            v ? "#{n}#{n[-1,1] == ':' ? '' : ' ='} #{v}" : n.to_s
+          end.join(", ")
+          h("(#{args})")
+        else
+          ""
+        end
+      end
+
+      # @return [String] formatted and linked return types for a method
+      def format_return_types(object)
+        return unless object.has_tag?(:return) && object.tag(:return).types
+        return if object.tag(:return).types.empty?
+        format_types [object.tag(:return).types.first], false
+      end
+
+      # @return [String] formatted block if one exists
+      def format_block(object)
+        if object.has_tag?(:yield) && object.tag(:yield).types
+          params = object.tag(:yield).types
+        elsif object.has_tag?(:yieldparam)
+          params = object.tags(:yieldparam).map {|t| t.name }
+        elsif object.has_tag?(:yield)
+          return "{ ... }"
+        else
+          params = nil
+        end
+
+        params ? h("{|" + params.join(", ") + "| ... }") : ""
+      end
+
+      # @return [String] formats line numbers for source code of an object
+      def format_lines(object)
+        return "" if object.source.nil? || object.line.nil?
+        i = -1
+        object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
+      end
+
+      # @return [String] formats source of an object
+      def format_code(object, show_lines = false)
+        i = -1
+        lines = object.source.split(/\n/)
+        longestline = (object.line + lines.size).to_s.length
+        lines.map do |line|
+          lineno = object.line + (i += 1)
+          (" " * (longestline - lineno.to_s.length)) + lineno.to_s + "    " + line
+        end.join("\n")
+      end
+
+      # @return [String] formats source code of a constant value
+      def format_constant(value)
+        sp = value.split("\n").last[/^(\s+)/, 1]
+        num = sp ? sp.size : 0
+        html_syntax_highlight value.gsub(/^\s{#{num}}/, '')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module YARD
+  module Templates
+    module Helpers
+      # Helper methods for managing module objects.
+      module ModuleHelper
+        # Prunes the method listing by running the verifier and removing attributes/aliases
+        # @param [Array<CodeObjects::Base>] list a list of methods
+        # @param [Boolean] hide_attributes whether to prune attribute methods from the list
+        # @return [Array<CodeObjects::Base>] a pruned list of methods
+        def prune_method_listing(list, hide_attributes = true)
+          list = run_verifier(list)
+          list = list.reject {|o| o.is_alias? unless CodeObjects::Proxy === o.namespace }
+          list = list.reject {|o| o.is_attribute? unless CodeObjects::Proxy === o.namespace } if hide_attributes
+          list
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+module YARD
+  module Templates
+    module Helpers
+      # Helper methods for text template formats.
+      module TextHelper
+        # @return [String] escapes text
+        def h(text)
+          out = ""
+          text = text.split(/\n/)
+          text.each_with_index do |line, i|
+            out <<
+            case line
+            when /^\s*$/; "\n\n"
+            when /^\s+\S/, /^=/; line + "\n"
+            else; line + (text[i + 1] =~ /^\s+\S/ ? "\n" : " ")
+            end
+          end
+          out
+        end
+
+        # @return [String] wraps text at +col+ columns.
+        def wrap(text, col = 72)
+          text.gsub(/(.{1,#{col}})( +|$\n?)|(.{1,#{col}})/, "\\1\\3\n")
+        end
+
+        # @return [String] indents +text+ by +len+ characters.
+        def indent(text, len = 4)
+          text.gsub(/^/, ' ' * len)
+        end
+
+        # @return [String] aligns a title to the right
+        def title_align_right(text, col = 72)
+          align_right(text, '-', col)
+        end
+
+        # @return [String] aligns text to the right
+        def align_right(text, spacer = ' ', col = 72)
+          text = text[0, col - 4] + '...' if (col - 1 - text.length) < 0
+          spacer * (col - 1 - text.length) + " " + text
+        end
+
+        # @return [String] returns a horizontal rule for output
+        def hr(col = 72, sep = "-")
+          sep * col
+        end
+
+        # @return [String] the formatted signature for a method
+        def signature(meth)
+          # use first overload tag if it has a return type and method itself does not
+          if !meth.tag(:return) && meth.tag(:overload) && meth.tag(:overload).tag(:return)
+            meth = meth.tag(:overload)
+          end
+
+          type = options.default_return || ""
+          rmeth = meth
+          if !rmeth.has_tag?(:return) && rmeth.respond_to?(:object)
+            rmeth = meth.object
+          end
+          if rmeth.tag(:return) && rmeth.tag(:return).types
+            types = rmeth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
+            first = types.first
+            if types.size == 2 && types.last == 'nil'
+              type = first + '?'
+            elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
+              type = first + '+'
+            elsif types.size > 2
+              type = [first, '...'].join(', ')
+            elsif types == ['void'] && options.hide_void_return
+              type = ""
+            else
+              type = types.join(", ")
+            end
+          end
+          type = "(#{type})" if type.include?(',')
+          type = " -> #{type} " unless type.empty?
+          scope = meth.scope == :class ? "#{meth.namespace.name}." : "#{meth.namespace.name.to_s.downcase}."
+          name = meth.name
+          blk = format_block(meth)
+          args = format_args(meth)
+          extras = []
+          extras_text = ''
+          if rw = meth.namespace.attributes[meth.scope][meth.name]
+            attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
+            attname = attname.size == 1 ? attname.join('') + 'only' : nil
+            extras << attname if attname
+          end
+          extras << meth.visibility if meth.visibility != :public
+          extras_text = '(' + extras.join(", ") + ')' unless extras.empty?
+          title = "%s%s%s %s%s%s" % [scope, name, args, blk, type, extras_text]
+          title.gsub(/\s+/, ' ')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module YARD
+  module Templates::Helpers
+    # Helpers for UML template format
+    module UMLHelper
+      # Official UML visibility prefix syntax for an object given its visibility
+      # @param [CodeObjects::Base] object the object to retrieve visibility for
+      # @return [String] the UML visibility prefix
+      def uml_visibility(object)
+        case object.visibility
+        when :public;    '+'
+        when :protected; '#'
+        when :private;   '-'
+        end
+      end
+
+      # Formats the path of an object for Graphviz syntax
+      # @param [CodeObjects::Base] object an object to format the path of
+      # @return [String] the encoded path
+      def format_path(object)
+        object.path.gsub('::', '_')
+      end
+
+      # Encodes text in escaped Graphviz syntax
+      # @param [String] text text to encode
+      # @return [String] the encoded text
+      def h(text)
+        text.to_s.gsub(/(\W)/, '\\\\\1')
+      end
+
+      # Tidies data by formatting and indenting text
+      # @param [String] data pre-formatted text
+      # @return [String] tidied text.
+      def tidy(data)
+        indent = 0
+        data.split(/\n/).map do |line|
+          line.gsub!(/^\s*/, '')
+          next if line.empty?
+          indent -= 1 if line =~ /^\s*\}\s*$/
+          line = (' ' * (indent * 2)) + line
+          indent += 1 if line =~ /\{\s*$/
+          line
+        end.compact.join("\n") + "\n"
+      end
+    end
+  end
+end

data/lib/yard/templates/section.rb

@@ -0,0 +1,106 @@
+module YARD
+  module Templates
+    # Abstracts the structure for a section and its subsections into an ordered
+    # list of sections and subsections.
+    # @since 0.6.0
+    class Section < Array
+      attr_accessor :name
+
+      def initialize(name, *args)
+        self.name = name
+        replace(parse_sections(args))
+      end
+
+      def dup
+        obj = super
+        obj.name = name
+        obj
+      end
+
+      def [](*args)
+        if args.first.is_a?(Range) || args.size > 1
+          obj = super(*args)
+          obj.name = name
+          return obj
+        elsif args.first.is_a?(Integer)
+          return super(*args)
+        end
+        find {|o| o.name == args.first }
+      end
+
+      def eql?(other)
+        super(other) && name == other.name
+      end
+
+      def ==(other)
+        case other
+        when Section
+          eql?(other)
+        when Array
+          to_a == other
+        else
+          name == other
+        end
+      end
+
+      def push(*args)
+        super(*parse_sections(args))
+      end
+      alias << push
+
+      def unshift(*args)
+        super(*parse_sections(args))
+      end
+
+      def inspect
+        n = name.respond_to?(:path) ? "T('#{name.path}')" : name.inspect
+        subsects = empty? ? "" : ", subsections=#{super}"
+        "Section(#{n}#{subsects})"
+      end
+
+      def place(*args)
+        super(*parse_sections(args))
+      end
+
+      def to_a
+        list = [name]
+        unless empty?
+          subsects = []
+          each {|s| subsects += s.to_a }
+          list << subsects
+        end
+        list
+      end
+
+      def any(item)
+        find do |section|
+          return section if section == item
+          return section.any(item) unless section.empty?
+        end
+        nil
+      end
+
+      private
+
+      def parse_sections(args)
+        if args.size == 1 && args.first.is_a?(Array) && !args.first.is_a?(Section)
+          args = args.first
+        end
+        sections = []
+        args.each_with_index do |name, index|
+          case name
+          when Section; sections << name
+          when Array;   next
+          else
+            subsections = args[index + 1].is_a?(Array) ? args[index + 1] : []
+            if subsections.is_a?(Section)
+              subsections = []
+            end
+            sections << Section.new(name, subsections)
+          end
+        end
+        sections
+      end
+    end
+  end
+end