rdoc 4.2.1 → 6.3.1

data/lib/rdoc/token_stream.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # A TokenStream is a list of tokens, gathered during the parse of some entity
 # (say a method). Entities populate these streams by being registered with the
@@ -9,43 +10,61 @@ module RDoc::TokenStream
 
   ##
   # Converts +token_stream+ to HTML wrapping various tokens with
-  # <tt><span></tt> elements.  The following tokens types are wrapped in spans
-  # with the given class names:
-  #
-  # TkCONSTANT :: 'ruby-constant'
-  # TkKW       :: 'ruby-keyword'
-  # TkIVAR     :: 'ruby-ivar'
-  # TkOp       :: 'ruby-operator'
-  # TkId       :: 'ruby-identifier'
-  # TkNode     :: 'ruby-node'
-  # TkCOMMENT  :: 'ruby-comment'
-  # TkREGEXP   :: 'ruby-regexp'
-  # TkSTRING   :: 'ruby-string'
-  # TkVal      :: 'ruby-value'
-  #
-  # Other token types are not wrapped in spans.
+  # <tt><span></tt> elements. Some tokens types are wrapped in spans
+  # with the given class names. Other token types are not wrapped in spans.
 
   def self.to_html token_stream
+    starting_title = false
+
     token_stream.map do |t|
       next unless t
 
-      style = case t
-              when RDoc::RubyToken::TkCONSTANT then 'ruby-constant'
-              when RDoc::RubyToken::TkKW       then 'ruby-keyword'
-              when RDoc::RubyToken::TkIVAR     then 'ruby-ivar'
-              when RDoc::RubyToken::TkOp       then 'ruby-operator'
-              when RDoc::RubyToken::TkId       then 'ruby-identifier'
-              when RDoc::RubyToken::TkNode     then 'ruby-node'
-              when RDoc::RubyToken::TkCOMMENT  then 'ruby-comment'
-              when RDoc::RubyToken::TkREGEXP   then 'ruby-regexp'
-              when RDoc::RubyToken::TkSTRING   then 'ruby-string'
-              when RDoc::RubyToken::TkVal      then 'ruby-value'
+      style = case t[:kind]
+              when :on_const   then 'ruby-constant'
+              when :on_kw      then 'ruby-keyword'
+              when :on_ivar    then 'ruby-ivar'
+              when :on_cvar    then 'ruby-identifier'
+              when :on_gvar    then 'ruby-identifier'
+              when '=' != t[:text] && :on_op
+                               then 'ruby-operator'
+              when :on_tlambda then 'ruby-operator'
+              when :on_ident   then 'ruby-identifier'
+              when :on_label   then 'ruby-value'
+              when :on_backref, :on_dstring
+                               then 'ruby-node'
+              when :on_comment then 'ruby-comment'
+              when :on_embdoc  then 'ruby-comment'
+              when :on_regexp  then 'ruby-regexp'
+              when :on_tstring then 'ruby-string'
+              when :on_int, :on_float,
+                   :on_rational, :on_imaginary,
+                   :on_heredoc,
+                   :on_symbol, :on_CHAR then 'ruby-value'
+              when :on_heredoc_beg, :on_heredoc_end
+                               then 'ruby-identifier'
               end
 
-      text = CGI.escapeHTML t.text
+      comment_with_nl = false
+      if :on_comment == t[:kind] or :on_embdoc == t[:kind] or :on_heredoc_end == t[:kind]
+        comment_with_nl = true if "\n" == t[:text][-1]
+        text = t[:text].rstrip
+      else
+        text = t[:text]
+      end
+
+      if :on_ident == t[:kind] && starting_title
+        starting_title = false
+        style = 'ruby-identifier ruby-title'
+      end
+
+      if :on_kw == t[:kind] and 'def' == t[:text]
+        starting_title = true
+      end
+
+      text = CGI.escapeHTML text
 
       if style then
-        "<span class=\"#{style}\">#{text}</span>"
+        "<span class=\"#{style}\">#{text}</span>#{"\n" if comment_with_nl}"
       else
         text
       end
@@ -55,11 +74,16 @@ module RDoc::TokenStream
   ##
   # Adds +tokens+ to the collected tokens
 
-  def add_tokens(*tokens)
-    tokens.flatten.each { |token| @token_stream << token }
+  def add_tokens(tokens)
+    @token_stream.concat(tokens)
   end
 
