asciidoctor-reducer 1.0.0.alpha.6 → 1.0.0.alpha.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30089ea8ab059ef848713ada56dd9457f4d6681c80de8028b92a9d02b21b0544
-  data.tar.gz: f38c68d1f15627a4d74fd5376fb3ec9a5b6ad29345c10ea882ff988c875922a9
+  metadata.gz: 2a685ae408de9db32a7ec96055b70120ea6f7476436dca071cc37155cc680d56
+  data.tar.gz: 39d783c66481423417d64a232ee01bdaa88bef517474d22e8ec9fdeb670d09d9
 SHA512:
-  metadata.gz: a3ec843b92513164762d9647d963238073bff89c66619205166b26199a23e65d85ee5aaf23c2a60c953eae52d17ed36cbb7499dd7afb2040692912065171db12
-  data.tar.gz: df40e3f0c244ed21ea052536844df17f536c84a12252008d1c7dbdc04ad85ec00f3aabae81242550eda9a394497db386bd12b34f5110f323f61a8bdbc8ec30c6
+  metadata.gz: a3376645764a9d608f3e3aad5f29f2080748d9ecd20d90a06e2335263cdd7c88c0450a72ea061f8f36c17fa19af0f985a89002ee70e12ce950f4320c483b8140
+  data.tar.gz: a7899259cf2ff2daf619d13b97d88dd460a013b0bc85d2c8402e1283f1b3d6fff3780bc3c112e4c281463ad06e0bcb035385998771528a01e3aac487dd7c6e09

data/CHANGELOG.adoc

@@ -4,6 +4,25 @@
 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.7 (2022-02-14) - @mojavelinux
