rdoc 7.2.0 → 8.1.0

data/lib/rdoc/generator.rb

@@ -1,52 +1,54 @@
 # frozen_string_literal: true
-##
-# RDoc uses generators to turn parsed source code in the form of an
-# RDoc::CodeObject tree into some form of output.  RDoc comes with the HTML
-# generator RDoc::Generator::Darkfish and an ri data generator
-# RDoc::Generator::RI.
-#
-# == Registering a Generator
-#
-# Generators are registered by calling RDoc::RDoc.add_generator with the class
-# of the generator:
-#
-#   class My::Awesome::Generator
-#     RDoc::RDoc.add_generator self
-#   end
-#
-# == Adding Options to +rdoc+
-#
-# Before option processing in +rdoc+, RDoc::Options will call ::setup_options
-# on the generator class with an RDoc::Options instance.  The generator can
-# use RDoc::Options#option_parser to add command-line options to the +rdoc+
-# tool.  See RDoc::Options@Custom+Options for an example and see OptionParser
-# for details on how to add options.
-#
-# You can extend the RDoc::Options instance with additional accessors for your
-# generator.
-#
-# == Generator Instantiation
-#
-# After parsing, RDoc::RDoc will instantiate a generator by calling
-# #initialize with an RDoc::Store instance and an RDoc::Options instance.
-#
-# The RDoc::Store instance holds documentation for parsed source code.  In
-# RDoc 3 and earlier the RDoc::TopLevel class held this data.  When upgrading
-# a generator from RDoc 3 and earlier you should only need to replace
-# RDoc::TopLevel with the store instance.
-#
-# RDoc will then call #generate on the generator instance.  You can use the
-# various methods on RDoc::Store and in the RDoc::CodeObject tree to create
-# your desired output format.
+module RDoc
+  ##
+  # RDoc uses generators to turn parsed source code in the form of an
+  # RDoc::CodeObject tree into some form of output.  RDoc comes with the HTML
+  # generator RDoc::Generator::Darkfish and an ri data generator
+  # RDoc::Generator::RI.
+  #
+  # == Registering a Generator
+  #
+  # Generators are registered by calling RDoc::RDoc.add_generator with the class
+  # of the generator:
+  #
+  #   class My::Awesome::Generator
+  #     RDoc::RDoc.add_generator self
+  #   end
+  #
+  # == Adding Options to +rdoc+
+  #
+  # Before option processing in +rdoc+, RDoc::Options will call ::setup_options
+  # on the generator class with an RDoc::Options instance.  The generator can
+  # use RDoc::Options#option_parser to add command-line options to the +rdoc+
+  # tool.  See RDoc::Options@Custom+Options for an example and see OptionParser
+  # for details on how to add options.
+  #
+  # You can extend the RDoc::Options instance with additional accessors for your
+  # generator.
+  #
+  # == Generator Instantiation
+  #
+  # After parsing, RDoc::RDoc will instantiate a generator by calling
+  # #initialize with an RDoc::Store instance and an RDoc::Options instance.
+  #
+  # The RDoc::Store instance holds documentation for parsed source code.  In
+  # RDoc 3 and earlier the RDoc::TopLevel class held this data.  When upgrading
+  # a generator from RDoc 3 and earlier you should only need to replace
+  # RDoc::TopLevel with the store instance.
+  #
+  # RDoc will then call #generate on the generator instance.  You can use the
+  # various methods on RDoc::Store and in the RDoc::CodeObject tree to create
+  # your desired output format.
 
-module RDoc::Generator
+  module Generator
 
-  autoload :Markup,   "#{__dir__}/generator/markup"
+    autoload :Markup,   "#{__dir__}/generator/markup"
 
-  autoload :Aliki,     "#{__dir__}/generator/aliki"
-  autoload :Darkfish,  "#{__dir__}/generator/darkfish"
-  autoload :JsonIndex, "#{__dir__}/generator/json_index"
-  autoload :RI,        "#{__dir__}/generator/ri"
-  autoload :POT,       "#{__dir__}/generator/pot"
+    autoload :Aliki,     "#{__dir__}/generator/aliki"
+    autoload :Darkfish,  "#{__dir__}/generator/darkfish"
+    autoload :JsonIndex, "#{__dir__}/generator/json_index"
+    autoload :RI,        "#{__dir__}/generator/ri"
+    autoload :POT,       "#{__dir__}/generator/pot"
 
+  end
 end

data/lib/rdoc/i18n/locale.rb

@@ -1,102 +1,106 @@
 # frozen_string_literal: true
-##
-# A message container for a locale.
-#
-# This object provides the following two features:
-#
-#   * Loads translated messages from .po file.
-#   * Translates a message into the locale.
-
-class RDoc::I18n::Locale
-
-  @@locales = {} # :nodoc:
-
-  class << self
-
+module RDoc
+  module I18n
     ##
