asciidoctor-templates-compiler 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ad02dd81d47a7185c55b040d6a80af3f6fa5ba24
-  data.tar.gz: 26b3aaa536e7f76843fa4f7036c9d8d1901e4453
+  metadata.gz: 51590b253d877005f5760f154c14346665e1722c
+  data.tar.gz: 9d98b848da5104228aa0c8918e9646b12ec06805
 SHA512:
-  metadata.gz: 5190bb978d148d33659d16ce2065f6455e7da03322fe8c45979403ef6f4fc1f60baf27765d5900e16d04019466ff3e55169301172f897715d55772d903f1423e
-  data.tar.gz: 27cb8c19f213138b057d998d8f1a53eae0a03798ba0d508053ae651750ecbeec2b321d3d922bf4ef32db521c3b36b7ff34d9120f2400ecccafa6147563c391e5
+  metadata.gz: 3c6d38f6a691c349843ca8fd9d9569e6ac125bc81cb3732a45d3af1c4b651d7d953b8d759151823dbb6f1f3cb7802330719bab51e472fa04e0529674ca5c638a
+  data.tar.gz: 675c48c88d2c797049857cc70bedb7e3e56f9ec666ae8f2fa3181aafdfea67cc51fb949cd31f20240f27867d899b1dac0cfeb4b752188a026562c7104e1d667f

data/README.adoc

@@ -2,7 +2,7 @@
 :source-language: ruby
 // custom
 :gem-name: asciidoctor-templates-compiler
-:gem-version: 0.2.0
+:gem-version: 0.3.0
 :gh-name: jirutka/{gem-name}
 :gh-branch: master
 :codacy-id: b23b8c6503474ea5b13537eaef0c73d5

data/asciidoctor-templates-compiler.gemspec

@@ -11,11 +11,13 @@ Gem::Specification.new do |s|
   s.summary  = 'Compile templates-based Asciidoctor converter (backend) into a single Ruby file'
 
   s.files    = Dir['lib/**/*', '*.gemspec', 'LICENSE*', 'README*']
+  s.executables = Dir['bin/*'].map { |f| File.basename(f) }
 
-  s.required_ruby_version = '>= 2.3'
+  s.required_ruby_version = '>= 2.1'
 
   s.add_runtime_dependency 'asciidoctor', '~> 1.5'
   s.add_runtime_dependency 'corefines', '~> 1.2'
+  s.add_runtime_dependency 'docopt', '~> 0.6'
   s.add_runtime_dependency 'slim', '>= 2.1', '< 4.0'
   s.add_runtime_dependency 'ruby-beautify', '~> 0.97'
 

