gitlab-rdoc 6.3.2

data/lib/rdoc/markup/hard_break.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+##
+# A hard-break in the middle of a paragraph.
+
+class RDoc::Markup::HardBreak
+
+  @instance = new
+
+  ##
+  # RDoc::Markup::HardBreak is a singleton
+
+  def self.new
+    @instance
+  end
+
+  ##
+  # Calls #accept_hard_break on +visitor+
+
+  def accept visitor
+    visitor.accept_hard_break self
+  end
+
+  def == other # :nodoc:
+    self.class === other
+  end
+
+  def pretty_print q # :nodoc:
+    q.text "[break]"
+  end
+
+end
+

data/lib/rdoc/markup/heading.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+##
+# A heading with a level (1-6) and text
+
+RDoc::Markup::Heading =
+  Struct.new :level, :text do
+
+  @to_html = nil
+  @to_label = nil
+
+  ##
+  # A singleton RDoc::Markup::ToLabel formatter for headings.
+
+  def self.to_label
+    @to_label ||= RDoc::Markup::ToLabel.new
+  end
+
+  ##
+  # A singleton plain HTML formatter for headings.  Used for creating labels
+  # for the Table of Contents
+
+  def self.to_html
+    return @to_html if @to_html
+
+    markup = RDoc::Markup.new
+    markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+
+    @to_html = RDoc::Markup::ToHtml.new nil
+
+    def @to_html.handle_regexp_CROSSREF target
+      target.text.sub(/^\\/, '')
+    end
+
+    @to_html
+  end
+
+  ##
+  # Calls #accept_heading on +visitor+
+
+  def accept visitor
+    visitor.accept_heading self
+  end
+
+  ##
+  # An HTML-safe anchor reference for this header.
+
+  def aref
+    "label-#{self.class.to_label.convert text.dup}"
+  end
+
+  ##
+  # Creates a fully-qualified label which will include the label from
+  # +context+.  This helps keep ids unique in HTML.
+
+  def label context = nil
+    label = aref
+
+    label = [context.aref, label].compact.join '-' if
+      context and context.respond_to? :aref
+
+    label
+  end
+
+  ##
+  # HTML markup of the text of this label without the surrounding header
+  # element.
+
+  def plain_html
+    self.class.to_html.to_html(text.dup)
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, "[head: #{level} ", ']' do
+      q.pp text
+    end
+  end
+
+end
+

data/lib/rdoc/markup/include.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+##
+# A file included at generation time.  Objects of this class are created by
+# RDoc::RD for an extension-less include.
+#
+# This implementation in incomplete.
+
+class RDoc::Markup::Include
+
+  ##
+  # The filename to be included, without extension
+
+  attr_reader :file
+
+  ##
+  # Directories to search for #file
+
+  attr_reader :include_path
+
+  ##
+  # Creates a new include that will import +file+ from +include_path+
+
+  def initialize file, include_path
+    @file = file
+    @include_path = include_path
+  end
+
+  def == other # :nodoc:
+    self.class === other and
+      @file == other.file and @include_path == other.include_path
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, '[incl ', ']' do
+      q.text file
+      q.breakable
+      q.text 'from '
+      q.pp include_path
+    end
+  end
+
+end
+

data/lib/rdoc/markup/indented_paragraph.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+##
+# An Indented Paragraph of text
+
+class RDoc::Markup::IndentedParagraph < RDoc::Markup::Raw
+
+  ##
+  # The indent in number of spaces
+
+  attr_reader :indent
+
+  ##
+  # Creates a new IndentedParagraph containing +parts+ indented with +indent+
+  # spaces
+
+  def initialize indent, *parts
+    @indent = indent
+
+    super(*parts)
+  end
+
+  def == other # :nodoc:
+    super and indent == other.indent
+  end
+
+  ##
+  # Calls #accept_indented_paragraph on +visitor+
+
+  def accept visitor
+    visitor.accept_indented_paragraph self
+  end
+
+  ##
+  # Joins the raw paragraph text and converts inline HardBreaks to the
+  # +hard_break+ text followed by the indent.
+
+  def text hard_break = nil
+    @parts.map do |part|
+      if RDoc::Markup::HardBreak === part then
+        '%1$s%3$*2$s' % [hard_break, @indent, ' '] if hard_break
+      else
+        part
+      end
+    end.join
+  end
+
+end
+

