rdoc 3.1 → 6.3.3

data/lib/rdoc/generator/template/json_index/js/searcher.js

@@ -0,0 +1,229 @@
+Searcher = function(data) {
+  this.data = data;
+  this.handlers = [];
+}
+
+Searcher.prototype = new function() {
+  // search is performed in chunks of 1000 for non-blocking user input
+  var CHUNK_SIZE = 1000;
+  // do not try to find more than 100 results
+  var MAX_RESULTS = 100;
+  var huid = 1;
+  var suid = 1;
+  var runs = 0;
+
+  this.find = function(query) {
+    var queries = splitQuery(query);
+    var regexps = buildRegexps(queries);
+    var highlighters = buildHilighters(queries);
+    var state = { from: 0, pass: 0, limit: MAX_RESULTS, n: suid++};
+    var _this = this;
+
+    this.currentSuid = state.n;
+
+    if (!query) return;
+
+    var run = function() {
+      // stop current search thread if new search started
+      if (state.n != _this.currentSuid) return;
+
+      var results =
+        performSearch(_this.data, regexps, queries, highlighters, state);
+      var hasMore = (state.limit > 0 && state.pass < 4);
+
+      triggerResults.call(_this, results, !hasMore);
+      if (hasMore) {
+        setTimeout(run, 2);
+      }
+      runs++;
+    };
+    runs = 0;
+
+    // start search thread
+    run();
+  }
+
+  /*  ----- Events ------  */
+  this.ready = function(fn) {
+    fn.huid = huid;
+    this.handlers.push(fn);
+  }
+
+  /*  ----- Utilities ------  */
+  function splitQuery(query) {
+    return query.split(/(\s+|::?|\(\)?)/).filter(function(string) {
+      return string.match(/\S/);
+    });
+  }
+
+  function buildRegexps(queries) {
+    return queries.map(function(query) {
+      return new RegExp(query.replace(/(.)/g, '([$1])([^$1]*?)'), 'i');
+    });
+  }
+
+  function buildHilighters(queries) {
+    return queries.map(function(query) {
+      return query.split('').map(function(l, i) {
+        return '\u0001$' + (i*2+1) + '\u0002$' + (i*2+2);
+      }).join('');
+    });
+  }
+
+  // function longMatchRegexp(index, longIndex, regexps) {
+  //     for (var i = regexps.length - 1; i >= 0; i--){
+  //         if (!index.match(regexps[i]) && !longIndex.match(regexps[i])) return false;
+  //     };
+  //     return true;
+  // }
+
+
+  /*  ----- Mathchers ------  */
+
+  /*
+   * This record matches if the index starts with queries[0] and the record
+   * matches all of the regexps
+   */
+  function matchPassBeginning(index, longIndex, queries, regexps) {
+    if (index.indexOf(queries[0]) != 0) return false;
+    for (var i=1, l = regexps.length; i < l; i++) {
+      if (!index.match(regexps[i]) && !longIndex.match(regexps[i]))
+        return false;
+    };
+    return true;
+  }
+
+  /*
+   * This record matches if the longIndex starts with queries[0] and the
+   * longIndex matches all of the regexps
+   */
+  function matchPassLongIndex(index, longIndex, queries, regexps) {
+    if (longIndex.indexOf(queries[0]) != 0) return false;
+    for (var i=1, l = regexps.length; i < l; i++) {
+      if (!longIndex.match(regexps[i]))
+        return false;
+    };
+    return true;
+  }
+
+  /*
+   * This record matches if the index contains queries[0] and the record
+   * matches all of the regexps
+   */
+  function matchPassContains(index, longIndex, queries, regexps) {
+    if (index.indexOf(queries[0]) == -1) return false;
+    for (var i=1, l = regexps.length; i < l; i++) {
+      if (!index.match(regexps[i]) && !longIndex.match(regexps[i]))
+        return false;
+    };
+    return true;
+  }
+
+  /*
+   * This record matches if regexps[0] matches the index and the record
+   * matches all of the regexps
+   */
+  function matchPassRegexp(index, longIndex, queries, regexps) {
+    if (!index.match(regexps[0])) return false;
+    for (var i=1, l = regexps.length; i < l; i++) {
+      if (!index.match(regexps[i]) && !longIndex.match(regexps[i]))
+        return false;
+    };
+    return true;
+  }
+
+
+  /*  ----- Highlighters ------  */
+  function highlightRegexp(info, queries, regexps, highlighters) {
+    var result = createResult(info);
+    for (var i=0, l = regexps.length; i < l; i++) {
+      result.title = result.title.replace(regexps[i], highlighters[i]);
+      result.namespace = result.namespace.replace(regexps[i], highlighters[i]);
+    };
+    return result;
+  }
+
+  function hltSubstring(string, pos, length) {
+    return string.substring(0, pos) + '\u0001' + string.substring(pos, pos + length) + '\u0002' + string.substring(pos + length);
+  }
+
+  function highlightQuery(info, queries, regexps, highlighters) {
+    var result = createResult(info);
+    var pos = 0;
+    var lcTitle = result.title.toLowerCase();
+
+    pos = lcTitle.indexOf(queries[0]);
+    if (pos != -1) {
+      result.title = hltSubstring(result.title, pos, queries[0].length);
+    }
+
+    result.namespace = result.namespace.replace(regexps[0], highlighters[0]);
+    for (var i=1, l = regexps.length; i < l; i++) {
+      result.title = result.title.replace(regexps[i], highlighters[i]);
+      result.namespace = result.namespace.replace(regexps[i], highlighters[i]);
+    };
+    return result;
+  }
+
+  function createResult(info) {
+    var result = {};
+    result.title = info[0];
+    result.namespace = info[1];
+    result.path = info[2];
+    result.params = info[3];
+    result.snippet = info[4];
+    result.badge = info[6];
+    return result;
+  }
+
+  /*  ----- Searching ------  */
+  function performSearch(data, regexps, queries, highlighters, state) {
+    var searchIndex = data.searchIndex;
+    var longSearchIndex = data.longSearchIndex;
+    var info = data.info;
+    var result = [];
+    var i = state.from;
+    var l = searchIndex.length;
+    var togo = CHUNK_SIZE;
+    var matchFunc, hltFunc;
+
+    while (state.pass < 4 && state.limit > 0 && togo > 0) {
+      if (state.pass == 0) {
+        matchFunc = matchPassBeginning;
+        hltFunc = highlightQuery;
+      } else if (state.pass == 1) {
+        matchFunc = matchPassLongIndex;
+        hltFunc = highlightQuery;
+      } else if (state.pass == 2) {
+        matchFunc = matchPassContains;
+        hltFunc = highlightQuery;
+      } else if (state.pass == 3) {
+        matchFunc = matchPassRegexp;
+        hltFunc = highlightRegexp;
+      }
+
+      for (; togo > 0 && i < l && state.limit > 0; i++, togo--) {
+        if (info[i].n == state.n) continue;
+        if (matchFunc(searchIndex[i], longSearchIndex[i], queries, regexps)) {
+          info[i].n = state.n;
+          result.push(hltFunc(info[i], queries, regexps, highlighters));
+          state.limit--;
+        }
+      };
+      if (searchIndex.length <= i) {
+        state.pass++;
+        i = state.from = 0;
+      } else {
+        state.from = i;
+      }
+    }
+    return result;
+  }
+
+  function triggerResults(results, isLast) {
+    this.handlers.forEach(function(fn) {
+      fn.call(this, results, isLast)
+    });
+  }
+}
+

