tex_log_parser 1.0.0.pre.14 → 1.0.0.pre.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9452fd78396c5094be2717ac70979ac88892678f73433966ee1ca79ba21fa73d
-  data.tar.gz: 0e72ee4dc90ca406c2ba557eb017bca1c1a6ae682f9b2847d7f391ac4ddf0483
+  metadata.gz: 04cec17bca7fe8b297a5b35114d1334e3d5f530fba5f1e952672035c55d6627c
+  data.tar.gz: ec8e3cd45e18157f2fddb43b4c610f590792c0784bf857abd6d69b2d811e53f7
 SHA512:
-  metadata.gz: 52cf6f343c49d26fcc9e880301ea082e89f279a65a59ef1bd3c02c25d5810bf05de410224ec28008d55d64b295ea3168b683422b1a85e530a9e886507963da33
-  data.tar.gz: cda1bbf061fb89616784def652834b4020061d020be9c3874099a5bb7b7ed3b165f6343bf00398f3cbdbddae42cf8ab12b41d7dfc87929619c419f2fd56c32e5
+  metadata.gz: 3ce2d48f6d26848b14efecef85d48878cf93e9d5d638a77cf2c8a61af429b0a61364013dace4e5bbf532452dd9290d7dc3359d35b7c322f9bef69491bc893377
+  data.tar.gz: 9a062a9b01e3c467a64ac0166fe054f5e73174745c859d88767abd9faecaabdc8915e3ee879e72ddedf1435991992331a674b6d9392afc01150809ffdf351718

data/README.md