data/bin/asciidoctor-templates-compiler

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require 'asciidoctor/templates_compiler'
+require 'docopt'
+require 'corefines'
+
+using Corefines::Hash::rekey
+using Corefines::String::unindent
+
+PROG_NAME = 'asciidoctor-templates-compiler'
+BUGS_URL = "https://github.com/jirutka/#{PROG_NAME}/issues"
+
+HELP_MSG = <<-EOF.unindent
+  Usage:
+    #{PROG_NAME} [options...] TEMPLATES_DIR
+    #{PROG_NAME} --help | --version
+
+  Arguments:
+    TEMPLATES_DIR                    Path of the directory where to look for templates ("*.slim"
+                                     files not starting with "_", in the case of Slim) and
+                                     (optional) "helpers.rb".
+
+  Options:
+    -b --backend-info KEY=VAL[,...]  Parameters for backend_info: basebackend, outfilesuffix,
+                                     filetype, and htmlsyntax.
+
+    -n --class-name NAME             Full name of the converter class to generate (e.g.
+                                     My::HTML::Converter) [default: Converter].
+
+    -d --delegate-backend BACKEND    Name of the backend (converter) to use as a fallback for AST
+                                     nodes not supported by your converter. If not specified
+                                     (default), no fallback will be used and converter will raise
+                                     "NoMethodError" when it try to convert an unsupported node.
+
+    -o --output FILE                 Where to write the output. Use "-" for stdout. [default: -]
+
+    -P --no-pretty                   Do not format generated Ruby code.
+
+    -r --register-for BACKEND[,...]  Backend name(s) that the generated converter should be
+                                     registered in Asciidoctor to handle.
+
+    -V --version                     Print version and exit.
+
+    -h --help                        Show this message and exit.
+
+  Please report bugs at <#{BUGS_URL}>.
+EOF
+
+def die(message, status: 1)
+  $stderr.puts("#{PROG_NAME}: #{message}")
+  exit status
+end
+
+def parse_kw_list(list)
+  list
+    .flat_map { |arg| arg.split(/\s*,\s*/) }
+    .map { |item| item.split('=', 2) }
+    .to_h
+rescue ArgumentError
+  raise ArgumentError, 'not a list of key=word arguments'
+end
+
+def parse_option_value(name, value)
+  case name
+  when :backend_info
+    parse_kw_list(value)
+  when :class_name, :delegate_backend, :output
+    value.last
+  when :pretty
+    value.zero?
+  else
+    value
+  end
+rescue ArgumentError => e
+  raise ArgumentError, "Invalid option --#{name}: #{e.message}"
+end
+
+opts = begin
+  Docopt::docopt(HELP_MSG, help: false)
+    .rekey { |key| key.sub(/^--/, '').tr('-', '_').downcase.to_sym }
+    .rekey(:no_pretty => :pretty)  # rubocop:disable Style/HashSyntax
+    .map { |k, v| [k, parse_option_value(k, v)] }.to_h
+rescue Docopt::Exit => e
+  $stderr.puts(e.message)
+  exit 1
+rescue ArgumentError => e
+  die e.message
+end
+
+if opts[:help]
+  puts HELP_MSG.strip
+
+elsif opts[:version]
+  puts [PROG_NAME, Asciidoctor::TemplatesCompiler::VERSION].join(' ')
+
+else
+  output = if opts[:output] == '-'
+    $stdout
+  else
+    File.open(opts[:output], 'w')
+  end
+
+  begin
+    Asciidoctor::TemplatesCompiler::Slim.compile_converter(**opts, output: output)
+  rescue RuntimeError => e
+    die e.message
+  ensure
+    output.close if output != $stdout
+  end
+end

data/lib/asciidoctor/templates_compiler/base.rb

@@ -5,8 +5,12 @@ require 'asciidoctor/templates_compiler/ruby_beautify'
 require 'stringio'
 
 module Asciidoctor::TemplatesCompiler
+  ##
+  # Base class for templates compilers.
   class Base
     class << self
+      ##
+      # An "alias" for {#compile_converter}.
       def compile_converter(**opts)
         new.compile_converter(**opts)
       end
@@ -14,9 +18,23 @@ module Asciidoctor::TemplatesCompiler
       alias call compile_converter
     end
 
+    ##
+    # (see ConverterGenerator.generate)
+    #
+    # Compiles templates found in _templates_dir_ to Ruby and generates an Asciidoctor converter
+    # class from them.
+    #
+    # @param templates_dir [String] path of the directory where to look for templates
+    #   and (optional) +helpers.rb+.
+    # @param engine_opts [Hash] a hash of options to pass into the templating engine.
+    #   Default is empty.
+    # @param pretty [Boolean] enable pretty-formatting of the generated Ruby code?
+    #
+    # @raise [ArgumentError] if the given _templates_dir_ does not exist.
+    #
     def compile_converter(templates_dir:, engine_opts: {}, pretty: false, **opts)
       unless Dir.exist? templates_dir
-        raise "Templates directory '#{templates_dir}' does not exist"
+        raise ArgumentError, "Templates directory '#{templates_dir}' does not exist"
       end
 
       templates = find_templates(templates_dir)
@@ -30,11 +48,20 @@ module Asciidoctor::TemplatesCompiler
 
     protected
 
+    ##
     # @abstract
+    # @param filename [String] path of the template file to compile.
+    # @param engine_opts [Hash] a hash of options to pass into the templating engine.
+    # @return [String] a Ruby code of the compiled template.
+    #
     def compile_template(filename, engine_opts = {})
     end
 
+    ##
     # @abstract
+    # @param dirname [String] path of the directory where to look for templates.
+    # @return [Array<String>] paths of the found template files.
+    #
     def find_templates(dirname)
     end
 

