asciidoctor-interdoc-reftext 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fed3980f4a2bfa3f3c12b30ed11ffeb67271369c
+  data.tar.gz: dab27d0a17a2fcd44349879a58c87c18684f4033
+SHA512:
+  metadata.gz: 5cb9baa9cc4604a27f7314f814ad65358fc4571b8cb42de27ef97c74c8b99100a7f16cc4fd056076aa7965445bc9bfd13b7c45c31d6ab99a2fc7c1f5cad22509
+  data.tar.gz: ce59c604c441f61eddb9f1409890e814f3fa7704b58b41c651ba40966d85e01d3e2b1cb424fbbb8dd297e6497e3fe585a2c6ce7cc40d3cb65f2dfe4268a59e12

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright 2018 Jakub Jirutka <jakub@jirutka.cz>.
+
+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,93 @@
+= Asciidoctor Inter-doc Reference Text
+:source-language: shell
+// custom
+:gem-name: asciidoctor-interdoc-reftext
+:gh-name: jirutka/{gem-name}
+:gh-branch: master
+:codacy-id: 7f60adeeb3fc49ee85863df2c65cd4eb
+
+ifdef::env-github[]
+image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.org/{gh-name}"]
+image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"]
+image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"]
+image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
+image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"]
+endif::env-github[]
+
+
+This project is an http://asciidoctor.org/[Asciidoctor] extension providing implicit (automatic) reference text (label) for inter-document cross references.
+
+
+== Examples
+
+When you define a cross reference to another document “other.adoc” _without_ a label, e.g.:
+
+----
+xref:other#[]
+----
+
+Asciidoctor converts it into a plain link with the target document’s path as a text:
+
+// GitHub doesn't render Example block as a box.
+[subs="+macros"]
+----
+link:other.html[other.html]
+----
+
+but this extensions converts it into:
+
+[subs="+macros"]
+----
+link:other.html[Other Document]
+----
+
+where “Other Document” is a *title* of the _other.adoc_.
+
+Similarly with cross reference to a section in another document, e.g.:
+
+----
+xref:other#sec1[]
+----
+
+Asciidoctor converts it in the same way as above, but this extensions converts it into:
+
+[subs="+macros"]
+----
+link:other.html#sec1[The First Section]
+----
+
+where “The First Section” is *title* of the section with id _sec1_ in _other.adoc_.
+
+
+== Installation
+
+To install (or update to the latest version):
+
+[source, subs="+attributes"]
+gem install {gem-name}
+
+or to install the latest development version:
+
+[source, subs="+attributes"]
+gem install {gem-name} --pre
+
+
+== Usage
+
+Just `require '{gem-name}'`.
+If you invoke Asciidoctor from command-line, use option `-r` to load the extension:
+
+[source, subs="+attributes"]
+asciidoctor -r {gem-name} README.adoc
+
+If you don’t want the extension to be automatically registered in Asciidoctor, don’t _require_ `{gem-name}`, but `asciidoctor/interdoc_reftext/processor`.
+
+IMPORTANT: Bundler automatically _requires_ all the specified gems.
+           To prevent it, use +
+           `gem '{gem-name}', require: false`.
+
+
+== License
+
+This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
+For the full text of the license, see the link:LICENSE[LICENSE] file.

data/asciidoctor-interdoc-reftext.gemspec

