More restructuring and documentation.

 - Moved concrete patterns into TexLogParser class.
 - Logger moved into LogParser module.
 - Circle steps now output Ruby and Gem versions.

Author: reitzig

.circleci/config.yml

@@ -9,104 +9,115 @@ jobs:
       - run:
           name: Prepare Ruby environment
           command: |
+            ruby --version
+            echo "gem `gem --version`"
             gem update --system
             gem install bundler
             bundle install
       - run: rake test
   test-2.4:
-      docker:
-        - image: circleci/ruby:2.4
-      steps:
-        - checkout
-        - run:
-            name: Prepare Ruby environment
-            command: |
-              gem update --system
-              gem install bundler
-              bundle install
-        - run: rake test
+    docker:
+      - image: circleci/ruby:2.4
+    steps:
+      - checkout
+      - run:
+          name: Prepare Ruby environment
+          command: |
+            ruby --version
+            echo "gem `gem --version`"
+            gem update --system
+            gem install bundler
+            bundle install
+      - run: rake test
   test-2.5:
-      docker:
-        - image: circleci/ruby:2.5
-      steps:
-        - checkout
-        - run:
-            name: Prepare Ruby environment
-            command: |
-              gem update --system
-              gem install bundler
-              bundle install
-        - run: rake test
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      - checkout
+      - run:
+          name: Prepare Ruby environment
+          command: |
+            ruby --version
+            echo "gem `gem --version`"
+            gem update --system
+            gem install bundler
+            bundle install
+      - run: rake test
   build:
-      docker:
-        - image: circleci/ruby:2.5
-      steps:
-        - checkout
-        - run:
-            name: Prepare Ruby environment
-            command: |
-              gem update --system
-              gem install bundler
-              bundle install
-        - run:
-            name: Build Gem
-            command: gem build texlogparser.gemspec
-        - persist_to_workspace:
-            root: .
-            paths:
-              - .circleci/gem_credentials
-              - tex_log_parser*.gem
-              - test/texlogs/*.log
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      - checkout
+      - run:
+          name: Prepare Ruby environment
+          command: |
+            ruby --version
+            echo "gem `gem --version`"
+            gem update --system
+            gem install bundler
+            bundle install
+      - run:
+          name: Build Gem
+          command: gem build texlogparser.gemspec
+      - persist_to_workspace:
+          root: .
+          paths:
+            - .circleci/gem_credentials
+            - tex_log_parser*.gem
+            - test/texlogs/*.log
   doc:
-      docker:
-        - image: circleci/ruby:2.5
-      steps:
-        - checkout
-        - run:
-            name: Prepare Ruby environment
-            command: |
-              gem update --system
-              gem install bundler
-              bundle install
-        - run:
-            name: Build Documentation
-            command: bundle exec rake doc
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      - checkout
+      - run:
+          name: Prepare Ruby environment
+          command: |
+            ruby --version
+            echo "gem `gem --version`"
+            gem update --system
+            gem install bundler
+            bundle install
+      - run:
+          name: Build Documentation
+          command: rake doc
   test-cli:
-      docker:
-        - image: circleci/ruby:2.5
-      steps:
-        - attach_workspace:
-            at: .
-        - run:
-            name: Install Gem
-            command: gem install tex_log_parser*.gem
-        - run:
-           name: Test version output
-           command: texlogparser -v
-        - run:
-            name: Test an actual log
-            command: texlogparser -i `ls -d1 test/texlogs/*.log | head -1`
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      - attach_workspace:
+          at: .
+      - run:
+          name: Install Gem
+          command: gem install tex_log_parser*.gem
+      - run:
+         name: Test version output
+         command: texlogparser -v
+      - run:
+          name: Test an actual log
+          command: texlogparser -i `ls -d1 test/texlogs/*.log | head -1`
   deploy:
-      docker:
-        - image: circleci/ruby:2.5
-      steps:
-        - attach_workspace:
-            at: .
-        - run:
-            name: Deploy Gem
-            command: |
-              cat .circleci/gem_credentials | sed -e "s/__RUBYGEMS_API_KEY__/${RUBYGEMS_API_KEY}/" > ~/.gem/credentials
-              gem push tex_log_parser*.gem
-              shred -u ~/.gem/credentials
-      filters:
-        branches:
-          ignore: /.*/
-        tags:
-          only: /^v.*/
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      - attach_workspace:
+          at: .
+      - run:
+          name: Deploy Gem
+          command: |
+            echo "gem `gem --version`"
+            cat .circleci/gem_credentials | sed -e "s/__RUBYGEMS_API_KEY__/${RUBYGEMS_API_KEY}/" > ~/.gem/credentials
+            gem push tex_log_parser*.gem
+            shred -u ~/.gem/credentials
+    filters:
+      branches:
+        ignore: /.*/
+      tags:
+        only: /^v.*/
 
 workflows:
   version: 2
-  test:
+  test-and-deploy:
     jobs:
       - test-2.3
       - test-2.4

Rakefile