data/lib/rdoc/generator.rb

@@ -1,12 +1,11 @@
-require 'rdoc'
-
+# 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
+# == Registering a Generator
 #
 # Generators are registered by calling RDoc::RDoc.add_generator with the class
 # of the generator:
@@ -15,26 +14,38 @@ require 'rdoc'
 #     RDoc::RDoc.add_generator self
 #   end
 #
-# = Adding Options to +rdoc+
+# == 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 OptionParser for details on how to add options.
+# 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 accesors for your
+# You can extend the RDoc::Options instance with additional accessors for your
 # generator.
 #
-# = Generator Instantiation
+# == Generator Instantiation
 #
 # After parsing, RDoc::RDoc will instantiate a generator by calling
-# #initialize with an RDoc::Options instance.
+# #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 and pass in an Array
-# of RDoc::TopLevel instances, each representing a parsed file.  You can use
-# the various class methods on RDoc::TopLevel and in the RDoc::CodeObject tree
-# to create your desired output format.
+# 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
-end
 
+  autoload :Markup,   'rdoc/generator/markup'
+
+  autoload :Darkfish,  'rdoc/generator/darkfish'
+  autoload :JsonIndex, 'rdoc/generator/json_index'
+  autoload :RI,        'rdoc/generator/ri'
+  autoload :POT,       'rdoc/generator/pot'
+
+end

data/lib/rdoc/ghost_method.rb

@@ -1,5 +1,4 @@
-require 'rdoc/any_method'
-
+# frozen_string_literal: true
 ##
 # GhostMethod represents a method referenced only by a comment
 

data/lib/rdoc/i18n/locale.rb

@@ -0,0 +1,102 @@
+# 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
+
+    ##
+    # 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
+
+end

data/lib/rdoc/i18n/text.rb

@@ -0,0 +1,126 @@
+# 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.
+
+class RDoc::I18n::Text
+
+  ##
+  # Creates a new i18n supported text for +raw+ text.
+
+  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.
+
+  def extract_messages
+    parse do |part|
+      case part[:type]
+      when :empty_line
+        # ignore
+      when :paragraph
+        yield(part)
+      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}"
+      end
+    end
+    translated_text
+  end
+
+  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 = ''
+        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 RDoc::Comment
+      raw.text.each_line(&block)
+    when Array
+      raw.each do |comment, location|
+        each_line(comment, &block)
+      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
+
+end

data/lib/rdoc/i18n.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+##
+# This module provides i18n related features.
+
+module RDoc::I18n
+
+  autoload :Locale, 'rdoc/i18n/locale'
+  require_relative 'i18n/text'
+
+end

data/lib/rdoc/include.rb

@@ -1,100 +1,10 @@
-require 'rdoc/code_object'
-
+# frozen_string_literal: true
 ##
-# A Module include in a class with \#include
-
-class RDoc::Include < RDoc::CodeObject
-
-  ##
-  # Name of included module
-
-  attr_accessor :name
-
-  ##
-  # Creates a new Include for +name+ with +comment+
-
-  def initialize(name, comment)
-    super()
-    @name = name
-    self.comment = comment
-    @module = nil   # cache for module if found
-  end
-
-  ##
-  # Includes are sorted by name
-
-  def <=> other
-    return unless self.class === other
-
-    name <=> other.name
-  end
-
-  def == other # :nodoc:
-    self.class == other.class and
-      self.name == other.name
-  end
-
-  ##
-  # Full name based on #module
-
-  def full_name
-    m = self.module
-    RDoc::ClassModule === m ? m.full_name : @name
-  end
-
-  def inspect # :nodoc:
-    "#<%s:0x%x %s.include %s>" % [
-      self.class,
-      object_id,
-      parent_name, @name,
-    ]
-  end
-
-  ##
-  # Attempts to locate the included module object.  Returns the name if not
-  # known.
-  #
-  # The scoping rules of Ruby to resolve the name of an included module are:
-  # - first look into the children of the current context;
-  # - if not found, look into the children of included modules,
-  #   in reverse inclusion order;
-  # - if still not found, go up the hierarchy of names.
-
-  def module
-    return @module if @module
-
-    # search the current context
-    return @name unless parent
-    full_name = parent.child_name(@name)
-    @module = RDoc::TopLevel.modules_hash[full_name]
-    return @module if @module
-    return @name if @name =~ /^::/
-
-    # search the includes before this one, in reverse order
-    searched = parent.includes.take_while { |i| i != self }.reverse
-    searched.each do |i|
-      inc = i.module
-      next if String === inc
-      full_name = inc.child_name(@name)
-      @module = RDoc::TopLevel.modules_hash[full_name]
-      return @module if @module
-    end
-
-    # go up the hierarchy of names
-    p = parent.parent
-    while p
-      full_name = p.child_name(@name)
-      @module = RDoc::TopLevel.modules_hash[full_name]
-      return @module if @module
-      p = p.parent
-    end
-
-    @name
-  end
+# A Module included in a class with \#include
+#
+#   RDoc::Include.new 'Enumerable', 'comment ...'
 
-  def to_s # :nodoc:
-    "include #@name in: #{parent}"
-  end
+class RDoc::Include < RDoc::Mixin
 
 end
 

data/lib/rdoc/known_classes.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module RDoc
 
   ##
@@ -26,6 +27,7 @@ module RDoc
     "rb_cRange"            => "Range",
     "rb_cRegexp"           => "Regexp",
     "rb_cRubyVM"           => "RubyVM",
+    "rb_cSocket"           => "Socket",
     "rb_cString"           => "String",
     "rb_cStruct"           => "Struct",
     "rb_cSymbol"           => "Symbol",
@@ -36,7 +38,7 @@ module RDoc
     "rb_eArgError"         => "ArgError",
     "rb_eEOFError"         => "EOFError",
     "rb_eException"        => "Exception",
-    "rb_eFatal"            => "Fatal",
+    "rb_eFatal"            => "fatal",
     "rb_eFloatDomainError" => "FloatDomainError",
     "rb_eIOError"          => "IOError",
     "rb_eIndexError"       => "IndexError",
@@ -49,7 +51,7 @@ module RDoc
     "rb_eRuntimeError"     => "RuntimeError",
     "rb_eScriptError"      => "ScriptError",
     "rb_eSecurityError"    => "SecurityError",
-    "rb_eSignal"           => "Signal",
+    "rb_eSignal"           => "SignalException",
     "rb_eStandardError"    => "StandardError",
     "rb_eSyntaxError"      => "SyntaxError",
     "rb_eSystemCallError"  => "SystemCallError",
@@ -60,6 +62,7 @@ module RDoc
     "rb_mComparable"       => "Comparable",
     "rb_mEnumerable"       => "Enumerable",
     "rb_mErrno"            => "Errno",
+    "rb_mFConst"           => "File::Constants",
     "rb_mFileTest"         => "FileTest",
     "rb_mGC"               => "GC",
     "rb_mKernel"           => "Kernel",