-  alias add_token add_tokens
+  ##
+  # Adds one +token+ to the collected tokens
+
+  def add_token(token)
+    @token_stream.push(token)
+  end
 
   ##
   # Starts collecting tokens
@@ -88,7 +112,7 @@ module RDoc::TokenStream
   # Returns a string representation of the token stream
 
   def tokens_to_s
-    token_stream.compact.map { |token| token.text }.join ''
+    token_stream.compact.map { |token| token[:text] }.join ''
   end
 
 end

data/lib/rdoc/tom_doc.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # :markup: tomdoc
 
 # A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
@@ -179,12 +180,19 @@ class RDoc::TomDoc < RDoc::Markup::Parser
 
       case type
       when :TEXT then
-        @section = 'Returns' if data =~ /\AReturns/
+        @section = 'Returns' if data =~ /\A(Returns|Raises)/
 
         paragraph << data
       when :NEWLINE then
         if :TEXT == peek_token[0] then
-          paragraph << ' '
+          # Lines beginning with 'Raises' in the Returns section should not be
+          # treated as multiline text
+          if 'Returns' == @section and
+            peek_token[1].start_with?('Raises') then
+            break
+          else
+            paragraph << ' '
+          end
         else
           break
         end
@@ -221,7 +229,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   # Returns self.
 
   def tokenize text
-    text.sub!(/\A(Public|Internal|Deprecated):\s+/, '')
+    text = text.sub(/\A(Public|Internal|Deprecated):\s+/, '')
 
     setup_scanner text
 
@@ -234,19 +242,18 @@ class RDoc::TomDoc < RDoc::Markup::Parser
 
       @tokens << case
                  when @s.scan(/\r?\n/) then
-                   token = [:NEWLINE, @s.matched, *token_pos(pos)]
-                   @line_pos = char_pos @s.pos
-                   @line += 1
+                   token = [:NEWLINE, @s.matched, *pos]
+                   @s.newline!
                    token
                  when @s.scan(/(Examples|Signature)$/) then
-                   @tokens << [:HEADER, 3, *token_pos(pos)]
+                   @tokens << [:HEADER, 3, *pos]
 
-                   [:TEXT, @s[1], *token_pos(pos)]
+                   [:TEXT, @s[1], *pos]
                  when @s.scan(/([:\w][\w\[\]]*)[ ]+- /) then
-                   [:NOTE, @s[1], *token_pos(pos)]
+                   [:NOTE, @s[1], *pos]
                  else
                    @s.scan(/.*/)
-                   [:TEXT, @s.matched.sub(/\r$/, ''), *token_pos(pos)]
+                   [:TEXT, @s.matched.sub(/\r$/, ''), *pos]
                  end
     end
 
@@ -254,4 +261,3 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   end
 
 end
-

data/lib/rdoc/top_level.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # A TopLevel context is a representation of the contents of a single file
 
@@ -32,7 +33,7 @@ class RDoc::TopLevel < RDoc::Context
   ##
   # The parser class that processed this file
 
-  attr_accessor :parser
+  attr_reader :parser
 
   ##
   # Creates a new TopLevel for the file at +absolute_name+.  If documentation
@@ -51,6 +52,12 @@ class RDoc::TopLevel < RDoc::Context
     @classes_or_modules = []
   end
 
+  def parser=(val)
+    @parser = val
+    @store.update_parser_of_file(absolute_name, val) if @store
+    @parser
+  end
+
   ##
   # An RDoc::TopLevel is equal to another with the same relative_name
 
@@ -271,7 +278,7 @@ class RDoc::TopLevel < RDoc::Context
   # Is this TopLevel from a text file instead of a source code file?
 
   def text?
-    @parser and @parser.ancestors.include? RDoc::Parser::Text
+    @parser and @parser.include? RDoc::Parser::Text
   end
 
   def to_s # :nodoc:

data/lib/rdoc/version.rb

@@ -0,0 +1,8 @@
+module RDoc
+
+  ##
+  # RDoc version you are using
+
+  VERSION = '6.3.1'
+
+end

data/lib/rdoc.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 $DEBUG_RDOC = nil
 
 # :main: README.rdoc
@@ -61,10 +62,7 @@ module RDoc
 
   class Error < RuntimeError; end
 
