asciidoctor 1.5.5 → 1.5.6

data/lib/asciidoctor/table.rb

@@ -14,50 +14,20 @@ class Table < AbstractBlock
       @body = body
     end
 
-    alias :[] :send
+    alias [] send
+
+    # Public: Returns the rows grouped by section.
+    #
+    # Creates a 2-dimensional array of two element entries. The first element
+    # is the section name as a symbol. The second element is the Array of rows
+    # in that section. The entries are in document order (head, foot, body).
+    #
+    # Returns a 2-dimentional Array of rows grouped by section.
+    def by_section
+      [[:head, @head], [:foot, @foot], [:body, @body]]
+    end
   end
 
-  # Public: A String key that specifies the default table format in AsciiDoc (psv)
-  DEFAULT_DATA_FORMAT = 'psv'
-
-  # Public: An Array of String keys that represent the table formats in AsciiDoc
-  DATA_FORMATS = ['psv', 'dsv', 'csv']
-
-  # Public: A Hash mapping the AsciiDoc table formats to their default delimiters
-  DEFAULT_DELIMITERS = {
-    'psv' => '|',
-    'dsv' => ':',
-    'csv' => ','
-  }
-
-  # Public: A Hash mapping styles abbreviations to styles that can be applied
-  # to a table column or cell
-  TEXT_STYLES = {
-    'd' => :none,
-    's' => :strong,
-    'e' => :emphasis,
-    'm' => :monospaced,
-    'h' => :header,
-    'l' => :literal,
-    'v' => :verse,
-    'a' => :asciidoc
-  }
-
-  # Public: A Hash mapping alignment abbreviations to alignments (horizontal
-  # and vertial) that can be applies to a table column or cell
-  ALIGNMENTS = {
-    :h => {
-      '<' => 'left',
-      '>' => 'right',
-      '^' => 'center'
-    },
-    :v => {
-      '<' => 'top',
-      '>' => 'bottom',
-      '^' => 'middle'
-    }
-  }
-
   # Public: Get/Set the columns for this table
   attr_accessor :columns
 
@@ -68,6 +38,9 @@ class Table < AbstractBlock
   # Public: Boolean specifies whether this table has a header row
   attr_accessor :has_header_option
 
+  # Public: Get the caption for this table
+  attr_reader :caption
+
   def initialize parent, attributes
     super parent, :table
     @rows = Rows.new
@@ -87,6 +60,7 @@ class Table < AbstractBlock
     @attributes['tablepcwidth'] = pcwidth_intval
 
     if @document.attributes.key? 'pagewidth'
+      # FIXME calculate more accurately (only used in DocBook output)
       @attributes['tableabswidth'] ||=
           ((@attributes['tablepcwidth'].to_f / 100) * @document.attributes['pagewidth']).round
     end
@@ -135,12 +109,22 @@ class Table < AbstractBlock
       @columns.each {|col| total_width += (col_pcwidth = col.assign_width nil, width_base, pf) }
     else
       col_pcwidth = ((100 * pf / @columns.size).to_i) / pf
+      # or...
+      #col_pcwidth = (100.0 / @columns.size).truncate 4
       col_pcwidth = col_pcwidth.to_i if col_pcwidth.to_i == col_pcwidth
       @columns.each {|col| total_width += col.assign_width col_pcwidth }
     end
 
-    # donate balance, if any, to final column
-    @columns[-1].assign_width(((100 - total_width + col_pcwidth) * pf).round / pf) unless total_width == 100
+    # donate balance, if any, to final column (using half up rounding)
+    unless total_width == 100
+      @columns[-1].assign_width(((100 - total_width + col_pcwidth) * pf).round / pf)
+      # or (manual half up rounding)...
+      #numerator = (raw_numerator = (100 - total_width + col_pcwidth) * pf).to_i
+      #numerator += 1 if raw_numerator >= numerator + 0.5
+      #@columns[-1].assign_width numerator / pf
+      # or...
+      #@columns[-1].assign_width((100 - total_width + col_pcwidth).round 4)
+    end
 
     nil
   end
