module YARD

Backward compatability for gem specification lookup @see Gem::SourceIndex

Gem::YARDoc provides methods to generate YARDoc and yri data for installed gems upon gem installation.

This file is automatically required by RubyGems 1.9 and newer.

Constants

CONFIG_DIR

@deprecated Use {Config::CONFIG_DIR}

ROOT

The root path for YARD source libraries

TEMPLATE_ROOT

The root path for YARD builtin templates

VERSION

Public Class Methods

load_plugins() click to toggle source

(see YARD::Config.load_plugins) @deprecated Use {Config.load_plugins}

# File lib/yard.rb, line 30
def self.load_plugins; YARD::Config.load_plugins end
parse(*args) click to toggle source

An alias to {Parser::SourceParser}'s parsing method

@example Parse a glob of files

YARD.parse('lib   /*.rb')

@see YARD::Parser::SourceParser.parse

# File lib/yard.rb, line 19
def self.parse(*args) Parser::SourceParser.parse(*args) end
parse_string(*args) click to toggle source

An alias to {Parser::SourceParser}'s parsing method

@example Parse a string of input

YARD.parse_string('class Foo; end')

@see YARD::Parser::SourceParser.parse_string

# File lib/yard.rb, line 26
def self.parse_string(*args) Parser::SourceParser.parse_string(*args) end
ruby18?() click to toggle source

@return [Boolean] whether YARD is being run in Ruby 1.8 mode

# File lib/yard.rb, line 43
def self.ruby18?; !ruby19? end
ruby19?() click to toggle source

@return [Boolean] whether YARD is being run in Ruby 1.9 mode

# File lib/yard.rb, line 46
def self.ruby19?; @ruby19 ||= (RUBY_VERSION >= "1.9.1") end
ruby2?() click to toggle source

@return [Boolean] whether YARD is being run in Ruby 2.0

# File lib/yard.rb, line 49
def self.ruby2?; @ruby2 ||= (RUBY_VERSION >= '2.0.0') end
windows?() click to toggle source

@return [Boolean] whether YARD is being run inside of Windows

# File lib/yard.rb, line 33
def self.windows?
  return @windows if defined? @windows
  require 'rbconfig'
  @windows =
    ::RbConfig::CONFIG['host_os'] =~ /mingw|win32|cygwin/ ? true : false
ensure
  @windows ||= false
end

Public Instance Methods

anchor_for(object) click to toggle source

@param [CodeObjects::Base] object the object to get an anchor for @return [String] the anchor for a specific object

# File lib/yard/templates/helpers/html_helper.rb, line 325
def anchor_for(object)
  case object
  when CodeObjects::MethodObject
    "#{object.name}-#{object.scope}_#{object.type}"
  when CodeObjects::ClassVariableObject
    "#{object.name.to_s.gsub('@@', '')}-#{object.type}"
  when CodeObjects::Base
    "#{object.name}-#{object.type}"
  when CodeObjects::Proxy
    object.path
  else
    object.to_s
  end
end
charset() click to toggle source

Returns the current character set. The default value can be overridden by setting the LANG environment variable or by overriding this method. In Ruby 1.9 you can also modify this value by setting Encoding.default_external.

@return [String] the current character set @since 0.5.4

# File lib/yard/templates/helpers/html_helper.rb, line 552
def charset
  has_encoding = defined?(::Encoding)
  if defined?(@file) && @file && has_encoding
    lang = @file.contents.encoding.to_s
  else
    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'
  else; lang
  end
end
format_object_name_list(objects) click to toggle source

Formats a list of objects and links them @return [String] a formatted list of objects

# File lib/yard/templates/helpers/html_helper.rb, line 436
def format_object_name_list(objects)
  objects.sort_by {|o| o.name.to_s.downcase }.map do |o|
    "<span class='name'>" + linkify(o, o.name) + "</span>"
  end.join(", ")
end
format_types(typelist, brackets = true) click to toggle source

Formats a list of types from a tag.

@param [Array<String>, FalseClass] typelist

the list of types to be formatted.

@param [Boolean] brackets omits the surrounding

brackets if +brackets+ is set to +false+.

@return [String] the list of types formatted