-  ##
-  # RDoc version you are using
-
-  VERSION = '4.2.1'
+  require 'rdoc/version'
 
   ##
   # Method visibilities
@@ -122,9 +120,28 @@ module RDoc
     end
   end
 
-  autoload :RDoc,           'rdoc/rdoc'
+  def self.home
+    rdoc_dir = begin
+                File.expand_path('~/.rdoc')
+              rescue ArgumentError
+              end
+
+    if File.directory?(rdoc_dir)
+      rdoc_dir
+    else
+      begin
+        # XDG
+        xdg_data_home = ENV["XDG_DATA_HOME"] || File.join(File.expand_path("~"), '.local', 'share')
+        unless File.exist?(xdg_data_home)
+          FileUtils.mkdir_p xdg_data_home
+        end
+        File.join xdg_data_home, "rdoc"
+      rescue Errno::EACCES
+      end
+    end
+  end
 
-  autoload :TestCase,       'rdoc/test_case'
+  autoload :RDoc,           'rdoc/rdoc'
 
   autoload :CrossReference, 'rdoc/cross_reference'
   autoload :ERBIO,          'rdoc/erbio'
@@ -147,13 +164,11 @@ module RDoc
 
   autoload :KNOWN_CLASSES,  'rdoc/known_classes'
 
-  autoload :RubyLex,        'rdoc/ruby_lex'
-  autoload :RubyToken,      'rdoc/ruby_token'
   autoload :TokenStream,    'rdoc/token_stream'
 
   autoload :Comment,        'rdoc/comment'
 
-  autoload :I18n,           'rdoc/i18n'
+  require 'rdoc/i18n'
 
   # code objects
   #
@@ -184,4 +199,3 @@ module RDoc
   autoload :Require,        'rdoc/require'
 
 end
-

data/man/ri.1