@@ -149,7 +133,7 @@ class Table < AbstractBlock
   # by the options on the table
   #
   # returns nothing
-  def partition_header_footer(attributes)
+  def partition_header_footer(attrs)
     # set rowcount before splitting up body rows
     @attributes['rowcount'] = @rows.body.size
 
@@ -164,7 +148,7 @@ class Table < AbstractBlock
       @rows.head = [head]
     end
 
-    if num_body_rows > 0 && attributes.key?('footer-option')
+    if num_body_rows > 0 && attrs.key?('footer-option')
       @rows.foot = [@rows.body.pop]
     end
 
@@ -189,7 +173,7 @@ class Table::Column < AbstractNode
   end
 
   # Public: An alias to the parent block (which is always a Table)
-  alias :table :parent
+  alias table parent
 
   # Internal: Calculate and assign the widths (percentage and absolute) for this column
   #
@@ -199,6 +183,8 @@ class Table::Column < AbstractNode
   def assign_width col_pcwidth, width_base = nil, pf = 10000.0
     if width_base
       col_pcwidth = ((@attributes['width'].to_f / width_base) * 100 * pf).to_i / pf
+      # or...
+      #col_pcwidth = (@attributes['width'].to_f * 100.0 / width_base).truncate 4
       col_pcwidth = col_pcwidth.to_i if col_pcwidth.to_i == col_pcwidth
     end
     @attributes['colpcwidth'] = col_pcwidth
@@ -222,58 +208,90 @@ class Table::Cell < AbstractNode
   attr_accessor :rowspan
 
   # Public: An alias to the parent block (which is always a Column)
-  alias :column :parent
+  alias column parent
 
   # Public: The internal Asciidoctor::Document for a cell that has the asciidoc style
   attr_reader :inner_document
 
-  def initialize column, text, attributes = {}, cursor = nil
+  def initialize column, cell_text, attributes = {}, opts = {}
     super column, :cell
-    @text = text
-    @style = nil
-    @colspan = nil
-    @rowspan = nil
-    # TODO feels hacky
     if column
-      @style = column.attributes['style']
-      update_attributes(column.attributes)
+      cell_style = (in_header_row = column.table.header_row?) ? nil : column.attributes['style']
+      # REVIEW feels hacky to inherit all attributes from column
+      update_attributes column.attributes
+    else
+      in_header_row = cell_style = nil
     end
     if attributes
-      @colspan = attributes.delete('colspan')
-      @rowspan = attributes.delete('rowspan')
-      # TODO eventualy remove the style attribute from the attributes hash
-      #@style = attributes.delete('style') if attributes.key? 'style'
-      @style = attributes['style'] if attributes.key? 'style'
-      update_attributes(attributes)
+      @colspan = attributes.delete 'colspan'
+      @rowspan = attributes.delete 'rowspan'
+      # TODO eventually remove the style attribute from the attributes hash
+      #cell_style = attributes.delete 'style' unless in_header_row || !(attributes.key? 'style')
+      cell_style = attributes['style'] unless in_header_row || !(attributes.key? 'style')
+      if opts[:strip_text]
+        if cell_style == :literal || cell_style == :verse
+          cell_text = cell_text.rstrip
+          cell_text = cell_text.slice 1, cell_text.length - 1 while cell_text.start_with? LF
+        else
+          cell_text = cell_text.strip
+        end
+      end
+      update_attributes attributes
+    else
+      @colspan = nil
+      @rowspan = nil
     end
-    # only allow AsciiDoc cells in non-header rows
-    if @style == :asciidoc && !column.table.header_row?
+    # NOTE only true for non-header rows
+    if cell_style == :asciidoc
       # FIXME hide doctitle from nested document; temporary workaround to fix
       # nested document seeing doctitle and assuming it has its own document title
       parent_doctitle = @document.attributes.delete('doctitle')
       # NOTE we need to process the first line of content as it may not have been processed
       # the included content cannot expect to match conditional terminators in the remaining
       # lines of table cell content, it must be self-contained logic
