Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • rdoc/encoding.rb

Class/Module Index [+]



This class is a wrapper around File IO and Encoding that helps RDoc load files and convert them to the correct encoding.

Public Class Methods

read_file(filename, encoding, force_transcode = false) click to toggle source

Reads the contents of filename and handles any encoding directives in the file.

The content will be converted to the encoding. If the file cannot be converted a warning will be printed and nil will be returned.

If force_transcode is true the document will be transcoded and any unknown character in the target encoding will be replaced with ‘?’

               # File rdoc/encoding.rb, line 20
def self.read_file filename, encoding, force_transcode = false
  content = open filename, "rb" do |f| f.read end
  content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/

  utf8 = content.sub!(/\A\xef\xbb\xbf/, '')

  RDoc::Encoding.set_encoding content

  if Object.const_defined? :Encoding then
    encoding ||= Encoding.default_external
    orig_encoding = content.encoding

    if utf8 then
      content.force_encoding Encoding::UTF_8
      content.encode! encoding
      # assume the content is in our output encoding
      content.force_encoding encoding

    unless content.valid_encoding? then
      # revert and try to transcode
      content.force_encoding orig_encoding
      content.encode! encoding

    unless content.valid_encoding? then
      warn "unable to convert #{filename} to #{encoding}, skipping"
      content = nil

rescue ArgumentError => e
  raise unless e.message =~ /unknown encoding name - (.*)/
  warn "unknown encoding name \"#{$1}\" for #{filename}, skipping"
rescue Encoding::UndefinedConversionError => e
  if force_transcode then
    content.force_encoding orig_encoding
    content.encode! encoding, :undef => :replace, :replace => '?'
    warn "unable to convert #{e.message} for #{filename}, skipping"
rescue Errno::EISDIR, Errno::ENOENT
set_encoding(string) click to toggle source

Sets the encoding of string based on the magic comment

               # File rdoc/encoding.rb, line 73
def self.set_encoding string
  first_line = string[/\A(?:#!.*\n)?.*\n/]

  name = case first_line
         when /^<\?xml[^?]*encoding=(["'])(.*?)\1/ then $2
         when /\b(?:en)?coding[=:]\s*([^\s;]+)/i   then $1
         else                                           return

  string.sub! first_line, ''

  return unless Object.const_defined? :Encoding

  enc = Encoding.find name
  string.force_encoding enc if enc

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.