data/lib/asciidoctor/templates_compiler/converter_generator.rb

@@ -1,21 +1,48 @@
 # frozen_string_literal: true
 require 'asciidoctor/templates_compiler/version'
+require 'asciidoctor/templates_compiler/string_ext'
 require 'corefines'
 require 'stringio'
 
 module Asciidoctor::TemplatesCompiler
+  ##
+  # Source-code generator of Asciidoctor converter classes.
   class ConverterGenerator
-    using Corefines::String::indent
+    using Corefines::String[:indent, :unindent]
     using Corefines::Object::blank?
+    using StringExt::reindent
 
     class << self
+      ##
+      # (see #initialize)
+      # @param output [#<<] output stream where to write the generated class.
+      #   Defaults to {StringIO}.
+      # @return the given _output_ stream.
+      #
       def generate(output: StringIO.new, **opts)
         new(**opts).call(output)
       end
 
+      # An alias for {.generate}.
       alias call generate
     end
 
+    ##
+    # @param class_name [String] full name of the converter class to generate
+    #   (e.g. +My::HTML::Converter+).
+    # @param transforms_code [#each] enumerable that yields pair: transform name ()
+    # @param helpers_code [String, nil] source code to include in the generated class. It must
+    #   contain a module named +Helpers+.
+    # @param register_for [Array<String>] an array of backend names that the generated converter
+    #   should be registered for to handle. Default is empty.
+    # @param backend_info [Hash] a hash of parameters for +backend_info+: +basebackend+,
+    #   +outfilesuffix+, +filetype+, +htmlsyntax+. Default is empty.
+    # @param delegate_backend [String, nil] name of the backend (converter) to use as a fallback
+    #   for AST nodes not supported by the generated converter. If not specified, no fallback will
+    #   be used and converter will raise +NoMethodError+ when it try to convert unsupported node.
+    #
+    # @raise [ArgumentError] if _helpers_code_ is not blank and does not contain module +Helpers+.
+    #
     def initialize(class_name:, transforms_code:, helpers_code: nil,
                    register_for: [], backend_info: {}, delegate_backend: nil, **)
       @class_name = class_name
@@ -30,6 +57,12 @@ module Asciidoctor::TemplatesCompiler
       end
     end
 
+    ##
+    # Generates source code of a converter class for Asciidoctor.
+    #
+    # @param out [#<<] output stream where to write the generated class.
+    # @return the given _out_ stream.
+    #
     def generate(out = StringIO.new)
       out << head_code << "\n"
       out << helpers_code << "\n" unless @helpers_code.blank?
@@ -52,7 +85,7 @@ module Asciidoctor::TemplatesCompiler
         .tap { |ary| ary.push('end ' * ary.size) }
         .join(' ').strip
 
-      <<~EOF
+      <<-EOF.unindent
         # This file has been generated!
 
         #{init_modules}
@@ -61,9 +94,9 @@ module Asciidoctor::TemplatesCompiler
     end
 
     def helpers_code
-      <<~EOF.indent(2, ' ')
+      <<-EOF.unindent.%(@helpers_code).indent(2)
         #{separator 'Begin of Helpers'}
-        #{@helpers_code}
+        %s
 
         # Make Helpers' constants accessible from transform methods.
         Helpers.constants.each do |const|
@@ -84,7 +117,7 @@ module Asciidoctor::TemplatesCompiler
       end
 
       if @delegate_backend
-        delegate_converter = <<~EOF.rstrip.indent(2, ' ')
+        delegate_converter = <<-EOF.reindent(2).rstrip
 
           delegate_backend = (opts[:delegate_backend] || #{@delegate_backend.inspect}).to_s
           factory = ::Asciidoctor::Converter::Factory
@@ -106,7 +139,7 @@ module Asciidoctor::TemplatesCompiler
         delegate_converter,
         'end',
         '',
-      ].compact.join("\n").indent(2, ' ')
+      ].compact.join("\n").indent(2)
     end
 
     def convert_method_code
@@ -116,7 +149,7 @@ module Asciidoctor::TemplatesCompiler
         'self'
       end
 