data/lib/rdoc/markup/list.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+##
+# A List is a homogeneous set of ListItems.
+#
+# The supported list types include:
+#
+# :BULLET::
+#   An unordered list
+# :LABEL::
+#   An unordered definition list, but using an alternate RDoc::Markup syntax
+# :LALPHA::
+#   An ordered list using increasing lowercase English letters
+# :NOTE::
+#   An unordered definition list
+# :NUMBER::
+#   An ordered list using increasing Arabic numerals
+# :UALPHA::
+#   An ordered list using increasing uppercase English letters
+#
+# Definition lists behave like HTML definition lists.  Each list item can
+# describe multiple terms.  See RDoc::Markup::ListItem for how labels and
+# definition are stored as list items.
+
+class RDoc::Markup::List
+
+  ##
+  # The list's type
+
+  attr_accessor :type
+
+  ##
+  # Items in the list
+
+  attr_reader :items
+
+  ##
+  # Creates a new list of +type+ with +items+.  Valid list types are:
+  # +:BULLET+, +:LABEL+, +:LALPHA+, +:NOTE+, +:NUMBER+, +:UALPHA+
+
+  def initialize type = nil, *items
+    @type = type
+    @items = []
+    @items.concat items
+  end
+
+  ##
+  # Appends +item+ to the list
+
+  def << item
+    @items << item
+  end
+
+  def == other # :nodoc:
+    self.class == other.class and
+      @type == other.type and
+      @items == other.items
+  end
+
+  ##
+  # Runs this list and all its #items through +visitor+
+
+  def accept visitor
+    visitor.accept_list_start self
+
+    @items.each do |item|
+      item.accept visitor
+    end
+
+    visitor.accept_list_end self
+  end
+
+  ##
+  # Is the list empty?
+
+  def empty?
+    @items.empty?
+  end
+
+  ##
+  # Returns the last item in the list
+
+  def last
+    @items.last
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, "[list: #{@type} ", ']' do
+      q.seplist @items do |item|
+        q.pp item
+      end
+    end
+  end
+
+  ##
+  # Appends +items+ to the list
+
+  def push *items
+    @items.concat items
+  end
+
+end
+

data/lib/rdoc/markup/list_item.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+##
+# An item within a List that contains paragraphs, headings, etc.
+#
+# For BULLET, NUMBER, LALPHA and UALPHA lists, the label will always be nil.
+# For NOTE and LABEL lists, the list label may contain:
+#
+# * a single String for a single label
+# * an Array of Strings for a list item with multiple terms
+# * nil for an extra description attached to a previously labeled list item
+
+class RDoc::Markup::ListItem
+
+  ##
+  # The label for the ListItem
+
+  attr_accessor :label
+
+  ##
+  # Parts of the ListItem
+
+  attr_reader :parts
+
+  ##
+  # Creates a new ListItem with an optional +label+ containing +parts+
+
+  def initialize label = nil, *parts
+    @label = label
+    @parts = []
+    @parts.concat parts
+  end
+
+  ##
+  # Appends +part+ to the ListItem
+
+  def << part
+    @parts << part
+  end
+
+  def == other # :nodoc:
+    self.class == other.class and
+      @label == other.label and
+      @parts == other.parts
+  end
+
+  ##
+  # Runs this list item and all its #parts through +visitor+
+
+  def accept visitor
+    visitor.accept_list_item_start self
+
+    @parts.each do |part|
+      part.accept visitor
+    end
+
+    visitor.accept_list_item_end self
+  end
+
+  ##
+  # Is the ListItem empty?
+
+  def empty?
+    @parts.empty?
+  end
+
+  ##
+  # Length of parts in the ListItem
+
+  def length
+    @parts.length
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, '[item: ', ']' do
+      case @label
+      when Array then
+        q.pp @label
+        q.text ';'
+        q.breakable
+      when String then
+        q.pp @label
+        q.text ';'
+        q.breakable
+      end
+
+      q.seplist @parts do |part|
+        q.pp part
+      end
+    end
+  end
+
+  ##
+  # Adds +parts+ to the ListItem
+
+  def push *parts
+    @parts.concat parts
+  end
+
+end
+