+
+=== Added
+
+* Add asciidoctor/reducer/api to require main API (#3)
+* Add `Asciidoctor::Reducer.reduce` and `Asciidoctor::Reducer.reduce_file` API methods (#3)
+* Add asciidoctor/reducer/extensions to require extensions API (#3)
+* Add `Asciidoctor::Reducer::Extensions` API (#3)
+
+=== Changed
+
+* Scope extensions to single call instead of registering them globally (#3)
+* Use `:safe` as the default safe mode when using the API
+* Make `CurrentPosition` module private to the `PreprocessorDirectiveTracker` module
+
+=== Fixed
+
+* Require asciidoctor/reducer/version automatically when `Asciidoctor::Reducer::VERSION` is accessed
+
 == 1.0.0.alpha.6 (2022-02-10) - @mojavelinux
 
 === Added
@@ -98,3 +117,7 @@ Initial release.
 === Details
 
 {url-repo}/releases/tag/v1.0.0.alpha.6[git tag]
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.7[git tag]

data/README.adoc

@@ -1,6 +1,6 @@
 = {project-name}
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
-v1.0.0.alpha.6, 2022-02-10
+v1.0.0.alpha.7, 2022-02-14
 :idprefix:
 :idseparator: -
 ifndef::env-github[:icons: font]
@@ -22,10 +22,10 @@ If the document does not contain any preprocessor directives, the tool returns t
 
 == Prerequisites
 
-{project-name} is a Ruby program that you install using Ruby packaging.
+{project-name} is a Ruby application that you install using Ruby packaging.
 To install and run {project-name}, you need Ruby 2.5 or better.
 
-Run the following command to check whether you have Ruby installed and to check which version:
+Run the following command to check which version of Ruby you have installed, if any:
 
  $ ruby -v
 
@@ -41,7 +41,9 @@ 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 into the Ruby runtime to use it as an Asciidoctor extension.
+You can also require the gem into the Ruby runtime to use it as a library or Asciidoctor extension.
+
+=== Project-scoped
 
 If you prefer to manage the application as a project-scoped dependency, you can declare the gem in the project's [.path]_Gemfile_:
 
@@ -61,7 +63,7 @@ Installing the gem this way makes the `bundle exec asciidoctor-reducer` command
 
 == Usage
 
-=== As command
+=== 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:
@@ -75,7 +77,7 @@ asciidoctor-reducer [OPTION]... FILE
 ....
 
 The argument `FILE` is the AsciiDoc file you want to reduce.
-The options, represented by `[OPTION]...`, are optional, as the name suggestions.
+The options, represented by `+[OPTION]...+`, are optional, as the name suggestions.
 
 Thus, to use the command, pass the AsciiDoc file as the sole argument:
 
@@ -91,27 +93,26 @@ To use the command in this way, pass `-` as the first argument:
 
  $ cat input.adoc | asciidoctor-reducer -
 
-To write the output to a file instead of stdout, also specify an output file using the `-o` option:
+To write the output to a file in this case, specify an output file using 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
+=== API
 
-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.
+You can also use this tool from a Ruby application using the provided API.
+To begin, require the API for this library.
 
 [,ruby]
 ----
-require 'asciidoctor/reducer'
+require 'asciidoctor/reducer/api'
 ----
 
-Next, load a parent document that contains includes.
+Next, reduce a parent document that contains includes.
+This works without having to specify the safe mode since the default safe mode when using the API is `:safe`.
 
 [,ruby]
 ----
-doc = Asciidoctor.load_file 'sample.adoc', safe: :safe
+doc = Asciidoctor::Reducer.reduce_file 'sample.adoc'
 ----
 
 Finally, you can retrieve the reduced source from the returned document.
@@ -121,11 +122,60 @@ Finally, you can retrieve the reduced source from the returned document.
 puts doc.source
 ----
 
-You can write this source to a file to save the reduced document.
+The benefit of this approach is that you can access the reduced source and the parsed document that corresponds to it.
+
+If you don't need the parsed document, you can retrieve the reduced source directly by passing the `String` type to the `:to` option:
+
+[,ruby]
+----
+puts Asciidoctor::Reducer.reduce_file 'sample.adoc', to: String
+----
+
+You can write the reduced source directly to a file by passing a file path to the `:to` option:
+
+[,ruby]
+----
+Asciidoctor::Reducer.reduce_file 'sample.adoc', to: 'sample-reduced.adoc'
+----
+
+== Extension
+
+Instead of using the API for this library, you can use the load API provided by Asciidoctor.
+If you want to register the extension globally, require the library as follows:
+
+[,ruby]
+----
+require 'asciidoctor/reducer'
+----
+
+When you use the Asciidoctor load API, the document will automatically be reduced.
+
+[,ruby]
+----
+puts (Asciidoctor.load_file 'sample.adoc', safe: :safe).source
+----
+
+If you want to keep the extension scoped to the call, require the library as follows:
+
+[,ruby]
+----
+require 'asciidoctor/reducer/extensions'
+----
+
+Next, use the extensions API to prepare an extension registry and pass it to the Asciidoctor load API:
+
+[,ruby]
+----
+puts (Asciidoctor.load_file 'sample.adoc', safe: :safe, extension_registry: Asciidoctor::Reducer.prepare_registry).source
+----
+
+Working with the extension directly is intended for low-level operations.
+Most of the time, you should use the API provided by this library.
 
 == How it Works
 
 {project-name} uses a collection of Asciidoctor extensions to rebuild the AsciiDoc source as a single document.
+Top-level include files in the input AsciiDoc document are resolved relative to current working directory.
 
 It starts by using a preprocessor extension to enhance the PreprocessorReader class to be notified each time an include is entered (pushed) or exited (popped).
 When an include directive is encountered, the enhanced reader stores the resolved lines and location of the include directive, thus keeping track of where those lines should be inserted in the original source.
@@ -191,7 +241,7 @@ For more fine-grained control, you can also run the tests directly using RSpec:
 
 To run all tests in a single spec, point RSpec at the spec file:
 
- $ bundle exec rspec spec/asciidoctor_reducer_spec.rb
+ $ bundle exec rspec spec/reducer_spec.rb
 
 ==== Run specific tests
 

data/asciidoctor-reducer.gemspec

@@ -35,5 +35,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'asciidoctor', '~> 2.0'
 
   s.add_development_dependency 'rake', '~> 13.0.0'
-  s.add_development_dependency 'rspec', '~> 3.10.0'
+  s.add_development_dependency 'rspec', '~> 3.11.0'
 end

data/bin/asciidoctor-reducer

@@ -1,13 +1,11 @@
 #!/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
+asciidoctor_reducer_cli = File.absolute_path '../lib/asciidoctor/reducer/cli', __dir__
+if File.exist? asciidoctor_reducer_cli
+  require asciidoctor_reducer_cli
 else
-  require 'asciidoctor/reducer'
+  require 'asciidoctor/reducer/cli'
 end
 
-require 'asciidoctor/reducer/cli'
-
 exit Asciidoctor::Reducer::Cli.run

data/lib/asciidoctor/reducer/api.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'extensions'
+
+module Asciidoctor::Reducer
+  autoload :VERSION, (::File.join __dir__, 'version.rb')
+
+  class << self
+    def reduce input, opts = {}
+      opts = opts.merge extension_registry: (Extensions.prepare_registry opts[:extension_registry] || opts[:extensions])
+      opts[:safe] = ::Asciidoctor::SafeMode::SAFE unless opts.key? :safe
+      case input
+      when ::File
+        doc = ::Asciidoctor.load_file input, opts
+      when ::Pathname
+        doc = ::Asciidoctor.load_file input.to_path, opts
+      else
+        doc = ::Asciidoctor.load input, opts
+      end
+      write doc, opts[:to]
+    end
+
+    def reduce_file input_file, opts = {}
+      reduce (::Pathname.new input_file), opts
+    end
+
+    private
+
+    def write doc, to
+      if to && to != '/dev/null'
+        output = doc.source
+        return output if to == ::String
+        output += LF unless output.empty?
+        if ::Pathname === to || (!(to.respond_to? :write) && (to = ::Pathname.new to.to_s))
+          to.dirname.mkpath
+          to.write output, encoding: UTF_8
+        else
+          to.write output
+        end
+      end
+      doc
+    end
+  end
+
+  LF = ?\n
+  UTF_8 = ::Encoding::UTF_8
+
+  private_constant :LF, :UTF_8
+end

data/lib/asciidoctor/reducer/cli.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'api'
 autoload :OptionParser, 'optparse'
-autoload :Pathname, 'pathname'
 
 module Asciidoctor::Reducer
-  autoload :VERSION, (::File.join __dir__, 'version.rb')
-
   class Cli
     LOG_LEVELS = (::Logger::Severity.constants false).each_with_object({}) do |level, accum|
       accum[level.to_s.downcase] = (::Logger::Severity.const_get level) unless level == :UNKNOWN
@@ -105,17 +103,9 @@ module Asciidoctor::Reducer
       else
         options[:logger] = nil
       end
-      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, options).source + ?\n
-      else
-        reduced = (::Asciidoctor.load_file input_file, options).source + ?\n
-      end
-      ::Pathname === to ? (to.write reduced, encoding: ::Encoding::UTF_8) : (to.write reduced)
+      options[:to] = (output_file = options.delete :output_file) == '-' ? $stdout : (::Pathname.new output_file)
+      input = (input_file = options.delete :input_file) == '-' ? $stdin : (::Pathname.new input_file)
+      ::Asciidoctor::Reducer.reduce input, options
       0
     rescue
       $stderr.write %(asciidoctor-reducer: #{$!.message}\n)

data/lib/asciidoctor/reducer/extensions.rb

@@ -1,4 +1,39 @@
 # frozen_string_literal: true
 
+require 'asciidoctor' unless defined? Asciidoctor.load
 require_relative 'preprocessor'
 require_relative 'tree_processor'
+
+module Asciidoctor::Reducer
+  module Extensions
+    module_function
+
+    def group
+      proc do
+        next if document.options[:reduced]
+        preprocessor Preprocessor
+        tree_processor TreeProcessor
+      end
+    end
+
+    def prepare_registry registry = nil
+      registry = ::Asciidoctor::Extensions.create(&registry) if ::Proc === registry
+      unless ::Asciidoctor::Extensions.groups[:reducer]
+        if registry
+          registry.groups[:reducer] = group
+        else
+          registry = ::Asciidoctor::Extensions.create :reducer, &group
+        end
+      end
+      registry
+    end
+
+    def register
+      ::Asciidoctor::Extensions.register :reducer, &group
+    end
+
+    def unregister
+      ::Asciidoctor::Extensions.unregister :reducer
+    end
+  end
+end

data/lib/asciidoctor/reducer/preprocessor_directive_tracker.rb

@@ -86,4 +86,6 @@ module Asciidoctor::Reducer
       self[@pos]
     end
   end
+
+  private_constant :CurrentPosition
 end

data/lib/asciidoctor/reducer/version.rb

@@ -2,6 +2,6 @@
 
 module Asciidoctor
   module Reducer
-    VERSION = '1.0.0.alpha.6'
+    VERSION = '1.0.0.alpha.7'
   end
 end

data/lib/asciidoctor/reducer.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require 'asciidoctor'
 require_relative 'reducer/extensions'
 
-Asciidoctor::Extensions.register :reducer do
-  next if document.options[:reduced]
-  preprocessor Asciidoctor::Reducer::Preprocessor
-  tree_processor Asciidoctor::Reducer::TreeProcessor
-end
+Asciidoctor::Reducer::Extensions.register

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-reducer
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha.6
+  version: 1.0.0.alpha.7
 platform: ruby
 authors:
 - Dan Allen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-10 00:00:00.000000000 Z
+date: 2022-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.10.0
+        version: 3.11.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.10.0
+        version: 3.11.0
 description: A tool that reduces a composite AsciiDoc document containing preprocessor
   directives (includes and conditionals) to a single AsciiDoc document by expanding
   the includes and applying the conditionals.
@@ -68,6 +68,7 @@ files:
 - bin/asciidoctor-reducer
 - lib/asciidoctor-reducer.rb
 - lib/asciidoctor/reducer.rb
+- lib/asciidoctor/reducer/api.rb
 - lib/asciidoctor/reducer/cli.rb
 - lib/asciidoctor/reducer/extensions.rb
 - lib/asciidoctor/reducer/preprocessor.rb