asciidoctor-reducer 1.0.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b897d6327d17f704a62f21f7649a2ae1a4f2643bf7f8f41445c126aafbf77e2
+  data.tar.gz: d3c11b63175f9f235f459a2c8822d0ee2d08e2762f2cab5273f30c238797db49
+SHA512:
+  metadata.gz: 421524a636890420cebe721455f2ba348cb514b8b576d125c1baa2d9e474297a2763b3c325d7c8948e7bd12d28276f8e27b5171cfecc0d92be62b1f1e8094f11
+  data.tar.gz: 7c148e99347aaf86474d376b80e8beb7a35cb96fe211ace49c5ba6a8e8a8bfb40716225c995107407ff3c13c9f3e850f8fc3b83ce9e4e172102b719a2ef48dca

data/CHANGELOG.adoc

@@ -0,0 +1,13 @@
+= Asciidoctor Reducer Changelog
+:url-repo: https://github.com/asciidoctor/asciidoctor-reducer
+
+This document provides a high-level view of the changes to the Asciidoctor Reducer by release.
+For a detailed view of what has changed, refer to the {url-repo}/commits/main[commit history] on GitHub.
+
+== 1.0.0.alpha.1 (2022-01-12) - @mojavelinux
+
+Initial release.
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.1[git tag]

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2021 Dan Allen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,113 @@
+= Asciidoctor Reducer
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
+v1.0.0.alpha.1, 2022-01-12
+:idprefix:
+:idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github[]
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+:url-rvm: https://rvm.io
+
+Asciidoctor Reducer is a tool that reduces an AsciiDoc document with includes to a single document by expanding the includes reachable from the specified parent document.
+If the document does not contain any includes, the tool returns the original source.
+
+== Prerequisites
+
+To install and run Asciidoctor Reducer, you need Ruby 2.5 or better installed and the Asciidoctor gem.
+The instructions for installing the gems is covered in the next section.
+
+To check whether you have Ruby installed, and which version, run the following command:
+
+ $ ruby -v
+
+If Ruby is not installed, you can install it using {url-rvm}[RVM] (or, if you prefer, the package manager for your system).
+We generally recommend using RVM because it allows you to install gems without requiring elevated privileges or messing with system libraries.
+
+== Installation
+
+Asciidoctor Reducer is published to RubyGems.org as the gem named *asciidoctor-reducer*.
+
+You can install the latest version of the gem using the following command:
+
+ $ gem install asciidoctor-reducer --pre
+
+Installing this gem makes the `asciidoctor-reducer` command available on your $PATH.
+You can also require the gem to use it as an Asciidoctor extension.
+
+== Usage
+
+=== As command
+
+You can run this tool using the provided command (i.e., CLI), named `asciidoctor-reducer`.
+To learn how to use the command, and to verify it's available, run the command with the `-h` option:
+
+ $ asciidoctor-reducer -h
+
+On the first line of the help text, you'll see a synopsis of the command:
+
+....
+asciidoctor-reducer [OPTION]... FILE
+....
+
+The argument `FILE` is the AsciiDoc file you want to reduce.
+To use the command, pass the AsciiDoc file as the sole argument:
+
+ $ asciidoctor-reducer input.adoc
+
+By default, the command will output the reduced AsciiDoc document to the terminal (via stdout).
+To write the output to a file, specify an output file using the `-o` option.
+
+ $ asciidoctor-reducer -o output.adoc input.adoc
+
+The command can also read the input document from stdin instead of a file.
+To use the command in this way, pass `-` as the first argument:
+
+ $ cat input.adoc | asciidoctor-reducer -
+
+To write the output to a file, also specify the `-o` option:
+
+ $ cat input.adoc | asciidoctor-reducer -o output.adoc -
+
+Note that top-level include files in the input AsciiDoc document are resolved relative to current working directory.
+
+=== As extension
+
+You can use this tool as an Asciidoctor extension when using the Asciidoctor API.
+To do so, require it before calling the `Asciidoctor.load` method.
+
+[,ruby]
+----
+require 'asciidoctor/reducer'
+----
+
+Next, load a parent document that contains includes.
+
+[,ruby]
+----
+doc = Asciidoctor.load_file 'sample.adoc', safe: :safe
+----
+
+Finally, you can retrieve the reduced source from the returned document.
+
+[,ruby]
+----
+puts doc.source
+----
+
+You can write this source to a file to save the reduced document.
+
+== Copyright and License
+
+Copyright (C) 2021-present Dan Allen.
+Use of this software is granted under the terms of the MIT License.
+
+See the link:LICENSE[LICENSE] for the full license text.
+
+== Trademarks
+
+AsciiDoc(R) and AsciiDoc Language(TM) are trademarks of the Eclipse Foundation, Inc.