@@ -0,0 +1,29 @@
+require File.expand_path('../lib/asciidoctor/interdoc_reftext/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'asciidoctor-interdoc-reftext'
+  s.version     = Asciidoctor::InterdocReftext::VERSION
+  s.author      = 'Jakub Jirutka'
+  s.email       = 'jakub@jirutka.cz'
+  s.homepage    = 'https://github.com/jirutka/asciidoctor-interdoc-reftext'
+  s.license     = 'MIT'
+
+  s.summary     = "Asciidoctor extension providing implicit (automatic) reference \
+text (label) for inter-document cross references"
+
+  s.files       = Dir['lib/**/*', '*.gemspec', 'LICENSE*', 'README*']
+  s.has_rdoc    = 'yard'
+
+  s.required_ruby_version = '>= 2.1'
+
+  s.add_runtime_dependency 'asciidoctor', '~> 1.5.6'
+
+  s.add_development_dependency 'corefines', '~> 1.11'
+  s.add_development_dependency 'kramdown', '~> 1.16'
+  s.add_development_dependency 'rake', '~> 12.0'
+  s.add_development_dependency 'rspec', '~> 3.7'
+  s.add_development_dependency 'rspec-html-matchers', '~> 0.9.1'
+  s.add_development_dependency 'rubocop', '~> 0.51.0'
+  s.add_development_dependency 'simplecov', '~> 0.15'
+  s.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/asciidoctor-interdoc-reftext.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require 'asciidoctor/interdoc_reftext'

data/lib/asciidoctor/interdoc_reftext.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+require 'asciidoctor/extensions'
+require 'asciidoctor/interdoc_reftext/version'
+require 'asciidoctor/interdoc_reftext/processor'
+
+Asciidoctor::Extensions.register do
+  treeprocessor Asciidoctor::InterdocReftext::Processor
+end

data/lib/asciidoctor/interdoc_reftext/inline_node_mixin.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+require 'asciidoctor/interdoc_reftext/version'
+require 'asciidoctor'
+
+module Asciidoctor::InterdocReftext
+  # Mixin intended to be prepended into `Asciidoctor::Inline`.
+  #
+  # It modifies the method `#text` to resolve the value via {Resolver} if it's
+  # not set, this node is an *inline_anchor* and has attribute *path* (i.e.
+  # represents an inter-document cross reference).
+  module InlineNodeMixin
+
+    # Returns text of this inline element.
+    #
+    # @note This method will override the same name attribute reader in
+    #   class `Asciidoctor::Inline`.
+    #
+    # @return [String, nil]
+    def text
+      if (value = super)
+        value
+      # If this node is an inter-document cross reference...
+      elsif @node_name == 'inline_anchor' && @attributes['path']
+        resolver = interdoc_reftext_resolver
+        @text = resolver.call(@attributes['refid']) if resolver
+      end
+    end
+
+    private
+
+    # @return [#call, nil] an inter-document reftext resolver, or nil if not
+    #   set for the document.
+    def interdoc_reftext_resolver
+      # This variable is injected into the document by {Processor}.
+      @document.instance_variable_get(Processor::RESOLVER_VAR_NAME)
+    end
+  end
+end

data/lib/asciidoctor/interdoc_reftext/processor.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+require 'asciidoctor/extensions'
+require 'asciidoctor/interdoc_reftext/inline_node_mixin'
+require 'asciidoctor/interdoc_reftext/resolver'
+require 'asciidoctor/interdoc_reftext/version'
+
+module Asciidoctor::InterdocReftext
+  # Asciidoctor processor that adds support for automatic cross-reference text
+  # for inter-document cross references.
+  #
+  # ### Implementation Considerations
+  #
+  # Asciidoctor does not allow to _cleanly_ change the way of resolving
+  # xreftext for `xref:path#[]` macro with path and without explicit xreflabel;
+  # it always uses path as the default xreflabel.
+  #
+  # 1. `xref:[]` macros are parsed and even converted in
+  #    `Asciidoctor::Substitutors#sub_inline_xrefs` - a single, huge and nasty
+  #    method that accepts a text (e.g. whole paragraph) and returns the text
+  #    with converted `xref:[]` macros. The conversion is delegated to
+  #    `Asciidoctor::Inline#convert` - for each macro a new instance of
+  #    `Inline` node is created and then `#convert` is called.
+  #
+  # 2. `Inline#convert` just calls `converter.convert` with `self`, i.e. it's
+  #    dispatched to converter's `inline_anchor` handler.
+  #
+  # 3. The built-in so called HTML5 converter looks into the catalog of
+  #    references (`document.catalog[:refs]`) for reflabel for the xref's
+  #    *refid*, but only if xref node does not define attribute *path* or
+  #    *text* (explicit reflabel). If *text* is not set and *path* is set, i.e.
+  #    it's an inter-document reference without explicit reflabel, catalog of
+  #    references is bypassed and *path* is used as a reflabel.
+  #
+  # Eh, this is really nasty... The least evil way how to achieve the goal
+  # seems to be monkey-patching of the `Asciidoctor::Inline` class. This is
+  # done via {InlineNodeMixin} which is prepended into the `Inline` class on
+  # initialization of this processor.
+  #
+  # The actual logic that resolves reflabel for the given *refid* is
+  # implemented in class {Resolver}. The {Processor} is responsible for
+  # creating an instance of {Resolver} for the processed document and injecting
+  # it into instance variable {RESOLVER_VAR_NAME} in the document, so
+  # {InlineNodeMixin} can access it.
+  #
+  # Prepending {InlineNodeMixin} into the `Asciidoctor::Inline` class has
+  # (obviously) a global effect. However, if {RESOLVER_VAR_NAME} is not
+  # injected in the document object (e.g. extension is not active), `Inline`
+  # behaves the same as without {InlineNodeMixin}.
+  #
+  # NOTE: We use _reftext_ and _reflabel_ as interchangeable terms in this gem.
+  class Processor < ::Asciidoctor::Extensions::TreeProcessor
+
+    # Name of instance variable that is dynamically defined in a document
+    # object; it contains an instance of the Resolver for the document.
+    RESOLVER_VAR_NAME = :@_interdoc_reftext_resolver
+
+    # @param resolver_class [#new] the {Resolver} class to use.
+    # @param resolver_opts [Hash<Symbol, Object>] options to be passed into
+    #   the resolver_class's initializer (see {Resolver#initialize}).
+    def initialize(resolver_class: Resolver, **resolver_opts)
+      super
+      @resolver_class = resolver_class
+      @resolver_opts = resolver_opts
+
+      # Monkey-patch Asciidoctor::Inline unless already patched.
+      unless ::Asciidoctor::Inline.include? InlineNodeMixin
+        ::Asciidoctor::Inline.send(:prepend, InlineNodeMixin)
+      end
+    end
+
+    # @param document [Asciidoctor::Document] the document to process.
+    def process(document)
+      resolver = @resolver_class.new(document, @resolver_opts)
+      document.instance_variable_set(RESOLVER_VAR_NAME, resolver)
+      nil
+    end
+  end
+end

data/lib/asciidoctor/interdoc_reftext/resolver.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+require 'asciidoctor/interdoc_reftext/version'
+require 'asciidoctor'
+require 'logger'
+
+module Asciidoctor::InterdocReftext
+  # Resolver of inter-document cross reference texts.
+  class Resolver
+
+    # @param document [Asciidoctor::Document] the document associated with this resolver.
+    # @param asciidoc_exts [Array<String>] AsciiDoc file extensions (e.g. `.adoc`).
+    # @param logger [Logger] the logger to use for logging warning and errors.
+    # @param raise_exceptions [Boolean] whether to raise exceptions, or just log them.
+    def initialize(document,
+                   asciidoc_exts: ['.adoc', '.asciidoc', '.ad'],
+                   logger: ::Logger.new(STDERR),
+                   raise_exceptions: true)
+
+      @document = document
+      @asciidoc_exts = asciidoc_exts.dup.freeze
+      @logger = logger
+      @raise_exceptions = raise_exceptions
+      @cache = {}
+    end
+
+    # @param refid [String] the target without a file extension, optionally with
+    #   a fragment (e.g. `intro`, `intro#about`).
+    # @return [String, nil] reference text, or `nil` if not found.
+    # @raise ArgumentError if the *refid* is empty or starts with `#` and
+    #   *raise_exceptions* is true.
+    def resolve_reftext(refid)
+      if refid.empty? || refid.start_with?('#')
+        msg = "interdoc-reftext: refid must not be empty or start with '#', but given: '#{refid}'"
+        raise ArgumentError, msg if @raise_exceptions
+        @logger.error msg
+        return nil
+      end
+
+      path, fragment = refid.split('#', 2)
+      path = resolve_target_path(path) or return nil
+
+      @cache["#{path}##{fragment}".freeze] ||= begin
+        lines = read_file(path) or return nil
+        parse_reftext(lines, fragment)
+      rescue => e  # rubocop: disable RescueWithoutErrorClass
+        raise if @raise_exceptions
+        @logger.error "interdoc-reftext: #{e}"
+        nil
+      end
+    end
+
+    alias call resolve_reftext
+
+    protected
+
+    # @return [Hash<String, String>] a cache of resolved reftexts.
+    attr_reader :cache
+
+    # @param target_path [String] the target path without a file extension.
+    # @return [String, nil] file path of the *target_path*, or `nil` if not found.
+    def resolve_target_path(target_path)
+      # Include file is resolved relative to dir of the current include,
+      # or base_dir if within original docfile.
+      path = @document.normalize_system_path(target_path, @document.reader.dir,
+                                             nil, target_name: 'xref target')
+      return nil unless path
+
+      @asciidoc_exts.each do |extname|
+        filename = path + extname
+        return filename if ::File.file? filename
+      end
+      nil
+    end
+
+    # @param path [String] path of the file to read.
+    # @return [Enumerable<String>] lines of the file.
+    def read_file(path)
+      ::IO.foreach(path)
+    end
+
+    # @param input [Enumerable<String>] lines of the AsciiDoc document.
+    # @param fragment [String, nil] part of the target after `#`.
+    # @return [String, nil]
+    def parse_reftext(input, fragment = nil)
+      unless fragment
+        # Document title is typically defined at top of the document,
+        # so we try to parse just the first 10 lines to save resources.
+        # If document title is not here, we fallback to parsing whole document.
+        title = asciidoc_load(input.take(10)).doctitle
+        return title if title
+      end
+
+      doc = asciidoc_load(input)
+
+      if fragment
+        ref = doc.catalog[:refs][fragment]
+        ref.xreftext if ref
+      else
+        doc.doctitle
+      end
+    end
+
+    # @param input [Enumerable<String>, String] lines of the AsciiDoc document to load.
+    # @return [Asciidoctor::Document] a parsed document.
+    def asciidoc_load(input)
+      # Asciidoctor is dumb. It doesn't know enumerators and when we give it
+      # an Array, it calls #dup on it. At least it knows #readlines, so we just
+      # define it as an alias for #to_a.
+      if input.is_a?(::Enumerable) && !input.respond_to?(:readlines)
+        input.singleton_class.send(:alias_method, :readlines, :to_a)
+      end
+
+      ::Asciidoctor.load(input, @document.options)
+    end
+  end
+end

data/lib/asciidoctor/interdoc_reftext/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module InterdocReftext
+    # Version of the asciidoctor-interdoc-reftext gem.
+    VERSION = '0.1.0'.freeze
+  end
+end

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-interdoc-reftext
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jakub Jirutka
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+- !ruby/object:Gem::Dependency
+  name: corefines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rspec-html-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.51.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.51.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 
+email: jakub@jirutka.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.adoc
+- asciidoctor-interdoc-reftext.gemspec
+- lib/asciidoctor-interdoc-reftext.rb
+- lib/asciidoctor/interdoc_reftext.rb
+- lib/asciidoctor/interdoc_reftext/inline_node_mixin.rb
+- lib/asciidoctor/interdoc_reftext/processor.rb
+- lib/asciidoctor/interdoc_reftext/resolver.rb
+- lib/asciidoctor/interdoc_reftext/version.rb
+homepage: https://github.com/jirutka/asciidoctor-interdoc-reftext
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Asciidoctor extension providing implicit (automatic) reference text (label)
+  for inter-document cross references
+test_files: []