Maintenance of Ruby 2.0.0 will end on February 24, 2016. 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 18
def self.read_file filename, encoding, force_transcode = false
  content = open filename, "rb" do |f| 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 Encoding::InvalidByteSequenceError,
           Encoding::UndefinedConversionError => e
      if force_transcode then
        content.force_encoding orig_encoding
                        :invalid => :replace, :undef => :replace,
                        :replace => '?')
        return content
        warn "unable to convert #{e.message} for #{filename}, skipping"
        return nil

rescue ArgumentError => e
  raise unless e.message =~ /unknown encoding name - (.*)/
  warn "unknown encoding name \"#{$1}\" 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 76
def self.set_encoding string
  string =~ /\A(?:#!.*\n)?(.*\n)/

  first_line = $1

  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

blog comments powered by Disqus