data/asciidoctor-reducer.gemspec

@@ -0,0 +1,41 @@
+begin
+  require_relative 'lib/asciidoctor/reducer/version'
+rescue LoadError
+  require 'asciidoctor/reducer/version'
+end
+
+Gem::Specification.new do |s|
+  s.name = 'asciidoctor-reducer'
+  s.version = Asciidoctor::Reducer::VERSION
+  # Reduces a set of AsciiDoc documents into a single document by expanding all includes reachable from the parent document.
+
+  s.summary = 'Reduces an AsciiDoc document with includes to a single AsciiDoc document.'
+  s.description = 'A tool that reduces an AsciiDoc document with includes to a single AsciiDoc document by expanding the includes reachable from the specified parent document.'
+  s.authors = ['Dan Allen']
+  s.email = 'dan.j.allen@gmail.com'
+  s.homepage = 'https://asciidoctor.org'
+  s.license = 'MIT'
+  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
+  #s.required_ruby_version = '>= 2.5.0'
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-reducer/issues',
+    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-reducer/blob/main/CHANGELOG.adoc',
+    'mailing_list_uri' => 'https://asciidoctor.zulipchat.com',
+    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-reducer'
+  }
+
+  # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available
+  begin
+    files = (result = `git ls-files -z`.split ?\0).empty? ? Dir['**/*'] : result
+  rescue
+    files = Dir['**/*']
+  end
+  s.files = files.grep %r/^(?:lib\/.+|LICENSE|(?:CHANGELOG|README)\.adoc|#{s.name}\.gemspec)$/
+  s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'asciidoctor', '~> 2.0'
+
+  s.add_development_dependency 'rake', '~> 13.0.0'
+  s.add_development_dependency 'rspec', '~> 3.10.0'
+end

data/bin/asciidoctor-reducer

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+asciidoctor_reducer = File.absolute_path '../lib/asciidoctor/reducer', __dir__
+if File.exist? asciidoctor_reducer
+  require asciidoctor_reducer
+else
+  require 'asciidoctor/reducer'
+end
+
+require 'asciidoctor/reducer/cli'
+
+exit Asciidoctor::Reducer::Cli.run

data/lib/asciidoctor/reducer/cli.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+autoload :OptionParser, 'optparse'
+autoload :Pathname, 'pathname'
+
+module Asciidoctor::Reducer
+  autoload :VERSION, (::File.join __dir__, 'version.rb')
+
+  class Cli
+    def parse args
+      options = {}
+
+      opt_parser = ::OptionParser.new do |opts|
+        opts.program_name = 'asciidoctor-reducer'
+        opts.banner = <<~EOS
+        Usage: #{opts.program_name} [OPTION]... FILE
+
+        Reduces an AsciiDoc document with includes to a single AsciiDoc document.
+
+        EOS
+
+        opts.on '-o FILE', '--output=FILE', 'Set the output filename or stream' do |file|
+          options[:output_file] = file
+        end
+
+        opts.on '-h', '--help', 'Display this help text and exit' do
+          $stdout.write opts.help
+          return 0
+        end
+
+        opts.on '-v', '--version', %(Display version information and exit) do
+          $stdout.write %(#{opts.program_name} #{::Asciidoctor::Reducer::VERSION}\n)
+          return 0
+        end
+      end
+
+      args = opt_parser.parse args
+
+      if args.empty?
+        opt_parser.warn 'Please specify an AsciiDoc file to reduce.'
+        $stdout.write opt_parser.help
+        1
+      elsif args.size == 1
+        options[:input_file] = args[0]
+        options[:output_file] = '-' unless options[:output_file]
+        [0, options]
+      else
+        opt_parser.warn %(extra arguments detected (unparsed arguments: #{(args.drop 1).join ' '}))
+        $stdout.write opt_parser.help
+        [1, options]
+      end
+    rescue ::OptionParser::InvalidOption
+      $stderr.write %(#{opt_parser.program_name}: #{$!.message}\n)
+      $stdout.write opt_parser.help
+      1
+    end
+
+    def self.run args = ARGV
+      code, options = new.parse (Array args)
+      return code unless code == 0 && options
+      if (output_file = options.delete :output_file) == '-'
+        to = $stdout
+      else
+        (to = ::Pathname.new output_file).dirname.mkpath
+      end
+      if (input_file = options.delete :input_file) == '-'
+        reduced = (Asciidoctor.load $stdin, safe: :safe).source + ?\n
+      else
+        reduced = (Asciidoctor.load_file input_file, safe: :safe, to_file: false).source + ?\n
+      end
+      Pathname === to ? (to.write reduced, encoding: ::Encoding::UTF_8) : (to.write reduced)
+      0
+    rescue ::IOError
+      $stderr.write %(asciidoctor-reducer: #{$!.message}\n)
+      1
+    end
+  end
+end

data/lib/asciidoctor/reducer/ext/asciidoctor/preprocessor_reader.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Reducer
+  module AsciidoctorExt
+    module PreprocessorReader
+      def preprocess_include_directive target, attrlist
+        @x_include_directive_line = %(include::#{target}[#{attrlist}])
+        @x_push_include_called = false
+        inc_lineno = @lineno - 1 # we're currently on the include line, which is 1-based
+        result = super
+        return result if @x_push_include_called
+        parent_depth = (parents = @x_parents).length
+        depth_change = @include_stack.length - (parent_depth - 1)
+        parent_depth -= (parents.slice! parent_depth + depth_change, -depth_change).length if depth_change < 0
+        lines = ((line = @lines[-1].to_s).start_with? 'Unresolved directive in ') && (line.end_with? ']') ? [line] : []
+        @x_include_replacements << {
+          lines: lines,
+          into: parents[parent_depth - 1],
+          index: inc_lineno,
+          replace: @x_include_directive_line,
+        }
+      end
+
+      def push_include data, file, path, lineno, attrs
+        @x_push_include_called = true
+        inc_lineno = @lineno - 2 # we're below the include line, which is 1-based
+        prev_inc_depth = @include_stack.length
+        # Q: can we do this without resetting the lineno?
+        lineno = 1 # rubocop:disable Lint/ShadowedArgument
+        super
+        inc_depth = @include_stack.length
+        parent_depth = (parents = @x_parents).length
+        # push_include did not push to the stack
+        if inc_depth == prev_inc_depth
+          depth_change = inc_depth - (parent_depth - 1)
+          parent_depth -= (parents.slice! parent_depth + depth_change, -depth_change).length if depth_change < 0
+          @x_include_replacements << {
+            lines: [],
+            into: parents[parent_depth - 1],
+            index: inc_lineno,
+            replace: @x_include_directive_line,
+          }
+        else
+          depth_change = inc_depth - parent_depth
+          if depth_change > 0
+            parents << @x_include_replacements.length.pred
+            parent_depth += 1
+          elsif depth_change < 0
+            parent_depth -= (parents.slice! parent_depth + depth_change, -depth_change).length
+          end
+          @x_include_replacements << {
+            lines: @lines.reverse,
+            into: parents[parent_depth - 1],
+            index: inc_lineno,
+            replace: @x_include_directive_line,
+          }
+        end
+        self
+      end
+    end
+  end
+end

data/lib/asciidoctor/reducer/extensions.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'preprocessor'
+require_relative 'tree_processor'

data/lib/asciidoctor/reducer/preprocessor.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'ext/asciidoctor/preprocessor_reader'
+
+module Asciidoctor::Reducer
+  class Preprocessor < ::Asciidoctor::Extensions::Preprocessor
+    def process doc, reader
+      return if doc.options[:reduced]
+      doc.sourcemap = true
+      # Q: is there a better place we can store the original logger?
+      ::Asciidoctor::LoggerManager.instance_variable_set :@original_logger, ::Asciidoctor::LoggerManager.logger
+      ::Asciidoctor::LoggerManager.logger = ::Asciidoctor::NullLogger.new
+      reader.singleton_class.prepend AsciidoctorExt::PreprocessorReader
+      reader.instance_variable_set :@x_include_replacements, []
+      reader.instance_variable_set :@x_parents, [-1]
+      nil
+    end
+  end
+end

data/lib/asciidoctor/reducer/tree_processor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Reducer
+  class TreeProcessor < ::Asciidoctor::Extensions::TreeProcessor
+    def process doc
+      return if doc.options[:reduced]
+      unless (inc_replacements = doc.reader.instance_variable_get :@x_include_replacements).empty?
+        resolved_source_lines = doc.source_lines.dup
+        inc_replacements.reverse_each do |it|
+          # when into is -1, it indicates this is a top-level include
+          target_lines = (into = it[:into]) < 0 ? resolved_source_lines : inc_replacements[into][:lines]
+          # adds extra bit of assurance that we're replacing the correct line
+          if target_lines[(index = it[:index])] == it[:replace]
+            target_lines[index..index] = it[:lines]
+          end
+        end
+        # WARNING: if include directives remain that can still be resolved, the sourcemap won't match the source lines
+        doc = ::Asciidoctor.load resolved_source_lines, (doc.options.merge sourcemap: true, reduced: true)
+      end
+      ::Asciidoctor::LoggerManager.logger = ::Asciidoctor::LoggerManager.instance_variable_get :@original_logger
+      ::Asciidoctor::LoggerManager.remove_instance_variable :@original_logger
+      doc
+    end
+  end
+end

data/lib/asciidoctor/reducer/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Reducer
+    VERSION = '1.0.0.alpha.1'
+  end
+end

data/lib/asciidoctor/reducer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'asciidoctor'
+require_relative 'reducer/extensions'
+
+Asciidoctor::Extensions.register do
+  preprocessor Asciidoctor::Reducer::Preprocessor
+  tree_processor Asciidoctor::Reducer::TreeProcessor
+end

data/lib/asciidoctor-reducer.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'asciidoctor/reducer'

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-reducer
+version: !ruby/object:Gem::Version
+  version: 1.0.0.alpha.1
+platform: ruby
+authors:
+- Dan Allen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-01-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.10.0
+description: A tool that reduces an AsciiDoc document with includes to a single AsciiDoc
+  document by expanding the includes reachable from the specified parent document.
+email: dan.j.allen@gmail.com
+executables:
+- asciidoctor-reducer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.adoc
+- LICENSE
+- README.adoc
+- asciidoctor-reducer.gemspec
+- bin/asciidoctor-reducer
+- lib/asciidoctor-reducer.rb
+- lib/asciidoctor/reducer.rb
+- lib/asciidoctor/reducer/cli.rb
+- lib/asciidoctor/reducer/ext/asciidoctor/preprocessor_reader.rb
+- lib/asciidoctor/reducer/extensions.rb
+- lib/asciidoctor/reducer/preprocessor.rb
+- lib/asciidoctor/reducer/tree_processor.rb
+- lib/asciidoctor/reducer/version.rb
+homepage: https://asciidoctor.org
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/asciidoctor/asciidoctor-reducer/issues
+  changelog_uri: https://github.com/asciidoctor/asciidoctor-reducer/blob/main/CHANGELOG.adoc
+  mailing_list_uri: https://asciidoctor.zulipchat.com
+  source_code_uri: https://github.com/asciidoctor/asciidoctor-reducer
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.2.32
+signing_key: 
+specification_version: 4
+summary: Reduces an AsciiDoc document with includes to a single AsciiDoc document.
+test_files: []