-    # Returns the locale object for +locale_name+.
-
-    def [](locale_name)
-      @@locales[locale_name] ||= new(locale_name)
-    end
-
-    ##
-    # Sets the locale object for +locale_name+.
+    # A message container for a locale.
     #
-    # Normally, this method is not used. This method is useful for
-    # testing.
-
-    def []=(locale_name, locale)
-      @@locales[locale_name] = locale
-    end
-
-  end
-
-  ##
-  # The name of the locale. It uses IETF language tag format
-  # +[language[_territory][.codeset][@modifier]]+.
-  #
-  # See also {BCP 47 - Tags for Identifying
-  # Languages}[http://tools.ietf.org/rfc/bcp/bcp47.txt].
-
-  attr_reader :name
-
-  ##
-  # Creates a new locale object for +name+ locale. +name+ must
-  # follow IETF language tag format.
-
-  def initialize(name)
-    @name = name
-    @messages = {}
-  end
+    # This object provides the following two features:
+    #
+    #   * Loads translated messages from .po file.
+    #   * Translates a message into the locale.
+
+    class Locale
+
+      @@locales = {} # :nodoc:
+
+      class << self
+
+        ##
+        # Returns the locale object for +locale_name+.
+
+        def [](locale_name)
+          @@locales[locale_name] ||= new(locale_name)
+        end
+
+        ##
+        # Sets the locale object for +locale_name+.
+        #
+        # Normally, this method is not used. This method is useful for
+        # testing.
+
+        def []=(locale_name, locale)
+          @@locales[locale_name] = locale
+        end
+
+      end
+
+      ##
+      # The name of the locale. It uses IETF language tag format
+      # +[language[_territory][.codeset][@modifier]]+.
+      #
+      # See also {BCP 47 - Tags for Identifying
+      # Languages}[http://tools.ietf.org/rfc/bcp/bcp47.txt].
+
+      attr_reader :name
+
+      ##
+      # Creates a new locale object for +name+ locale. +name+ must
+      # follow IETF language tag format.
+
+      def initialize(name)
+        @name = name
+        @messages = {}
+      end
+
+      ##
+      # Loads translation messages from +locale_directory+/+@name+/rdoc.po
+      # or +locale_directory+/+@name+.po. The former has high priority.
+      #
+      # This method requires gettext gem for parsing .po file. If you
+      # don't have gettext gem, this method doesn't load .po file. This
+      # method warns and returns +false+.
+      #
+      # Returns +true+ if succeeded, +false+ otherwise.
+
+      def load(locale_directory)
+        return false if @name.nil?
+
+        po_file_candidates = [
+          File.join(locale_directory, @name, 'rdoc.po'),
+          File.join(locale_directory, "#{@name}.po"),
+        ]
+        po_file = po_file_candidates.find do |po_file_candidate|
+          File.exist?(po_file_candidate)
+        end
+        return false unless po_file
+
+        begin
+          require 'gettext/po_parser'
+          require 'gettext/mo'
+        rescue LoadError
+          warn('Need gettext gem for i18n feature:')
+          warn('  gem install gettext')
+          return false
+        end
+
+        po_parser = GetText::POParser.new
+        messages = GetText::MO.new
+        po_parser.report_warning = false
+        po_parser.parse_file(po_file, messages)
+
+        @messages.merge!(messages)
+
+        true
+      end
+
+      ##
+      # Translates the +message+ into locale. If there is no translation
+      # messages for +message+ in locale, +message+ itself is returned.
+
+      def translate(message)
+        @messages[message] || message
+      end
 
-  ##
-  # Loads translation messages from +locale_directory+/+@name+/rdoc.po
-  # or +locale_directory+/+@name+.po. The former has high priority.
-  #
-  # This method requires gettext gem for parsing .po file. If you
-  # don't have gettext gem, this method doesn't load .po file. This
-  # method warns and returns +false+.
-  #
-  # Returns +true+ if succeeded, +false+ otherwise.
-
-  def load(locale_directory)
-    return false if @name.nil?
-
-    po_file_candidates = [
-      File.join(locale_directory, @name, 'rdoc.po'),
-      File.join(locale_directory, "#{@name}.po"),
-    ]
-    po_file = po_file_candidates.find do |po_file_candidate|
-      File.exist?(po_file_candidate)
-    end
-    return false unless po_file
-
-    begin
-      require 'gettext/po_parser'
-      require 'gettext/mo'
-    rescue LoadError
-      warn('Need gettext gem for i18n feature:')
-      warn('  gem install gettext')
-      return false
     end