as [Type1, Type2, ...] with the types linked
to their respective descriptions.
# File lib/yard/templates/helpers/html_helper.rb, line 454
def format_types(typelist, brackets = true)
  return unless typelist.is_a?(Array)
  list = typelist.map do |type|
    type = type.gsub(/([<>])/) { h($1) }
    type = type.gsub(/([\w:]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) }
    "<tt>" + type + "</tt>"
  end
  list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
end
insert_include(text, markup = options.markup) click to toggle source

Inserts an include link while respecting inlining

# File lib/yard/templates/helpers/html_helper.rb, line 277
def insert_include(text, markup = options.markup)
  htmlify(text, markup).gsub(%r{\A\s*<p>|</p>\s*\Z}, '')
end
mtime(_file) click to toggle source
# File lib/yard/templates/helpers/html_helper.rb, line 378
def mtime(_file) nil end
mtime_url(obj, anchor = nil, relative = true)
Alias for: url_for
signature(meth, link = true, show_extras = true, full_attr_name = true) click to toggle source

Formats the signature of method meth.

@param [CodeObjects::MethodObject] meth the method object to list

the signature of

@param [Boolean] link whether to link the method signature to the details view @param [Boolean] show_extras whether to show extra meta-data (visibility, attribute info) @param [Boolean] full_attr_name whether to show the full attribute name

("name=" instead of "name")

@return [String] the formatted method signature

# File lib/yard/templates/helpers/html_helper.rb, line 507
def signature(meth, link = true, show_extras = true, full_attr_name = true)
  meth = convert_method_to_overload(meth)

  type = signature_types(meth, link)
  type = "&#x21d2; #{type}" if type && !type.empty?
  scope = meth.scope == :class ? "." : "#"
  name = full_attr_name ? meth.name : meth.name.to_s.gsub(/^(\w+)=$/, '\1')
  blk = format_block(meth)
  args = !full_attr_name && meth.writer? ? "" : format_args(meth)
  extras = []
  extras_text = ''
  if show_extras
    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
    end
    extras << meth.visibility if meth.visibility != :public
    extras_text = ' <span class="extras">(' + extras.join(", ") + ')</span>' unless extras.empty?
  end
  title = "%s<strong>%s</strong>%s %s %s" % [scope, h(name), args, blk, type]
  if link
    if meth.is_a?(YARD::CodeObjects::MethodObject)
      link_title = "#{h meth.name(true)} (#{meth.scope} #{meth.type})"
    else
      link_title = "#{h name} (#{meth.type})"
    end
    obj = meth.respond_to?(:object) ? meth.object : meth
    url = url_for(object, obj)
    link_url(url, title, :title => link_title) + extras_text
  else
    title + extras_text
  end
end
signature_types(meth, link = true) click to toggle source

Get the return types for a method signature.

@param [CodeObjects::MethodObject] meth the method object @param [Boolean] link whether to link the types @return [String] the signature types @since 0.5.3

# File lib/yard/templates/helpers/html_helper.rb, line 470
def signature_types(meth, link = true)
  meth = convert_method_to_overload(meth)
  if meth.respond_to?(:object) && !meth.has_tag?(:return)
    meth = meth.object
  end

  type = options.default_return || ""
  if meth.tag(:return) && meth.tag(:return).types
    types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
    first = link ? h(types.first) : format_types([types.first], false)
    if types.size == 2 && types.last == 'nil'
      type = first + '<sup>?</sup>'
    elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
      type = first + '<sup>+</sup>'
    elsif types.size > 2
      type = [first, '...'].join(', ')
    elsif types == ['void'] && options.hide_void_return
      type = ""
    else
      type = link ? h(types.join(", ")) : format_types(types, false)
    end
  elsif !type.empty?
    type = link ? h(type) : format_types([type], false)
  end
  type = "#{type} " unless type.empty?
  type
end
url_for(obj, anchor = nil, relative = true) click to toggle source

Returns the URL for an object.

@param [String, CodeObjects::Base] obj the object (or object path) to link to @param [String] anchor the anchor to link to @param [Boolean] relative use a relative or absolute link @return [String] the URL location of the object

