123456789_123456789_123456789_123456789_123456789_

Class: YARD::CodeObjects::ExtraFileObject

Relationships & Source Files
Inherits: Object
Defined in: lib/yard/code_objects/extra_file_object.rb

Overview

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.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(filename, contents = nil) ⇒ ExtraFileObject

Creates a new extra file object.

Parameters:

  • filename (String) —

    the location on disk of the file

  • contents (String) (defaults to: nil) —

    the file contents. If not set, the contents will be read from disk using the #filename.

[ GitHub ] 

  


# 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


  







Instance Attribute Details



  

    #attributes   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 30



def attributes
  ensure_parsed
  @attributes
end


  








  

    #attributes=(value)   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 9



attr_writer :attributes


  








  

    #contents   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 39



def contents
  ensure_parsed
  @contents
end


  








  

    #contents=(contents)   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 44



def contents=(contents)
  @original_contents = contents
  @parsed = false
end


  








  

    #filename   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 8



attr_accessor :filename


  








  

    #locale   (rw)
  



  

    
  





  
Since:


    
  
  • 
    
    0.8.3
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 12



attr_reader :locale


  








  

    #locale=(locale)  ⇒ void  (rw)
  



  

    
This method returns an undefined value.

  





  
Parameters:


    
  
  • 
    locale
    (String)
—    
    the locale name to be translated.
    

    
  
    • 



Since:


    
  
  • 
    
    0.8.3
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 52



def locale=(locale)
  @locale = locale
  @parsed = false
end


  








  

    #name   (rw)
    Also known as: #path
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 10



attr_accessor :name


  








  

    #path   (readonly)
  



  

    
Alias for #name.


  



  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 28



alias path name


  







Instance Method Details



  

    #==(other)  
    Also known as: #eql?, #equal?
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 64



def ==(other)
  return false unless self.class === other
  other.filename == filename
end


  








  

    #ensure_parsed   (private)
  

  [ GitHub ]


  

  


# 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


  








  

    #eql?(other)  
  



  

    
Alias for #==.


  



  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 68



alias eql? ==


  








  

    #equal?(other)  
  



  

    
Alias for #==.


  



  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 69



alias equal? ==


  








  

    #hash  
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 70



def hash; filename.hash end


  








  

    #inspect  
    Also known as: #to_s
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 57



def inspect
  "#<yardoc #{type} #{filename} attrs=#{attributes.inspect}>"
end


  








  

    #parse_contents(data)   (private)
  



  

    
  





  
Parameters:


    
  
  • 
    data
    (String)
—    
    the file contents
    

    
  
    • 





  [ GitHub ]


  

  


# 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
  raise unless e.message =~ /invalid byte sequence/

  if retried
    # This should never happen.
    log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
    return ''
  else
    data.force_encoding('binary') if data.respond_to?(:force_encoding)
    retried = true
    retry
  end
end


  








  

    #title  
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 35



def title
  attributes[:title] || name
end


  








  

    #to_s  
  



  

    
Alias for #inspect.


  



  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 60



alias to_s inspect


  








  

    #translate(data)   (private)
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 129



def translate(data)
  text = YARD::I18n::Text.new(data, :have_header => true)
  text.translate(YARD::Registry.locale(locale))
end


  








  

    #type  
  

  [ GitHub ]


  

  


# File 'lib/yard/code_objects/extra_file_object.rb', line 62



def type; :extra_file end