-
-    po_parser = GetText::POParser.new
-    messages = GetText::MO.new
-    po_parser.report_warning = false
-    po_parser.parse_file(po_file, messages)
-
-    @messages.merge!(messages)
-
-    true
-  end
-
-  ##
-  # Translates the +message+ into locale. If there is no translation
-  # messages for +message+ in locale, +message+ itself is returned.
-
-  def translate(message)
-    @messages[message] || message
   end
-
 end

data/lib/rdoc/i18n/text.rb

@@ -1,126 +1,130 @@
 # frozen_string_literal: true
-##
-# An i18n supported text.
-#
-# This object provides the following two features:
-#
-#   * Extracts translation messages from wrapped raw text.
-#   * Translates wrapped raw text in specified locale.
-#
-# Wrapped raw text is one of String, RDoc::Comment or Array of them.
+module RDoc
+  module I18n
+    ##
+    # An i18n supported text.
+    #
+    # This object provides the following two features:
+    #
+    #   * Extracts translation messages from wrapped raw text.
+    #   * Translates wrapped raw text in specified locale.
+    #
+    # Wrapped raw text is one of String, RDoc::Comment or Array of them.
 
-class RDoc::I18n::Text
+    class Text
 
-  ##
-  # Creates a new i18n supported text for +raw+ text.
+      ##
+      # Creates a new i18n supported text for +raw+ text.
 
-  def initialize(raw)
-    @raw = raw
-  end
+      def initialize(raw)
+        @raw = raw
+      end
 
-  ##
-  # Extracts translation target messages and yields each message.
-  #
-  # Each yielded message is a Hash. It consists of the followings:
-  #
-  # :type      :: :paragraph
-  # :paragraph :: String (The translation target message itself.)
-  # :line_no   :: Integer (The line number of the :paragraph is started.)
-  #
-  # The above content may be added in the future.
+      ##
+      # Extracts translation target messages and yields each message.
+      #
+      # Each yielded message is a Hash. It consists of the followings:
+      #
+      # :type      :: :paragraph
+      # :paragraph :: String (The translation target message itself.)
+      # :line_no   :: Integer (The line number of the :paragraph is started.)
+      #
+      # The above content may be added in the future.
 
-  def extract_messages
-    parse do |part|
-      case part[:type]
-      when :empty_line
-        # ignore
-      when :paragraph
-        yield(part)
+      def extract_messages
+        parse do |part|
+          case part[:type]
+          when :empty_line
+            # ignore
+          when :paragraph
+            yield(part)
+          end
+        end
       end
-    end
-  end
 
-  # Translates raw text into +locale+.
-  def translate(locale)
-    translated_text = ''
-    parse do |part|
-      case part[:type]
-      when :paragraph
-        translated_text += locale.translate(part[:paragraph])
-      when :empty_line
-        translated_text += part[:line]
-      else
-        raise "should not reach here: unexpected type: #{type}"
+      # Translates raw text into +locale+.
+      def translate(locale)
+        translated_text = ''
+        parse do |part|
+          case part[:type]
+          when :paragraph
+            translated_text += locale.translate(part[:paragraph])
+          when :empty_line
+            translated_text += part[:line]
+          else
+            raise "should not reach here: unexpected type: #{type}"
+          end
+        end
+        translated_text
       end
-    end
-    translated_text
-  end
 
-  private
-  def parse(&block)
-    paragraph = ''
-    paragraph_start_line = 0
-    line_no = 0
+    private
+      def parse(&block)
+        paragraph = ''
+        paragraph_start_line = 0
+        line_no = 0
 
-    each_line(@raw) do |line|
-      line_no += 1
-      case line
-      when /\A\s*\z/
-        if paragraph.empty?
-          emit_empty_line_event(line, line_no, &block)
-        else
-          paragraph += line
-          emit_paragraph_event(paragraph, paragraph_start_line, line_no,
-                               &block)
-          paragraph = ''
+        each_line(@raw) do |line|
+          line_no += 1
+          case line
+          when /\A\s*\z/
+            if paragraph.empty?
+              emit_empty_line_event(line, line_no, &block)
+            else
+              paragraph += line
+              emit_paragraph_event(paragraph, paragraph_start_line, line_no,
+                                   &block)
+              paragraph = ''
+            end
+          else
+            paragraph_start_line = line_no if paragraph.empty?
+            paragraph += line
+          end
+        end
+
+        unless paragraph.empty?
+          emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
         end
-      else
-        paragraph_start_line = line_no if paragraph.empty?
-        paragraph += line
       end
-    end
 