# File lib/yard/templates/helpers/html_helper.rb, line 346
def url_for(obj, anchor = nil, relative = true)
  link = nil
  return link unless serializer
  return link if obj.is_a?(CodeObjects::Base) && run_verifier([obj]).empty?

  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
  end

  objpath = serializer.serialized_path(obj)
  return link unless objpath

  relative = false if object == Registry.root
  if relative
    fromobj = object
    if object.is_a?(CodeObjects::Base) &&
       !object.is_a?(CodeObjects::NamespaceObject)
      fromobj = owner
    end

    from = serializer.serialized_path(fromobj)
    link = File.relative_path(from, objpath)
  else
    link = objpath
  end

  link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
end
Also aliased as: mtime_url
url_for_file(filename, anchor = nil) click to toggle source

Returns the URL for a specific file

@param [String, CodeObjects::ExtraFileObject] filename the filename to link to @param [String] anchor optional anchor @return [String] the URL pointing to the file

# File lib/yard/templates/helpers/html_helper.rb, line 385
def url_for_file(filename, anchor = nil)
  return '' unless serializer
  fromobj = object
  if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
    fromobj = fromobj.namespace
  end
  from = serializer.serialized_path(fromobj)
  path = filename == options.readme ?
    'index.html' : serializer.serialized_path(filename)
  link = File.relative_path(from, path)
  link += (anchor ? '#' + urlencode(anchor) : '')
  link
end
url_for_frameset() click to toggle source

Returns the URL for the frameset page

@return [String] the URL pointing to the frames page @since 0.8.0

# File lib/yard/templates/helpers/html_helper.rb, line 412
def url_for_frameset
  url_for_file("frames.html")
end
url_for_index() click to toggle source

Returns the URL for the alphabetic index page

@return [String] the URL pointing to the first main page the

user should see.
# File lib/yard/templates/helpers/html_helper.rb, line 428
def url_for_index
  url_for_file("_index.html")
end
url_for_list(type) click to toggle source

Returns the URL for a list type

@param [String, Symbol] type the list type to generate a URL for @return [String] the URL pointing to the list @since 0.8.0

# File lib/yard/templates/helpers/html_helper.rb, line 404
def url_for_list(type)
  url_for_file("#{type}_list.html")
end
url_for_main() click to toggle source

Returns the URL for the main page (README or alphabetic index)

@return [String] the URL pointing to the first main page the

user should see.
# File lib/yard/templates/helpers/html_helper.rb, line 420
def url_for_main
  url_for_file("index.html")
end

Private Instance Methods

convert_method_to_overload(meth) click to toggle source

Converts a {CodeObjects::MethodObject} into an overload object @since 0.5.3

# File lib/yard/templates/helpers/html_helper.rb, line 587
def convert_method_to_overload(meth)
  # use first overload tag if it has a return type and method itself does not
  if !meth.tag(:return) && meth.tags(:overload).size == 1 && meth.tag(:overload).tag(:return)
    return meth.tag(:overload)
  end
  meth
end
parse_codeblocks(html) click to toggle source

Parses code blocks out of html and performs syntax highlighting on code inside of the blocks.

@param [String] html the html to search for code in @return [String] highlighted html @see html_syntax_highlight

# File lib/yard/templates/helpers/html_helper.rb, line 618
def parse_codeblocks(html)
  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 ||= $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>)
  end
end
parse_lang_for_codeblock(source) click to toggle source

Parses !!!lang out of codeblock, returning the codeblock language followed by the source code.

@param [String] source the source code whose language to determine @return [Array(String, String)] the language, if any, and the

remaining source

@since 0.7.5

# File lib/yard/templates/helpers/html_helper.rb, line 602
def parse_lang_for_codeblock(source)
  type = nil
  if source =~ /\A(?:[ \t]*\r?\n)?[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/
    type = $1
    source = $'
  end

  [type, source]
end
tag_attrs(opts = {}) click to toggle source

Converts a set of hash options into HTML attributes for a tag

@param [Hash{String => String}] opts the tag options @return [String] the tag attributes of an HTML tag

# File lib/yard/templates/helpers/html_helper.rb, line 581
def tag_attrs(opts = {})
  opts.sort_by {|k, _v| k.to_s }.map {|k, v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
end