-      inner_document_lines = @text.split(EOL)
-      unless inner_document_lines.empty? || !inner_document_lines[0].include?('::')
-        unprocessed_lines = inner_document_lines[0]
-        processed_lines = PreprocessorReader.new(@document, unprocessed_lines).readlines
-        if processed_lines != unprocessed_lines
+      # QUESTION should we reset cell_text to nil?
+      # QUESTION is is faster to check for :: before splitting?
+      inner_document_lines = cell_text.split LF, -1
+      if (unprocessed_line1 = inner_document_lines[0]).include? '::'
+        preprocessed_lines = (PreprocessorReader.new @document, [unprocessed_line1]).readlines
+        unless unprocessed_line1 == preprocessed_lines[0] && preprocessed_lines.size < 2
           inner_document_lines.shift
-          inner_document_lines.unshift(*processed_lines)
+          inner_document_lines.unshift(*preprocessed_lines) unless preprocessed_lines.empty?
         end
-      end
-      @inner_document = Document.new(inner_document_lines, :header_footer => false, :parent => @document, :cursor => cursor)
+      end unless inner_document_lines.empty?
+      @inner_document = Document.new(inner_document_lines, :header_footer => false, :parent => @document, :cursor => opts[:cursor])
       @document.attributes['doctitle'] = parent_doctitle unless parent_doctitle.nil?
     end
+    @text = cell_text
+    @style = cell_style
   end
 
-  # Public: Get the text with normal substitutions applied for this cell. Used for cells in the head rows
+  # Public: Get the String text of this cell with substitutions applied.
+  #
+  # Used for cells in the head row as well as text-only (non-AsciiDoc) cells in
+  # the foot row and body.
+  #
+  # This method shouldn't be used for cells that have the AsciiDoc style.
+  #
+  # Returns the converted String text for this Cell
   def text
-    apply_normal_subs(@text).strip
+    apply_subs @text, (@style == :literal ? BASIC_SUBS : NORMAL_SUBS)
+  end
+
+  # Public: Set the String text.
+  #
+  # This method shouldn't be used for cells that have the AsciiDoc style.
+  #
+  # Returns the new String text assigned to this Cell
+  def text= val
+    @text = val
   end
 
   # Public: Handles the body data (tbody, tfoot), applying styles and partitioning into paragraphs
+  #
+  # This method should not be used for cells in the head row or that have the literal or verse style.
+  #
+  # Returns the converted String for this Cell
   def content
     if @style == :asciidoc
       @inner_document.convert
@@ -296,11 +314,24 @@ end
 # instantiated, the row is closed if the cell satisifies the column count and,
 # finally, a new buffer is allocated to track the next cell.
 class Table::ParserContext
+  # Public: An Array of String keys that represent the table formats in AsciiDoc
+  #--
+  # QUESTION should we recognize !sv as a valid format value?
+  FORMATS = ['psv', 'csv', 'dsv', 'tsv'].to_set
+
+  # Public: A Hash mapping the AsciiDoc table formats to default delimiters
+  DELIMITERS = {
+    'psv' => ['|', /\|/],
+    'csv' => [',', /,/],
+    'dsv' => [':', /:/],
+    'tsv' => [%(\t), /\t/],
+    '!sv' => ['!', /!/]
+  }
 
   # Public: The Table currently being parsed
   attr_accessor :table
 
-  # Public: The AsciiDoc table format (psv, dsv or csv)
+  # Public: The AsciiDoc table format (psv, dsv, or csv)
   attr_accessor :format
 
   # Public: Get the expected column count for a row
@@ -319,25 +350,41 @@ class Table::ParserContext
   # Public: The cell delimiter compiled Regexp for this table.
   attr_reader :delimiter_re
 
-  def initialize(reader, table, attributes = {})
+  def initialize reader, table, attributes = {}
     @reader = reader
     @table = table
-    # TODO if reader.cursor becomes a reference, this would require .dup
+    # IMPORTANT if reader.cursor becomes a reference, this assignment would require .dup
     @last_cursor = reader.cursor