@@ -1,7 +1,7 @@
 # TeXLogParser
 
 [![Gem Version](https://badge.fury.io/rb/tex_log_parser.svg)](https://badge.fury.io/rb/tex_log_parser)
-[![Yard docs](http://img.shields.io/badge/yard-docs-green.svg)](http://www.rubydoc.info/gems/tex_log_parser/1.0.0.pre.2) **˙**
+[![Yard docs](http://img.shields.io/badge/yard-docs-green.svg)](http://www.rubydoc.info/gems/tex_log_parser/1.0.0) **˙**
 [![Maintainability](https://api.codeclimate.com/v1/badges/748992a2c5f6570797d4/maintainability)](https://codeclimate.com/github/reitzig/texlogparser/maintainability) 
 [![Test Coverage](https://api.codeclimate.com/v1/badges/748992a2c5f6570797d4/test_coverage)](https://codeclimate.com/github/reitzig/texlogparser/test_coverage) **˙**
 [![Circle CI](https://circleci.com/gh/reitzig/texlogparser.svg?style=svg)](https://circleci.com/gh/reitzig/texlogparser)

data/lib/log_parser/log_parser.rb

@@ -5,12 +5,39 @@ require 'log_parser/buffer'
 require 'log_parser/message'
 require 'log_parser/pattern'
 
-# TODO: document
+# Parses a log, extracting messages according to a set of {Pattern}.
+#
+# Instances are single-use; create a new one for every log and parsing run.
 module LogParser
+  # @return [Array<Message>]
+  #   the messages this parser found in the given log.
   attr_reader :messages
+
+  # The parser keeps a record of the scope changes it detects.
+  #
+  # **Note:** Only available in debug mode; see {Logger}.
+  #
+  # The keys are line indices.
+  # The values are arrays of strings, with one string per scope change,
+  # in the same order as in the original line.
+  #  * Entering a new scope is denoted by
+  #
+  #     ```
+  #     push filename
+  #     ```
+  #    and
+  #  * leaving a scope by
+  #
+  #     ```
+  #     pop  filename
+  #     ```
+  #     Note the extra space after `pop` here; it's there for quaint cosmetic reasons.
+  #
+  # @return [Hash<Integer, Array<String>>]
+  #   the scope changes this parser detected in the given log.
   attr_reader :scope_changes_by_line if Logger.debug?
 
-  # TODO: document
+  # Parses the given log lines and extracts all messages (of known form).
   # @return [Array<Message>]
   def parse
     skip_empty_lines
@@ -45,25 +72,33 @@ module LogParser
 
   # @abstract
   # @return [Array<Pattern>]
+  #   The set of patterns this parser utilizes to extract messages.
   def patterns
     raise NotImplementedError
   end
 
+  # Extracts scope changes in the form of stack operations from the given line.
+  #
   # @abstract
   # @param [String] _line
-  # @return [Array<String,:pop>] A list of new scopes this line enters (strings)
-  #                              and leaves (`:pop`).
-  #                              Read stack operations from left to right.
+  # @return [Array<String,:pop>]
+  #   A list of new scopes this line enters (filename strings) and leaves (`:pop`).
+  #   Read stack operations from left to right.
   def scope_changes(_line)
     raise NotImplementedError
   end
 
+  # @return [true,false]
+  #   `true` if (and only if) there are no more lines to consume.
   def empty?
     @lines.empty?
   end
 
   private
 
+  # Forwards the internal buffer up to the next line that contains anything but whitespace.
+  #
+  # @return [void]
   def skip_empty_lines
     @lines.first
 
@@ -71,8 +106,12 @@ module LogParser
     remove_consumed_lines(first_nonempty_line || @lines.buffer_size)
   end
 
-  # TODO: document
+  # Reads the log until the next full message, consuming the lines.
+  # Assumes that empty lines have already been skipped.
+  #
   # @return [Message,nil]
+  #   The next message that could be extracted, or `nil` if none could be found.
+  # @raise If parsing already finished.
   def parse_next_lines
     raise 'Parse already done!' if @lines.empty?
 
@@ -102,6 +141,9 @@ module LogParser
     msg
   end
 
+  # After reading `i` lines, remove them from the internal buffer using this method.
+  #
+  # @return [void]
   def remove_consumed_lines(i)
     @lines.forward(i)
     @log_line_number += i
@@ -109,7 +151,15 @@ module LogParser
     @scope_changes_by_line[@log_line_number] = [] if Logger.debug? && i.positive?
   end
 
+  # Consume as many lines as the given pattern will match.
+  # Assumes that `pattern.begins_at?(@lines.first)` is `true`.
+  #
+  # If applying `pattern` is not successful, this method consumes a single line.
+  #
+  # @param [Pattern] pattern
+  #   The pattern to use for matching.
   # @return [Message,nil]
+  #   The message `pattern` produced, if any.
   def consume_pattern(pattern)
     # Apply the pattern, i.e. read the next message!
 
@@ -129,6 +179,9 @@ module LogParser
     return nil
   end
 
+  # Extracts the scope changes from the current line and applies them to the file stack `@files`.
+  #
+  # @return [void]
   def apply_scope_changes
     # In the hope that scope changes happen not on the same
     # line as messages. Gulp.

data/lib/tex_log_parser/patterns/bad_hbox_warning.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 class TexLogParser
-  # TODO: document
+  # Matches messages of this form:
+  #
+  #     Overfull \hbox (68.36201pt too wide) in paragraph at lines 33--34
+  #     []\OT1/cmr/m/n/10 Let's try to for-ce an over-full box: []
+  #     []
+  #
+  # and
+  #
+  #     Underfull \hbox (badness 10000) in paragraph at lines 35--36
+  #
+  #     []
   class BadHboxWarning
     include LogParser::RegExpPattern
 

data/lib/tex_log_parser/patterns/fatal_error_occurred.rb

@@ -3,8 +3,8 @@
 class TexLogParser
   # Matches messages of this form:
   #
-  # !  ==> Fatal error occurred, no output PDF file produced!
-  # Transcript written on plain.log.
+  #     !  ==> Fatal error occurred, no output PDF file produced!
+  #     Transcript written on plain.log.
   class FatalErrorOccurred
     include LogParser::RegExpPattern
 

data/lib/tex_log_parser/patterns/prefixed_multi_line_pattern.rb

@@ -7,7 +7,7 @@ class TexLogParser
   #     (tocbasic)             because of feature `nobabel' available
   #     (tocbasic)             for `toc' on input line 132.
   #
-  # Note: currently fails if lines get broken badly, e.g. in 000.log:634.
+  # **Note:** Fails to pick up the fill message if lines get broken badly, e.g. in `000_pdf_fl.log:634`.
   class PrefixedMultiLinePattern
     include LogParser::RegExpPattern
 

data/lib/tex_log_parser.rb

@@ -4,6 +4,9 @@ require 'log_parser/log_parser'
 Dir["#{File.expand_path(__dir__)}/tex_log_parser/patterns/*.rb"].each { |p| require p }
 
 # Parses logs (and output) of LaTeX interpreters, e.g. `pdflatex`, `xelatex` and `lualatex`.
+# Messages are extracted according to a set of patterns (see below).
+#
+# Instances are single-use; create a new one for every log and parsing run.
 #
 # *Note:* Due to shortcomings in the native format of those logs, please be
 # aware of these recommendations:
@@ -24,7 +27,8 @@ class TexLogParser
 
   protected
 
-  # (see LogParser#patterns)
+  # @return [Array<Pattern>]
+  #   The set of patterns this parser utilizes to extract messages.
   def patterns
     [HighlightedMessages.new,
      FileLineError.new,
@@ -35,9 +39,15 @@ class TexLogParser
      BadHboxWarning.new]
   end
 
-  # (see LogParser#scope_changes)
+  # Extracts scope changes in the form of stack operations from the given line.
+  #
+  # @param [String] line
+  # @return [Array<String,:pop>]
+  #   A list of new scopes this line enters (filename strings) and leaves (`:pop`).
+  #   Read stack operations from left to right.
+  #
   #
-  # _Implementation note:_ The basic format in LaTeX logs is that
+  # *Implementation note:* The basic format in LaTeX logs is that
   #  * `(filename` marks the beginning of messages from that file, and
   #  * the matching `)` marks the end.
   # Those nest, of course.
@@ -67,6 +77,13 @@ class TexLogParser
         # Scopes close on a dedicated line, except if they don't (cf 000.log:624)
         # So we have to continue on the rest of the line. Uh oh.
         ([:pop] * Regexp.last_match(1).length) + scope_changes(Regexp.last_match(2))
+      when /v.*? \d{4}-\d{2}-\d{2}\)(.*)$/
+        # Apparently, some nasty packages write their version number in front
+        # of the closing parenthesis, despite otherwise adhering to the format.
+        # See e.g. `002_pdf_fl.log:12`.
+        # This is a fix specifically for that situation -- let's hope that there
+        # are not many more similar ones.
+        [:pop] + scope_changes(Regexp.last_match(2))
       when /\([^)]*$/
         # BROKEN_BY_LINEBREAKS
         # Bad linebreaks can cause trailing ) to spill over. Narf.

data/lib/version.rb

@@ -3,5 +3,5 @@
 # @attr [String] VERSION
 #   The version of TexLogParser.
 class TexLogParser
-  VERSION = '1.0.0.pre.14'
+  VERSION = '1.0.0.pre.15'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tex_log_parser
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.14
+  version: 1.0.0.pre.15
 platform: ruby
 authors:
 - Raphael Reitzig
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement