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