@@ -0,0 +1,247 @@
+.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
+.Dd April 20, 2017
+.Dt RI \&1 "Ruby Programmer's Reference Guide"
+.Os UNIX
+.Sh NAME
+.Nm ri
+.Nd Ruby API reference front end
+.Sh SYNOPSIS
+.Nm
+.Op Fl ahilTv
+.Op Fl d Ar DIRNAME
+.Op Fl f Ar FORMAT
+.Op Fl w Ar WIDTH
+.Op Fl - Ns Oo Cm no- Oc Ns Cm pager
+.Op Fl -server Ns Oo = Ns Ar PORT Oc
+.Op Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
+.Op Fl -no-standard-docs
+.Op Fl - Ns Oo Cm no- Oc Ns Bro Cm system Ns | Ns Cm site Ns | Ns Cm gems Ns | Ns Cm home Brc
+.Op Fl - Ns Oo Cm no- Oc Ns Cm profile
+.Op Fl -dump Ns = Ns Ar CACHE
+.Op Ar name ...
+.Sh DESCRIPTION
+.Nm
+is a command-line front end for the Ruby API reference.
+You can search and read the API reference for classes and methods with
+.Nm .
+.Pp
+.Nm
+is a part of Ruby.
+.Pp
+.Ar name
+can be:
+.Bl -diag -offset indent
+.It Class | Module | Module::Class
+.Pp
+.It Class::method | Class#method | Class.method | method
+.Pp
+.It gem_name: | gem_name:README | gem_name:History
+.El
+.Pp
+All class names may be abbreviated to their minimum unambiguous form.
+If a name is ambiguous, all valid options will be listed.
+.Pp
+A
+.Ql \&.
+matches either class or instance methods, while #method
+matches only instance and ::method matches only class methods.
+.Pp
+README and other files may be displayed by prefixing them with the gem name
+they're contained in.  If the gem name is followed by a
+.Ql \&:
+all files in the gem will be shown.
+The file name extension may be omitted where it is unambiguous.
+.Pp
+For example:
+.Bd -literal -offset indent
+ri Fil
+ri File
+ri File.new
+ri zip
+ri rdoc:README
+.Ed
+.Pp
+Note that shell quoting or escaping may be required for method names
+containing punctuation:
+.Bd -literal -offset indent
+ri 'Array.[]'
+ri compact\e!
+.Ed
+.Pp
+To see the default directories
+.Nm
+will search, run:
+.Bd -literal -offset indent
+ri --list-doc-dirs
+.Ed
+.Pp
+Specifying the
+.Fl -system , Fl -site , Fl -home , Fl -gems ,
+or
+.Fl -doc-dir
+options will limit
+.Nm
+to searching only the specified directories.
+.Pp
+.Nm
+options may be set in the
+.Ev RI
+environment variable.
+.Pp
+The
+.Nm
+pager can be set with the
+.Ev RI_PAGER
+environment variable or the
+.Ev PAGER
+environment variable.
+.Pp
+.Sh OPTIONS
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl i
+.It Fl - Ns Oo Cm no- Oc Ns Cm interactive
+In interactive mode you can repeatedly
+look up methods with autocomplete.
+.Pp
+.It Fl a
+.It Fl - Ns Oo Cm no- Oc Ns Cm all
+Show all documentation for a class or module.
+.Pp
+.It Fl l
+.It Fl - Ns Oo Cm no- Oc Ns Cm list
+List classes
+.Nm
+knows about.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm pager
+Send output to a pager,
+rather than directly to stdout.
+.Pp
+.It Fl T
+Synonym for
+.Fl -no-pager .
+.Pp
+.It Fl w Ar WIDTH
+.It Fl -width Ns = Ns Ar WIDTH
+Set the width of the output.
+.Pp
+.It Fl -server Ns Oo = Ns Ar PORT Oc
+Run RDoc server on the given port.
+The default port is\~8214.
+.Pp
+.It Fl f Ar FORMAT
+.It Fl -format Ns = Ns Ar FORMAT
+Use the selected formatter.
+The default formatter is
+.Li bs
+for paged output and
+.Li ansi
+otherwise.
+Valid formatters are:
+.Li ansi , Li bs , Li markdown , Li rdoc .
+.Pp
+.It Fl h
+.It Fl -help
+Show help and exit.
+.Pp
+.It Fl v
+.It Fl -version
+Output version information and exit.
+.El
+.Pp
+Data source options:
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
+List the directories from which
+.Nm
+will source documentation on stdout and exit.
+.Pp
+.It Fl d Ar DIRNAME
+.It Fl -doc-dir Ns = Ns Ar DIRNAME
+List of directories from which to source
+documentation in addition to the standard
+directories.  May be repeated.
+.Pp
+.It Fl -no-standard-docs
+Do not include documentation from the Ruby standard library,
+.Pa site_lib ,
+installed gems, or
+.Pa ~/.rdoc .
+Use with
+.Fl -doc-dir .
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm system
+Include documentation from Ruby's standard library.  Defaults to true.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm site
+Include documentation from libraries installed in
+.Pa site_lib .
+Defaults to true.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm gems
+Include documentation from RubyGems.  Defaults to true.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm home
+Include documentation stored in
+.Pa ~/.rdoc .
+Defaults to true.
+.El
+.Pp
+Debug options:
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm profile
+Run with the Ruby profiler.
+.Pp
+.It Fl -dump Ns = Ns Ar CACHE
+Dump data from an ri cache or data file.
+.El
+.Pp
+.Sh ENVIRONMENT
+.Bl -tag -width "USERPROFILE" -compact
+.Pp
+.It Ev RI
+Options to prepend to those specified on the command-line.
+.Pp
+.It Ev RI_PAGER
+.It Ev PAGER
+Pager program to use for displaying.
+.Pp
+.It Ev HOME
+.It Ev USERPROFILE
+.It Ev HOMEPATH
+Path to the user's home directory.
+.El
+.Pp
+.Sh FILES
+.Bl -tag -width "USERPROFILE" -compact
+.Pp
+.It Pa ~/.rdoc
+Path for ri data in the user's home directory.
+.Pp
+.El
+.Pp
+.Sh SEE ALSO
+.Xr ruby 1 ,
+.Xr rdoc 1 ,
+.Xr gem 1
+.Pp
+.Sh REPORTING BUGS
+.Bl -bullet
+.It
+Security vulnerabilities should be reported via an email to
+.Mt security@ruby-lang.org .
+Reported problems will be published after being fixed.
+.Pp
+.It
+Other bugs and feature requests can be reported via the
+Ruby Issue Tracking System
+.Pq Lk https://bugs.ruby-lang.org/ .
+Do not report security vulnerabilities
+via this system because it publishes the vulnerabilities immediately.
+.El
+.Sh AUTHORS
+Written by
+.An Dave Thomas Aq dave@pragmaticprogrammer.com .