data/lib/rdoc/markup/paragraph.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+##
+# A Paragraph of text
+
+class RDoc::Markup::Paragraph < RDoc::Markup::Raw
+
+  ##
+  # Calls #accept_paragraph on +visitor+
+
+  def accept visitor
+    visitor.accept_paragraph self
+  end
+
+  ##
+  # Joins the raw paragraph text and converts inline HardBreaks to the
+  # +hard_break+ text.
+
+  def text hard_break = ''
+    @parts.map do |part|
+      if RDoc::Markup::HardBreak === part then
+        hard_break
+      else
+        part
+      end
+    end.join
+  end
+
+end
+

data/lib/rdoc/markup/parser.rb

@@ -0,0 +1,575 @@
+# frozen_string_literal: true
+require 'strscan'
+
+##
+# A recursive-descent parser for RDoc markup.
+#
+# The parser tokenizes an input string then parses the tokens into a Document.
+# Documents can be converted into output formats by writing a visitor like
+# RDoc::Markup::ToHTML.
+#
+# The parser only handles the block-level constructs Paragraph, List,
+# ListItem, Heading, Verbatim, BlankLine, Rule and BlockQuote.
+# Inline markup such as <tt>\+blah\+</tt> is handled separately by
+# RDoc::Markup::AttributeManager.
+#
+# To see what markup the Parser implements read RDoc.  To see how to use
+# RDoc markup to format text in your program read RDoc::Markup.
+
+class RDoc::Markup::Parser
+
+  include RDoc::Text
+
+  ##
+  # List token types
+
+  LIST_TOKENS = [
+    :BULLET,
+    :LABEL,
+    :LALPHA,
+    :NOTE,
+    :NUMBER,
+    :UALPHA,
+  ]
+
+  ##
+  # Parser error subclass
+
+  class Error < RuntimeError; end
+
+  ##
+  # Raised when the parser is unable to handle the given markup
+
+  class ParseError < Error; end
+
+  ##
+  # Enables display of debugging information
+
+  attr_accessor :debug
+
+  ##
+  # Token accessor
+
+  attr_reader :tokens
+
+  ##
+  # Parses +str+ into a Document.
+  #
+  # Use RDoc::Markup#parse instead of this method.
+
+  def self.parse str
+    parser = new
+    parser.tokenize str
+    doc = RDoc::Markup::Document.new
+    parser.parse doc
+  end
+
+  ##
+  # Returns a token stream for +str+, for testing
+
+  def self.tokenize str
+    parser = new
+    parser.tokenize str
+    parser.tokens
+  end
+
+  ##
+  # Creates a new Parser.  See also ::parse
+
+  def initialize
+    @binary_input   = nil
+    @current_token  = nil
+    @debug          = false
+    @s              = nil
+    @tokens         = []
+  end
+
+  ##
+  # Builds a Heading of +level+
+
+  def build_heading level
+    type, text, = get
+
+    text = case type
+           when :TEXT then
+             skip :NEWLINE
+             text
+           else
+             unget
+             ''
+           end
+
+    RDoc::Markup::Heading.new level, text
+  end
+
+  ##
+  # Builds a List flush to +margin+
+
+  def build_list margin
+    p :list_start => margin if @debug
+
+    list = RDoc::Markup::List.new
+    label = nil
+
+    until @tokens.empty? do
+      type, data, column, = get
+
+      case type
+      when *LIST_TOKENS then
+        if column < margin || (list.type && list.type != type) then
+          unget
+          break
+        end
+
+        list.type = type
+        peek_type, _, column, = peek_token
+
+        case type
+        when :NOTE, :LABEL then
+          label = [] unless label
+
+          if peek_type == :NEWLINE then
+            # description not on the same line as LABEL/NOTE
+            # skip the trailing newline & any blank lines below
+            while peek_type == :NEWLINE
+              get
+              peek_type, _, column, = peek_token
+            end
+
+            # we may be:
+            #   - at end of stream
+            #   - at a column < margin:
+            #         [text]
+            #       blah blah blah
+            #   - at the same column, but with a different type of list item
+            #       [text]
+            #       * blah blah
+            #   - at the same column, with the same type of list item
+            #       [one]
+            #       [two]
+            # In all cases, we have an empty description.
+            # In the last case only, we continue.
+            if peek_type.nil? || column < margin then
+              empty = true
+            elsif column == margin then
+              case peek_type
+              when type
+                empty = :continue
+              when *LIST_TOKENS
+                empty = true
+              else
+                empty = false
+              end
+            else
+              empty = false
+            end
+
+            if empty then
+              label << data
+              next if empty == :continue
+              break
+            end
+          end
+        else
+          data = nil
+        end
+
+        if label then
+          data = label << data
+          label = nil
+        end
+
+        list_item = RDoc::Markup::ListItem.new data
+        parse list_item, column
+        list << list_item
+
+      else
+        unget
+        break
+      end
+    end
+
+    p :list_end => margin if @debug
+
+    if list.empty? then
+      return nil unless label
+      return nil unless [:LABEL, :NOTE].include? list.type
+
+      list_item = RDoc::Markup::ListItem.new label, RDoc::Markup::BlankLine.new
+      list << list_item
+    end
+
+    list
+  end
+
+  ##
+  # Builds a Paragraph that is flush to +margin+
+
+  def build_paragraph margin
+    p :paragraph_start => margin if @debug
+
+    paragraph = RDoc::Markup::Paragraph.new
+
+    until @tokens.empty? do
+      type, data, column, = get
+
+      if type == :TEXT and column == margin then
+        paragraph << data
+
+        break if peek_token.first == :BREAK
+
+        data << ' ' if skip :NEWLINE
+      else
+        unget
+        break
+      end
+    end
+
+    paragraph.parts.last.sub!(/ \z/, '') # cleanup
+
+    p :paragraph_end => margin if @debug
+
+    paragraph
+  end
+
+  ##
+  # Builds a Verbatim that is indented from +margin+.
+  #
+  # The verbatim block is shifted left (the least indented lines start in
+  # column 0).  Each part of the verbatim is one line of text, always
+  # terminated by a newline.  Blank lines always consist of a single newline
+  # character, and there is never a single newline at the end of the verbatim.
+
+  def build_verbatim margin
+    p :verbatim_begin => margin if @debug
+    verbatim = RDoc::Markup::Verbatim.new
+
+    min_indent = nil
+    generate_leading_spaces = true
+    line = ''.dup
+
+    until @tokens.empty? do
+      type, data, column, = get
+
+      if type == :NEWLINE then
+        line << data
+        verbatim << line
+        line = ''.dup
+        generate_leading_spaces = true
+        next
+      end
+
+      if column <= margin
+        unget
+        break
+      end
+
+      if generate_leading_spaces then
+        indent = column - margin
+        line << ' ' * indent
+        min_indent = indent if min_indent.nil? || indent < min_indent
+        generate_leading_spaces = false
+      end
+
+      case type
+      when :HEADER then
+        line << '=' * data
+        _, _, peek_column, = peek_token
+        peek_column ||= column + data
+        indent = peek_column - column - data
+        line << ' ' * indent
+      when :RULE then
+        width = 2 + data
+        line << '-' * width
+        _, _, peek_column, = peek_token
+        peek_column ||= column + width
+        indent = peek_column - column - width
+        line << ' ' * indent
+      when :BREAK, :TEXT then
+        line << data
+      else # *LIST_TOKENS
+        list_marker = case type
+                      when :BULLET then data
+                      when :LABEL  then "[#{data}]"
+                      when :NOTE   then "#{data}::"
+                      else # :LALPHA, :NUMBER, :UALPHA
+                        "#{data}."
+                      end
+        line << list_marker
+        peek_type, _, peek_column = peek_token
+        unless peek_type == :NEWLINE then
+          peek_column ||= column + list_marker.length
+          indent = peek_column - column - list_marker.length
+          line << ' ' * indent
+        end
+      end
+
+    end
+
+    verbatim << line << "\n" unless line.empty?
+    verbatim.parts.each { |p| p.slice!(0, min_indent) unless p == "\n" } if min_indent > 0
+    verbatim.normalize
+
+    p :verbatim_end => margin if @debug
+
+    verbatim
+  end
+
+  ##
+  # Pulls the next token from the stream.
+
+  def get
+    @current_token = @tokens.shift
+    p :get => @current_token if @debug
+    @current_token
+  end
+
+  ##
+  # Parses the tokens into an array of RDoc::Markup::XXX objects,
+  # and appends them to the passed +parent+ RDoc::Markup::YYY object.
+  #
+  # Exits at the end of the token stream, or when it encounters a token
+  # in a column less than +indent+ (unless it is a NEWLINE).
+  #
+  # Returns +parent+.
+
+  def parse parent, indent = 0
+    p :parse_start => indent if @debug
+
+    until @tokens.empty? do
+      type, data, column, = get
+
+      case type
+      when :BREAK then
+        parent << RDoc::Markup::BlankLine.new
+        skip :NEWLINE, false
+        next
+      when :NEWLINE then
+        # trailing newlines are skipped below, so this is a blank line
+        parent << RDoc::Markup::BlankLine.new
+        skip :NEWLINE, false
+        next
+      end
+
+      # indentation change: break or verbatim
+      if column < indent then
+        unget
+        break
+      elsif column > indent then
+        unget
+        parent << build_verbatim(indent)
+        next
+      end
+
+      # indentation is the same
+      case type
+      when :HEADER then
+        parent << build_heading(data)
+      when :RULE then
+        parent << RDoc::Markup::Rule.new(data)
+        skip :NEWLINE
+      when :TEXT then
+        unget
+        parse_text parent, indent
+      when :BLOCKQUOTE then
+        type, _, column = get
+        if type == :NEWLINE
+          type, _, column = get
+        end
+        unget if type
+        bq = RDoc::Markup::BlockQuote.new
+        p :blockquote_start => [data, column] if @debug
+        parse bq, column
+        p :blockquote_end => indent if @debug
+        parent << bq
+      when *LIST_TOKENS then
+        unget
+        parent << build_list(indent)
+      else
+        type, data, column, line = @current_token
+        raise ParseError, "Unhandled token #{type} (#{data.inspect}) at #{line}:#{column}"
+      end
+    end
+
+    p :parse_end => indent if @debug
+
+    parent
+
+  end
+
+  ##
+  # Small hook that is overridden by RDoc::TomDoc
+
+  def parse_text parent, indent # :nodoc:
+    parent << build_paragraph(indent)
+  end
+
+  ##
+  # Returns the next token on the stream without modifying the stream
+
+  def peek_token
+    token = @tokens.first || []
+    p :peek => token if @debug
+    token
+  end
+
+  ##
+  # A simple wrapper of StringScanner that is aware of the current column and lineno
+
+  class MyStringScanner
+    def initialize(input)
+      @line = @column = 0
+      @s = StringScanner.new input
+    end
+
+    def scan(re)
+      ret = @s.scan(re)
+      @column += ret.length if ret
+      ret
+    end
+
+    def unscan(s)
+      @s.pos -= s.bytesize
+      @column -= s.length
+    end
+
+    def pos
+      [@column, @line]
+    end
+
+    def newline!
+      @column = 0
+      @line += 1
+    end
+
+    def eos?
+      @s.eos?
+    end
+
+    def matched
+      @s.matched
+    end
+
+    def [](i)
+      @s[i]
+    end
+  end
+
+  ##
+  # Creates the StringScanner
+
+  def setup_scanner input
+    @s = MyStringScanner.new input
+  end
+
+  ##
+  # Skips the next token if its type is +token_type+.
+  #
+  # Optionally raises an error if the next token is not of the expected type.
+
+  def skip token_type, error = true
+    type, = get
+    return unless type # end of stream
+    return @current_token if token_type == type
+    unget
+    raise ParseError, "expected #{token_type} got #{@current_token.inspect}" if error
+  end
+
+  ##
+  # Turns text +input+ into a stream of tokens
+
+  def tokenize input
+    setup_scanner input
+
+    until @s.eos? do
+      pos = @s.pos
+
+      # leading spaces will be reflected by the column of the next token
+      # the only thing we loose are trailing spaces at the end of the file
+      next if @s.scan(/ +/)
+
+      # note: after BULLET, LABEL, etc.,
+      # indent will be the column of the next non-newline token
+
+      @tokens << case
+                 # [CR]LF => :NEWLINE
+                 when @s.scan(/\r?\n/) then
+                   token = [:NEWLINE, @s.matched, *pos]
+                   @s.newline!
+                   token
+                 # === text => :HEADER then :TEXT
+                 when @s.scan(/(=+)(\s*)/) then
+                   level = @s[1].length
+                   header = [:HEADER, level, *pos]
+
+                   if @s[2] =~ /^\r?\n/ then
+                     @s.unscan(@s[2])
+                     header
+                   else
+                     pos = @s.pos
+                     @s.scan(/.*/)
+                     @tokens << header
+                     [:TEXT, @s.matched.sub(/\r$/, ''), *pos]
+                   end
+                 # --- (at least 3) and nothing else on the line => :RULE
+                 when @s.scan(/(-{3,}) *\r?$/) then
+                   [:RULE, @s[1].length - 2, *pos]
+                 # * or - followed by white space and text => :BULLET
+                 when @s.scan(/([*-]) +(\S)/) then
+                   @s.unscan(@s[2])
+                   [:BULLET, @s[1], *pos]
+                 # A. text, a. text, 12. text => :UALPHA, :LALPHA, :NUMBER
+                 when @s.scan(/([a-z]|\d+)\. +(\S)/i) then
+                   # FIXME if tab(s), the column will be wrong
+                   # either support tabs everywhere by first expanding them to
+                   # spaces, or assume that they will have been replaced
+                   # before (and provide a check for that at least in debug
+                   # mode)
+                   list_label = @s[1]
+                   @s.unscan(@s[2])
+                   list_type =
+                     case list_label
+                     when /[a-z]/ then :LALPHA
+                     when /[A-Z]/ then :UALPHA
+                     when /\d/    then :NUMBER
+                     else
+                       raise ParseError, "BUG token #{list_label}"
+                     end
+                   [list_type, list_label, *pos]
+                 # [text] followed by spaces or end of line => :LABEL
+                 when @s.scan(/\[(.*?)\]( +|\r?$)/) then
+                   [:LABEL, @s[1], *pos]
+                 # text:: followed by spaces or end of line => :NOTE
+                 when @s.scan(/(.*?)::( +|\r?$)/) then
+                   [:NOTE, @s[1], *pos]
+                 # >>> followed by end of line => :BLOCKQUOTE
+                 when @s.scan(/>>> *(\w+)?$/) then
+                   [:BLOCKQUOTE, @s[1], *pos]
+                 # anything else: :TEXT
+                 else
+                   @s.scan(/(.*?)(  )?\r?$/)
+                   token = [:TEXT, @s[1], *pos]
+
+                   if @s[2] then
+                     @tokens << token
+                     [:BREAK, @s[2], pos[0] + @s[1].length, pos[1]]
+                   else
+                     token
+                   end
+                 end
+    end
+
+    self
+  end
+
+  ##
+  # Returns the current token to the token stream
+
+  def unget
+    token = @current_token
+    p :unget => token if @debug
+    raise Error, 'too many #ungets' if token == @tokens.first
+    @tokens.unshift token if token
+  end
+
+end