@@ -14,7 +14,7 @@ desc 'Build documentation'
 YARD::Rake::YardocTask.new do |t|
   t.name = 'doc'
   # t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
-  t.options = %w(--markup-provider=redcarpet --markup=markdown --main=README.md)
+  t.options = %w[--markup-provider=redcarpet --markup=markdown --main=README.md]
 end
 
 task default: :test

bin/texlogparser

@@ -17,7 +17,7 @@ formats = %i[file_line json]
 OptionParser.new do |opts|
   opts.banner = 'Usage: texlogparser [options]'
   opts.on('-d', '--debug', 'Output debug information') do
-    Logger.debugging = true
+    LogParser::Logger.debug = true
   end
   opts.on('-f ENUM', '--format ENUM', formats,
           'Output format', "One of: #{formats.map(&:to_s).join(', ')}") do |format|
@@ -39,7 +39,7 @@ OptionParser.new do |opts|
     exit
   end
   opts.on_tail('-v', '--version', 'Show version') do
-    puts TexLogParser::VERSION
+    puts "#{File.basename(__FILE__)} #{TexLogParser::VERSION}"
     exit
   end
 
@@ -58,7 +58,7 @@ end
 
 input = STDIN
 input = File.open(options[:input], 'r') if options[:input].is_a?(String)
-parser = TexLogParser.new(input, options)
+parser = TexLogParser.new(input)
 messages = parser.parse
 
 output = STDOUT

lib/log_parser/buffer.rb

@@ -103,12 +103,15 @@ def [](offset, length = nil)
     #
     # @param [Integer] offset
     #   The number of lines to drop.
+    # @return [void]
     def forward(offset = 1)
       self[offset]
       @buffer.slice!(0, offset)
     end
 
     # Closes the `IO` this buffer reads from, if any.
+    #
+    # @return [void]
     def close
       @stream.close unless @stream.nil? || @stream.closed?
     end

lib/log_parser/log_parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'log_parser/logger'
 require 'log_parser/buffer'
 require 'log_parser/message'
 require 'log_parser/pattern'
@@ -10,9 +11,28 @@ module LogParser
   attr_reader :scope_changes_by_line if Logger.debug?
 
   # TODO: document
+  # @return [Array<Message>]
+  def parse
+    skip_empty_lines
+    until empty?
+      parse_next_lines
+      skip_empty_lines
+    end
+
+    # TODO: Remove duplicates?
+    @messages
+  end
+
+  protected
+
+  # Creates a new instance.
+  #
+  # This parser will read lines one by one from the given `log`.
+  # If it is an `IO` or `StringIO`, only those lines currently under investigation will be kept in memory.
+  #
   # @param [Array<String>,IO,StringIO] log
-  # @param [Hash] _options
-  def initialize(log, _options = {})
+  #   A set of log lines that will be parsed.
+  def initialize(log)
     @files = []
 
     @messages = []
@@ -23,11 +43,13 @@ def initialize(log, _options = {})
     @scope_changes_by_line = {} if Logger.debug?
   end
 
+  # @abstract
   # @return [Array<Pattern>]
   def patterns
     raise NotImplementedError
   end
 
+  # @abstract
   # @param [String] _line
   # @return [Array<String,:pop>] A list of new scopes this line enters (strings)
   #                              and leaves (`:pop`).
@@ -40,19 +62,6 @@ def empty?
     @lines.empty?
   end
 
-  # TODO: document
-  # @return [Array<Message>]
-  def parse
-    skip_empty_lines
-    until empty?
-      parse_next_lines
-      skip_empty_lines
-    end
-
-    # TODO: Remove duplicates?
-    @messages
-  end
-
   private
 
   def skip_empty_lines

lib/log_parser/logger.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module LogParser
+  # A simple helper, probably to be replaced by a proper logging library
+  # at some point.
+  class Logger
+    class << self
+      # Switches debugging mode on and off.
+      #
+      # @param [true,false] flag
+      # @return [void]
+      def debug=(flag)
+        @debugging = flag
+      end
+
+      # Indicates whether we are debugging.
+      #
+      # @return [true,false]
+      #   `true` if we are in debugging mode, `false` otherwise.
+      def debug?
+        @debugging || !ENV['DEBUG'].nil?
+      end
+
+      # Logs the given message to STDOUT if `debug?` is true.
+      #
+      # @param [String] message
+      # @return [void]
+      def debug(message)
+        puts message if debug?
+      end
+    end
+  end
+end

lib/log_parser/message.rb

@@ -38,6 +38,9 @@ def initialize(message:, source_file: nil, source_lines: nil, log_lines: nil,
     attr_accessor :message, :source_file, :source_lines, :log_lines,
                   :preformatted, :level
 
+    # Convert this message to a file-line string representation.
+    #
+    # @return [String]
     def to_s
       lines = if @source_lines.nil?
                 ''
@@ -56,6 +59,10 @@ def to_s
       MSG
     end
 
+    # Convert this message to JSON.
+    #
+    # @return [String]
+    #   The JSON string representing this message.
     def to_json(_options = {})
       hash = {
         level: @level,