-    unless paragraph.empty?
-      emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
-    end
-  end
+      def each_line(raw, &block)
+        case raw
+        when Comment
+          raw.text.each_line(&block)
+        when Hash
+          raw.each_value do |comments|
+            comments.each { |comment| each_line(comment, &block) }
+          end
+        else
+          raw.each_line(&block)
+        end
+      end
 
-  def each_line(raw, &block)
-    case raw
-    when RDoc::Comment
-      raw.text.each_line(&block)
-    when Array
-      raw.each do |comment, location|
-        each_line(comment, &block)
+      def emit_empty_line_event(line, line_no)
+        part = {
+          :type => :empty_line,
+          :line => line,
+          :line_no => line_no,
+        }
+        yield(part)
       end
-    else
-      raw.each_line(&block)
-    end
-  end
 
-  def emit_empty_line_event(line, line_no)
-    part = {
-      :type => :empty_line,
-      :line => line,
-      :line_no => line_no,
-    }
-    yield(part)
-  end
+      def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        paragraph_part = {
+          :type => :paragraph,
+          :line_no => paragraph_start_line,
+        }
+        match_data = /(\s*)\z/.match(paragraph)
+        if match_data
+          paragraph_part[:paragraph] = match_data.pre_match
+          yield(paragraph_part)
+          emit_empty_line_event(match_data[1], line_no, &block)
+        else
+          paragraph_part[:paragraph] = paragraph
+          yield(paragraph_part)
+        end
+      end
 
-  def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
-    paragraph_part = {
-      :type => :paragraph,
-      :line_no => paragraph_start_line,
-    }
-    match_data = /(\s*)\z/.match(paragraph)
-    if match_data
-      paragraph_part[:paragraph] = match_data.pre_match
-      yield(paragraph_part)
-      emit_empty_line_event(match_data[1], line_no, &block)
-    else
-      paragraph_part[:paragraph] = paragraph
-      yield(paragraph_part)
     end
   end
-
 end

data/lib/rdoc/i18n.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
-##
-# This module provides i18n related features.
+module RDoc
+  ##
+  # This module provides i18n related features.
 
-module RDoc::I18n
+  module I18n
 
-  autoload :Locale, "#{__dir__}/i18n/locale"
-  require_relative 'i18n/text'
+    autoload :Locale, "#{__dir__}/i18n/locale"
+    require_relative 'i18n/text'
 
+  end
 end

data/lib/rdoc/markdown/byte_runtime.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'strscan'
+
+module RDoc
+  class Markdown
+
+    ##
+    # Byte-offset replacements for the position helpers of the kpeg-generated
+    # parser runtime.
+    #
+    # The generated runtime addresses +@string+ by character index, which makes
+    # every position lookup scan the string from its beginning when the input
+    # contains non-ASCII characters, so parse time becomes quadratic in the
+    # input size.  Generated rule bodies only save and restore +pos+ without
+    # inspecting it, so replacing these helpers is enough to switch the whole
+    # parser to byte offsets.
+    #
+    # get_byte (the grammar's `.`) consumes one character and returns its
+    # codepoint, exactly like the character-index runtime, so positions always
+    # stay on character boundaries and the only observable difference is the
+    # position values themselves.  The input must be validly encoded in an
+    # ASCII-compatible encoding.
+    #
+    # The error-reporting helpers of the generated runtime (+current_line+,
+    # +current_column+, ...) are left as-is and would misreport locations when
+    # given byte offsets.  They are unreachable: markdown is deliberately
+    # designed to parse any input somehow rather than fail (the root rule
+    # `Doc = Block*` cannot fail), so a parse failure means a bug in the
+    # grammar itself, and nothing in RDoc invokes +raise_error+ or
+    # +show_error+.  Make these helpers byte-aware before using them for
+    # anything.
+
+    module ByteRuntime
+      def set_string(string, pos)
+        @string = string
+        @string_size = string ? string.bytesize : 0
+        @pos = pos
+        @position_line_offsets = nil
+        @scanner = string ? StringScanner.new(string) : nil
+      end
+
+      def scan(reg)
+        @scanner.pos = @pos
+        if @scanner.skip(reg)
+          @pos = @scanner.pos
+          true
+        end
+      end
+
+      def match_string(str)
+        len = str.bytesize
+        if @string.byteslice(@pos, len) == str
+          @pos += len
+          str
+        end
+      end
+
+      def get_byte
+        byte = @string.getbyte(@pos)
+        return nil unless byte
+
+        if byte < 0x80
+          @pos += 1
+          byte
+        else
+          @scanner.pos = @pos
+          # /./ interprets the character in the string's own encoding
+          char = @scanner.scan(/./m)
+          @pos = @scanner.pos
+          char.ord
+        end
+      end
+
+      def get_text(start)
+        @string.byteslice(start, @pos - start)
+      end
+    end
+  end
+end