class YARD::CodeObjects::ExtraFileObject

An ExtraFileObject represents an extra documentation file (README or other file). It is not strictly a CodeObject (does not inherit from `Base`) although it implements `path`, `name` and `type`, and therefore should be structurally compatible with most CodeObject interfaces.

Attributes

attributes[W]
filename[RW]
locale[R]

@since 0.8.3

name[RW]
path[RW]

Public Class Methods

new(filename, contents = nil) click to toggle source

Creates a new extra file object. @param [String] filename the location on disk of the file @param [String] contents the file contents. If not set, the contents

will be read from disk using the +filename+.
# File lib/yard/code_objects/extra_file_object.rb, line 18
def initialize(filename, contents = nil)
  self.filename = filename
  self.name = File.basename(filename).gsub(/\.[^.]+$/, '')
  self.attributes = SymbolHash.new(false)
  @original_contents = contents
  @parsed = false
  @locale = nil
  ensure_parsed
end

Public Instance Methods

==(other) click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 64
def ==(other)
  return false unless self.class === other
  other.filename == filename
end
Also aliased as: eql?, equal?
attributes() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 30
def attributes
  ensure_parsed
  @attributes
end
contents() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 39
def contents
  ensure_parsed
  @contents
end
contents=(contents) click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 44
def contents=(contents)
  @original_contents = contents
  @parsed = false
end
eql?(other)
Alias for: ==
equal?(other)
Alias for: ==
hash() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 70
def hash; filename.hash end
inspect() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 57
def inspect
  "#<yardoc #{type} #{filename} attrs=#{attributes.inspect}>"
end
Also aliased as: to_s
locale=(locale) click to toggle source

@param [String] locale the locale name to be translated. @return [void] @since 0.8.3

# File lib/yard/code_objects/extra_file_object.rb, line 52
def locale=(locale)
  @locale = locale
  @parsed = false
end
title() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 35
def title
  attributes[:title] || name
end
to_s()
Alias for: inspect
type() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 62
def type; :extra_file end

Private Instance Methods

ensure_parsed() click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 74
def ensure_parsed
  return if @parsed
  @parsed = true
  @contents = parse_contents(@original_contents || File.read(@filename))
end
parse_contents(data) click to toggle source

@param [String] data the file contents

# File lib/yard/code_objects/extra_file_object.rb, line 81
def parse_contents(data)
  retried = false
  cut_index = 0
  data = translate(data)
  data = data.split("\n")
  data.each_with_index do |line, index|
    case line
    when /^#!(\S+)\s*$/
      if index == 0
        attributes[:markup] = $1
      else
        cut_index = index
        break
      end
    when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
      attributes[$1] = $2
    when /^\s*<!--\s*$/, /^\s*-->\s*$/
      # Ignore HTML comments
    else
      cut_index = index
      break
    end
  end
  data = data[cut_index..-1] if cut_index > 0
  contents = data.join("\n")

  if contents.respond_to?(:force_encoding) && attributes[:encoding]
    begin
      contents.force_encoding(attributes[:encoding])
    rescue ArgumentError
      log.warn "Invalid encoding `#{attributes[:encoding]}' in #{filename}"
    end
  end
  contents
rescue ArgumentError => e
  if retried && e.message =~ /invalid byte sequence/
    # This should never happen.
    log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
    return ''
  end
  data.force_encoding('binary') if data.respond_to?(:force_encoding)
  retried = true
  retry
end
translate(data) click to toggle source
# File lib/yard/code_objects/extra_file_object.rb, line 126
def translate(data)
  text = YARD::I18n::Text.new(data, :have_header => true)
  text.translate(YARD::Registry.locale(locale))
end