-    if (@format = attributes['format'])
-      unless Table::DATA_FORMATS.include? @format
-        raise %(Illegal table format: #{@format})
+
+    if attributes.key? 'format'
+      if FORMATS.include?(xsv = attributes['format'])
+        if xsv == 'tsv'
+          # NOTE tsv is just an alias for csv with a tab separator
+          @format = 'csv'
+        elsif (@format = xsv) == 'psv' && table.document.nested?
+          xsv = '!sv'
+        end
+      else
+        warn %(asciidoctor: ERROR: #{reader.prev_line_info}: illegal table format: #{xsv})
+        @format, xsv = 'psv', (table.document.nested? ? '!sv' : 'psv')
       end
     else
-      @format = Table::DEFAULT_DATA_FORMAT
+      @format, xsv = 'psv', (table.document.nested? ? '!sv' : 'psv')
     end
 
-    @delimiter = if @format == 'psv' && !(attributes.key? 'separator') && table.document.nested?
-      '!'
+    if attributes.key? 'separator'
+      if (sep = attributes['separator']).nil_or_empty?
+        @delimiter, @delimiter_re = DELIMITERS[xsv]
+      # QUESTION should we support any other escape codes or multiple tabs?
+      elsif sep == '\t'
+        @delimiter, @delimiter_re = DELIMITERS['tsv']
+      else
+        @delimiter, @delimiter_re = sep, /#{::Regexp.escape sep}/
+      end
     else
-      attributes['separator'] || Table::DEFAULT_DELIMITERS[@format]
+      @delimiter, @delimiter_re = DELIMITERS[xsv]
     end
-    @delimiter_re = /#{Regexp.escape @delimiter}/
+
     @colcount = table.columns.empty? ? -1 : table.columns.size
     @buffer = ''
     @cellspecs = []
@@ -364,31 +411,36 @@ class Table::ParserContext
     @delimiter_re.match(line)
   end
 
-  # Public: Skip beyond the matched delimiter because it was a false positive
-  # (either because it was escaped or in a quoted context)
+  # Public: Skip past the matched delimiter because it's inside quoted text.
   #
   # returns the String after the match
-  def skip_matched_delimiter(match, escaped = false)
-    @buffer = %(#{@buffer}#{escaped ? match.pre_match.chop : match.pre_match}#{@delimiter})
+  def skip_past_delimiter(match)
+    @buffer = %(#{@buffer}#{match.pre_match}#{@delimiter})
     match.post_match
   end
 
-  # Public: Determines whether the buffer has unclosed quotes. Used for CSV data.
+  # Public: Skip past the matched delimiter because it's escaped.
   #
-  # returns true if the buffer has unclosed quotes, false if it doesn't or it
-  # isn't quoted data
-  def buffer_has_unclosed_quotes?(append = nil)
-    record = %(#{@buffer}#{append}).strip
-    record.start_with?('"') && !record.start_with?('""') && !record.end_with?('"')
+  # returns the String after the match
+  def skip_past_escaped_delimiter(match)
+    @buffer = %(#{@buffer}#{match.pre_match.chop}#{@delimiter})
+    match.post_match
   end
 
-  # Public: Determines whether the buffer contains quoted data. Used for CSV data.
+  # Public: Determines whether the buffer has unclosed quotes. Used for CSV data.
   #
-  # returns true if the buffer starts with a double quote (and not an escaped double quote),
-  # false otherwise
-  def buffer_quoted?
-    @buffer = @buffer.lstrip
-    @buffer.start_with?('"') && !@buffer.start_with?('""')
+  # returns true if the buffer has unclosed quotes, false if it doesn't or it
+  # isn't quoted data
+  def buffer_has_unclosed_quotes? append = nil
+    if (record = append ? (buffer + append).strip : buffer.strip).start_with? '"'
+      if ((trailing_quote = record.end_with? '"') && (record.end_with? '""')) || (record.start_with? '""')
+        ((record = record.gsub '""', '').start_with? '"') && !(record.end_with? '"')
+      else
+        !trailing_quote
+      end
+    else
+      false
+    end
   end
 
   # Public: Takes a cell spec from the stack. Cell specs precede the delimiter, so a
@@ -460,11 +512,11 @@ class Table::ParserContext
   #
   # returns nothing
   def close_cell(eol = false)
-    cell_text = @buffer.strip
-    @buffer = ''
     if @format == 'psv'
-      cellspec = take_cellspec
-      if cellspec
+      strip_text = true
+      cell_text = @buffer
+      @buffer = ''
+      if (cellspec = take_cellspec)
         repeat = cellspec.delete('repeatcol') || 1
       else
         warn %(asciidoctor: ERROR: #{@last_cursor.line_info}: table missing leading separator, recovering automatically)
@@ -472,6 +524,9 @@ class Table::ParserContext
         repeat = 1
       end
     else
+      strip_text = false
+      cell_text = @buffer.strip
+      @buffer = ''
       cellspec = nil
       repeat = 1
       if @format == 'csv'
@@ -482,8 +537,8 @@ class Table::ParserContext
             cell_text = cell_text[1...-1].strip
           end
 
-          # collapses escaped quotes
-          cell_text = cell_text.tr_s('"', '"')
+          # collapse escaped quotes
+          cell_text = cell_text.squeeze('"')
         end
       end
     end
@@ -506,7 +561,7 @@ class Table::ParserContext
         end
       end
 
-      cell = Table::Cell.new(column, cell_text, cellspec, @last_cursor)
+      cell = Table::Cell.new(column, cell_text, cellspec, :cursor => @last_cursor, :strip_text => strip_text)
       @last_cursor = @reader.cursor
       unless !cell.rowspan || cell.rowspan == 1
         activate_rowspan(cell.rowspan, (cell.colspan || 1))

data/lib/asciidoctor/version.rb

@@ -1,3 +1,3 @@
 module Asciidoctor
-  VERSION = '1.5.5'
+  VERSION = '1.5.6'
 end

data/man/asciidoctor.1

@@ -1,13 +1,13 @@
 '\" t
 .\"     Title: asciidoctor
 .\"    Author: Dan Allen, Sarah White, Ryan Waldron
-.\" Generator: Asciidoctor 1.5.5
-.\"      Date: 2016-10-05
+.\" Generator: Asciidoctor 1.5.6
+.\"      Date: 2017-07-12
 .\"    Manual: Asciidoctor Manual
-.\"    Source: Asciidoctor 1.5.5
+.\"    Source: Asciidoctor 1.5.6
 .\"  Language: English
 .\"
-.TH "ASCIIDOCTOR" "1" "2016-10-05" "Asciidoctor 1.5.5" "Asciidoctor Manual"
+.TH "ASCIIDOCTOR" "1" "2017-07-12" "Asciidoctor 1.5.6" "Asciidoctor Manual"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -35,7 +35,7 @@ If \fIFILE\fP is \fI\-\fP then the AsciiDoc source is read from standard input.
 .RS 4
 Base directory containing the document and resources.
 Defaults to the directory containing the source file, or the working directory if the source is read from a stream.
-Can be used as a way to chroot the execution of the program.
+When combined with the safe mode setting, can be used to chroot the execution of the program.
 .RE
 .sp
 \fB\-S, \-\-safe\-mode\fP=\fISAFE_MODE\fP
@@ -48,7 +48,7 @@ If not set, the safe mode level defaults to \fIunsafe\fP when Asciidoctor is inv
 \fB\-\-safe\fP
 .RS 4
 Set safe mode level to \fIsafe\fP.
-Enables include macros, but restricts access to ancestor paths of source file.
+Enables include directives, but prevents access to ancestor paths of source file.
 Provided for compatibility with the asciidoc command.
 If not set, the safe mode level defaults to \fIunsafe\fP when Asciidoctor is invoked using this script.
 .RE
@@ -57,7 +57,7 @@ If not set, the safe mode level defaults to \fIunsafe\fP when Asciidoctor is inv
 \fB\-a, \-\-attribute\fP=\fIATTRIBUTE\fP
 .RS 4
 Define, override or delete a document attribute.
-Command\-line attributes take precedence over attributes defined in the source file.
+Command\-line attributes take precedence over attributes defined in the source file unless the value ends with \fI@\fP.
 .sp
 \fIATTRIBUTE\fP is normally formatted as a key\-value pair, in the form \fINAME=VALUE\fP.
 Alternate acceptable forms are \fINAME\fP (where the \fIVALUE\fP defaults to an empty string), \fINAME!\fP (unassigns the \fINAME\fP attribute) and \fINAME=VALUE@\fP (where \fIVALUE\fP does not override value of \fINAME\fP attribute if it\(cqs already defined in the source document).
@@ -70,8 +70,8 @@ This option may be specified more than once.
 .RS 4
 Backend output file format: \fIhtml5\fP, \fIdocbook5\fP, \fIdocbook45\fP and \fImanpage\fP are supported out of the box.
 You can also use the backend alias names \fIhtml\fP (aliased to \fIhtml5\fP) or \fIdocbook\fP (aliased to \fIdocbook5\fP).
+Other values can be passed, but if Asciidoctor cannot resolve the backend to a converter, it will fail.
 Defaults to \fIhtml5\fP.
-Other options can be passed, but if Asciidoctor cannot find the backend, it will fail during conversion.
 .RE
 .sp
 \fB\-d, \-\-doctype\fP=\fIDOCTYPE\fP
@@ -79,7 +79,7 @@ Other options can be passed, but if Asciidoctor cannot find the backend, it will
 Document type: \fIarticle\fP, \fIbook\fP, \fImanpage\fP or \fIinline\fP.
 Sets the root element when using the \fIdocbook\fP backend and the style class on the HTML body element when using the \fIhtml\fP backend.
 The \fIbook\fP document type allows multiple level\-0 section titles in a single document.
-The \fImanpage\fP document type enables parsing of metadata necessary to produce a manpage.
+The \fImanpage\fP document type enables parsing of metadata necessary to produce a man page.
 The \fIinline\fP document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element.
 Defaults to \fIarticle\fP.
 .RE
@@ -129,9 +129,9 @@ Synonym for \fB\-\-attribute numbered\fP.
 .RS 4
 Write output to file \fIOUT_FILE\fP.
 Defaults to the base name of the input file suffixed with \fIbackend\fP extension.
-If the input is read from standard input, then the output file defaults to stdout.
-If \fIOUT_FILE\fP is \fI\-\fP then the standard output is also used.
-If specified, the file is resolved relative to the working directory.
+The file is resolved relative to the working directory.
+If the input is read from standard input or a named pipe (fifo), then the output file defaults to stdout.
+If \fIOUT_FILE\fP is \fI\-\fP, then the output file is written to standard output.
 .RE
 .sp
 \fB\-r, \-\-require\fP=\fILIBRARY\fP
@@ -180,9 +180,11 @@ Display timings information (time to read, parse and convert).
 .RE
 .SS "Program Information"
 .sp
-\fB\-h, \-\-help\fP
+\fB\-h, \-\-help\fP [\fITOPIC\fP]
 .RS 4
-Show the help message.
+Print the help message.
+Show the command usage if \fITOPIC\fP is not specified (or not recognized).
+Dump the Asciidoctor man page (in troff/groff format) if \fITOPIC\fP is \fImanpage\fP.
 .RE
 .sp
 \fB\-V, \-\-version\fP
@@ -193,7 +195,7 @@ Print program version number.
 .RE
 .SH "ENVIRONMENT"
 .sp
-\fBAsciidoctor\fP honors the SOURCE_DATE_EPOCH environment variable.
+\fBAsciidoctor\fP honors the \fBSOURCE_DATE_EPOCH\fP environment variable.
 If this variable is assigned an integer value, that value is used as the epoch of all input documents and as the local date and time.
 See \c
 .URL "https://reproducible\-builds.org/specs/source\-date\-epoch/" "" " "
@@ -233,7 +235,7 @@ Refer to the \fBAsciidoctor\fP issue tracker at \c
 .URL "http://discuss.asciidoctor.org" "" ""
 .SH "COPYING"
 .sp
-Copyright (C) 2012\-2016 Dan Allen, Ryan Waldron and the Asciidoctor Project.
+Copyright (C) 2012\-2017 Dan Allen, Ryan Waldron and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 .SH "AUTHOR(S)"
 .sp