-      <<~EOF.indent(2, ' ')
+      <<-EOF.reindent(2)
         def convert(node, transform = nil, opts = {})
           transform ||= node.node_name
           converter = #{converter}
@@ -131,7 +164,7 @@ module Asciidoctor::TemplatesCompiler
     end
 
     def support_methods_code
-      <<~EOF.indent(2, ' ')
+      <<-EOF.reindent(2)
         def set_local_variables(binding, vars)
           vars.each do |key, val|
             binding.local_variable_set(key.to_sym, val)
@@ -141,19 +174,17 @@ module Asciidoctor::TemplatesCompiler
     end
 
     def transform_methods_code(out)
-      out << "  #{separator 'Begin of generated transformation methods'}"
+      out << "  #{separator 'Begin of generated transformation methods'}\n"
 
       @transforms_code.each do |name, code|
-        out << <<~EOF.indent(2, ' ')
-
-          def #{name}(node, opts = {})
-          #{'  node.extend(Helpers)' unless @helpers_code.blank?}
-            node.instance_eval do
-              converter.set_local_variables(binding, opts) unless opts.empty?
-          #{code.indent(6, ' ')}
-            end
-          end
-        EOF
+        out << "\n"
+        out << "  def #{name}(node, opts = {})\n"
+        out << "    node.extend(Helpers)\n" unless @helpers_code.blank?
+        out << "    node.instance_eval do\n"
+        out << "      converter.set_local_variables(binding, opts) unless opts.empty?\n"
+        out << code.indent(6, ' ') << "\n"
+        out << "    end\n"
+        out << "  end\n"
       end
 
       out << "  #{separator 'End of generated transformation methods'}\n"

data/lib/asciidoctor/templates_compiler/ruby_beautify.rb

@@ -14,7 +14,7 @@ module Asciidoctor::TemplatesCompiler
       new_lines_old = NEW_LINES
       NEW_LINES.push(:on_semicolon)  # XXX: sandbox somehow?
 
-      s = +"module M_\n#{code}\nend\n"
+      s = "module M_\n#{code}\nend\n".dup
       s.gsub!(/^[ \t]*;/, '')      # remove leading semicolons
       s.gsub!(/;\s*$/, '')         # remove trailing semicolons
       s.replace(pretty_string_orig(s, indent_token: "\1", indent_count: indent_count))

data/lib/asciidoctor/templates_compiler/string_ext.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+require 'corefines'
+
+module Asciidoctor::TemplatesCompiler
+  # @private
+  module StringExt
+    module Reindent
+      refine ::String do
+        using ::Corefines::String[:indent, :unindent]
+
+        def reindent(level, indent_str = ' ')
+          unindent.indent!(level, indent_str)
+        end
+      end
+    end
+
+    include ::Corefines::Support::AliasSubmodules
+  end
+end

data/lib/asciidoctor/templates_compiler/version.rb

@@ -2,6 +2,6 @@
 
 module Asciidoctor
   module TemplatesCompiler
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-templates-compiler
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jakub Jirutka
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-04 00:00:00.000000000 Z
+date: 2017-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: docopt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: slim
   requirement: !ruby/object:Gem::Requirement
@@ -130,19 +144,22 @@ dependencies:
         version: '0.14'
 description: 
 email: jakub@jirutka.cz
-executables: []
+executables:
+- asciidoctor-templates-compiler
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.adoc
 - asciidoctor-templates-compiler.gemspec
+- bin/asciidoctor-templates-compiler
 - lib/asciidoctor-templates-compiler.rb
 - lib/asciidoctor/templates_compiler.rb
 - lib/asciidoctor/templates_compiler/base.rb
 - lib/asciidoctor/templates_compiler/converter_generator.rb
 - lib/asciidoctor/templates_compiler/ruby_beautify.rb
 - lib/asciidoctor/templates_compiler/slim.rb
+- lib/asciidoctor/templates_compiler/string_ext.rb
 - lib/asciidoctor/templates_compiler/temple_ext.rb
 - lib/asciidoctor/templates_compiler/version.rb
 homepage: https://github.com/jirutka/asciidoctor-templates-compiler
@@ -157,7 +174,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="