asciidoctor 0.1.4 → 1.5.0

data/lib/asciidoctor/cli/options.rb

@@ -1,10 +1,8 @@
-require 'optparse'
-
 module Asciidoctor
   module Cli
 
     # Public: List of options that can be specified on the command line
-    class Options < Hash
+    class Options < ::Hash
 
       def initialize(options = {})
         self[:attributes] = options[:attributes] || {}
@@ -21,11 +19,13 @@ module Asciidoctor
           self[:attributes]['backend'] = options[:backend]
         end
         self[:eruby] = options[:eruby] || nil
-        self[:compact] = options[:compact] || false
-        self[:verbose] = options[:verbose] || false
+        self[:verbose] = options[:verbose] || 1
+        self[:load_paths] = options[:load_paths] || nil
+        self[:requires] = options[:requires] || nil
         self[:base_dir] = options[:base_dir]
         self[:destination_dir] = options[:destination_dir] || nil
         self[:trace] = false
+        self[:timings] = false
       end
 
       def self.parse!(args)
@@ -33,7 +33,7 @@ module Asciidoctor
       end
 
       def parse!(args)
-        opts_parser = OptionParser.new do |opts|
+        opts_parser = ::OptionParser.new do |opts|
           opts.banner = <<-EOS
 Usage: asciidoctor [OPTION]... FILE...
 Translate the AsciiDoc source FILE or FILE(s) into the backend output format (e.g., HTML 5, DocBook 4.5, etc.)
@@ -42,14 +42,11 @@ Example: asciidoctor -b html5 source.asciidoc
 
           EOS
 
-          opts.on('-v', '--verbose', 'enable verbose mode (default: false)') do |verbose|
-            self[:verbose] = true
-          end
           opts.on('-b', '--backend BACKEND', 'set output format backend (default: html5)') do |backend|
             self[:attributes]['backend'] = backend
           end
           opts.on('-d', '--doctype DOCTYPE', ['article', 'book', 'manpage', 'inline'],
-                  'document type to use when rendering output: [article, book, manpage, inline] (default: article)') do |doc_type|
+                  'document type to use when converting document: [article, book, manpage, inline] (default: article)') do |doc_type|
             self[:attributes]['doctype'] = doc_type
           end
           opts.on('-o', '--out-file FILE', 'output file (default: based on input file path); use - to output to STDOUT') do |output_file|
@@ -70,16 +67,15 @@ Example: asciidoctor -b html5 source.asciidoc
             self[:header_footer] = false
           end
           opts.on('-n', '--section-numbers', 'auto-number section titles in the HTML backend; disabled by default') do
-            self[:attributes]['numbered'] = ''
+            self[:attributes]['sectnums'] = ''
           end
           opts.on('-e', '--eruby ERUBY', ['erb', 'erubis'],
-                  'specify eRuby implementation to render built-in templates: [erb, erubis] (default: erb)') do |eruby|
+                  'specify eRuby implementation to use when rendering custom ERB templates: [erb, erubis] (default: erb)') do |eruby|
             self[:eruby] = eruby
           end
-          opts.on('-C', '--compact', 'compact the output by removing blank lines (default: false)') do
-            self[:compact] = true
+          opts.on('-C', '--compact', 'compact the output by removing blank lines. (No longer in use)') do
           end
-          opts.on('-a', '--attribute key[=value],key2[=value2],...', Array,
+          opts.on('-a', '--attribute key[=value],key2[=value2],...', ::Array,
                   'a list of document attributes to set in the form of key, key! or key=value pair',
                   'unless @ is appended to the value, these attributes take precedence over attributes',
                   'defined in the source document') do |attribs|
@@ -92,17 +88,17 @@ Example: asciidoctor -b html5 source.asciidoc
               self[:attributes][key] = val || ''
             end
           end
-          opts.on('-T', '--template-dir DIR', 'a directory containing custom render templates that override the built-in set (requires tilt gem)',
+          opts.on('-T', '--template-dir DIR', 'a directory containing custom converter templates that override the built-in converter (requires tilt gem)',
                   'may be specified multiple times') do |template_dir|
             if self[:template_dirs].nil?
               self[:template_dirs] = [template_dir]
-            elsif self[:template_dirs].is_a? Array
+            elsif self[:template_dirs].is_a? ::Array
               self[:template_dirs].push template_dir
             else
               self[:template_dirs] = [self[:template_dirs], template_dir]
             end
           end
-          opts.on('-E', '--template-engine NAME', 'template engine to use for the custom render templates (loads gem on demand)') do |template_engine|
+          opts.on('-E', '--template-engine NAME', 'template engine to use for the custom converter templates (loads gem on demand)') do |template_engine|
             self[:template_engine] = template_engine
           end
           opts.on('-B', '--base-dir DIR', 'base directory containing the document and resources (default: directory of source file)') do |base_dir|
@@ -111,83 +107,137 @@ Example: asciidoctor -b html5 source.asciidoc
           opts.on('-D', '--destination-dir DIR', 'destination output directory (default: directory of source file)') do |dest_dir|
             self[:destination_dir] = dest_dir
           end
+          opts.on('-IDIRECTORY', '--load-path LIBRARY', 'add a directory to the $LOAD_PATH',
+              'may be specified more than once') do |path|
+            (self[:load_paths] ||= []).concat(path.split ::File::PATH_SEPARATOR)
+          end
+          opts.on('-rLIBRARY', '--require LIBRARY', 'require the specified library before executing the processor (using require)',
+              'may be specified more than once') do |path|
+            (self[:requires] ||= []).concat(path.split ',')
+          end
+          opts.on('-q', '--quiet', 'suppress warnings (default: false)') do |verbose|
+            self[:verbose] = 0
+          end
           opts.on('--trace', 'include backtrace information on errors (default: false)') do |trace|
             self[:trace] = true
           end
+          opts.on('-v', '--verbose', 'enable verbose mode (default: false)') do |verbose|
+            self[:verbose] = 2
+          end
+          opts.on('-t', '--timings', 'enable timings mode (default: false)') do |timing|
+            self[:timings] = true
+          end
 
           opts.on_tail('-h', '--help', 'show this message') do
             $stdout.puts opts
             return 0
           end
 
-          opts.on_tail('-V', '--version', 'display the version') do
-            $stdout.puts "Asciidoctor #{Asciidoctor::VERSION} [http://asciidoctor.org]"
+          opts.on_tail('-V', '--version', 'display the version and runtime environment (or -v if no other flags or arguments)') do
+            $stdout.puts %(Asciidoctor #{::Asciidoctor::VERSION} [http://asciidoctor.org])
+            $stdout.puts %(Runtime Environment (#{RUBY_DESCRIPTION}))
             return 0
           end
           
         end
 
-        begin
-          infiles = []
-          opts_parser.parse! args
-          
-          if args.empty?
+        infiles = []
+        opts_parser.parse! args
+        
+        if args.empty?
+          if self[:verbose] == 2
+            $stdout.puts %(Asciidoctor #{::Asciidoctor::VERSION} [http://asciidoctor.org])
+            $stdout.puts %(Runtime Environment (#{RUBY_DESCRIPTION}))
+            return 0
+          else
             $stderr.puts opts_parser
             return 1
           end
+        end
 
-          # shave off the file to process so that options errors appear correctly
-          if args.size == 1 && args.first == '-'
-            infiles.push args.pop
-          elsif
-            args.each do |file|
-              if (file == '-' || file.start_with?('-'))
-                # warn, but don't panic; we may have enough to proceed, so we won't force a failure
-                $stderr.puts "asciidoctor: WARNING: extra arguments detected (unparsed arguments: #{args.map{|a| "'#{a}'"} * ', '}) or incorrect usage of stdin"
+        # shave off the file to process so that options errors appear correctly
+        if args.size == 1 && args[0] == '-'
+          infiles.push args.pop
+        elsif
+          args.each do |file|
+            if file == '-' || (file.start_with? '-')
+              # warn, but don't panic; we may have enough to proceed, so we won't force a failure
+              $stderr.puts "asciidoctor: WARNING: extra arguments detected (unparsed arguments: #{args.map{|a| "'#{a}'"} * ', '}) or incorrect usage of stdin"
+            else
+              if ::File.readable? file
+                matches = [file]
               else
-                # TODO this glob may not be necessary as the shell should have already performed expansion
-                matches = Dir.glob file
-
-                if matches.empty?
-                  $stderr.puts "asciidoctor: FAILED: input file #{file} missing or cannot be read"
+                # Tilt backslashes in Windows paths the Ruby-friendly way
+                if ::File::ALT_SEPARATOR == '\\' && (file.include? '\\')
+                  file = file.tr '\\', '/'
+                end
+                if (matches = ::Dir.glob file).empty?
+                  $stderr.puts %(asciidoctor: FAILED: input file #{file} missing or cannot be read)
                   return 1
                 end
-
-                infiles.concat matches
               end
+
+              infiles.concat matches
             end
           end
+        end
 
-          infiles.each do |file|
-            unless file == '-' || File.readable?(file)
-              $stderr.puts "asciidoctor: FAILED: input file #{file} missing or cannot be read"
-              return 1
-            end
+        infiles.each do |file|
+          unless file == '-' || (::File.readable? file)
+            $stderr.puts %(asciidoctor: FAILED: input file #{file} missing or cannot be read)
+            return 1
           end
+        end
 
-          self[:input_files] = infiles
+        self[:input_files] = infiles
 
-          if !self[:template_dirs].nil?
+        self.delete(:attributes) if self[:attributes].empty?
+
+        if self[:template_dirs]
+          begin
+            require 'tilt' unless defined? ::Tilt
+          rescue ::LoadError
+            raise $! if self[:trace]
+            $stderr.puts 'asciidoctor: FAILED: \'tilt\' could not be loaded'
+            $stderr.puts '  You must have the tilt gem installed (gem install tilt) to use custom backend templates'
+            $stderr.puts '  Use --trace for backtrace'
+            return 1
+          rescue ::SystemExit
+            # not permitted here
+          end
+        end
+
+        if (load_paths = self[:load_paths])
+          (self[:load_paths] = load_paths.uniq).reverse_each do |path|
+            $:.unshift File.expand_path(path)
+          end
+        end
+
+        if (requires = self[:requires])
+          (self[:requires] = requires.uniq).each do |path|
             begin
-              require 'tilt'
-            rescue LoadError
-              $stderr.puts 'asciidoctor: FAILED: tilt could not be loaded; to use a custom backend, you must have the tilt gem installed (gem install tilt)'
+              require path
+            rescue ::LoadError
+              raise $! if self[:trace]
+              $stderr.puts %(asciidoctor: FAILED: '#{path}' could not be loaded)
+              $stderr.puts '  Use --trace for backtrace'
               return 1
+            rescue ::SystemExit
+              # not permitted here
             end
           end
-
-        rescue OptionParser::MissingArgument
-          $stderr.puts "asciidoctor: option #{$!.message}"
-          $stdout.puts opts_parser
-          return 1
-        rescue OptionParser::InvalidOption, OptionParser::InvalidArgument
-          $stderr.puts "asciidoctor: #{$!.message}"
-          $stdout.puts opts_parser
-          return 1
         end
-        self
-      end # parse()
 
+        self
+      rescue ::OptionParser::MissingArgument
+        $stderr.puts %(asciidoctor: option #{$!.message})
+        $stdout.puts opts_parser
+        return 1
+      rescue ::OptionParser::InvalidOption, ::OptionParser::InvalidArgument
+        $stderr.puts %(asciidoctor: #{$!.message})
+        $stdout.puts opts_parser
+        return 1
+      end
     end
   end
 end

data/lib/asciidoctor/converter.rb

@@ -0,0 +1,232 @@
+module Asciidoctor
+  # A base module for defining converters that can be used to convert {AbstractNode}
+  # objects in a parsed AsciiDoc document to a backend format such as HTML or
+  # DocBook.
+  #
+  # Implementing a converter involves:
+  #
+  # * including this module in a {Converter} implementation class
+  # * overriding the {Converter#convert} method
+  # * optionally associating the converter with one or more backends using
+  #   the {#register_for} DSL method imported by the {Config Converter::Config} module
+  #
+  # Examples
+  #
+  #   class TextConverter
+  #     include Asciidoctor::Converter
+  #     register_for 'text'
+  #     def initialize backend, opts
+  #       super
+  #       outfilesuffix '.txt'
+  #     end
+  #     def convert node, transform = nil
+  #       case (transform ||= node.node_name)
+  #       when 'document'
+  #         node.content
+  #       when 'section'
+  #         [node.title, node.content] * "\n\n"
+  #       when 'paragraph'
+  #         node.content.tr("\n", ' ') << "\n"
+  #       else
+  #         if transform.start_with? 'inline_'
+  #           node.text
+  #         else
+  #           %(<#{transform}>\n)
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   puts Asciidoctor.convert_file 'sample.adoc', backend: :text
+  module Converter
+    # A module that provides the {#register_for} method for statically
+    # registering a converter with the default {Factory Converter::Factory} instance.
+    module Config
+      # Public: Statically registers the current {Converter} class with the default
+      # {Factory Converter::Factory} to handle conversion to the specified backends.
+      #
+      # This method also defines the converts? method on the class which returns whether
+      # the class is registered to convert a specified backend.
+      #
+      # backends - A String Array of backends with which to associate this {Converter} class.
+      #
+      # Returns nothing
+      def register_for *backends
+        Factory.register self, backends
+        metaclass = class << self; self; end
+        if backends == ['*']
+          metaclass.send :define_method, :converts? do |name|
+            true
+          end
+        else
+          metaclass.send :define_method, :converts? do |name|
+            backends.include? name
+          end
+        end
+        nil
+      end
+    end
+
+    module BackendInfo
+      def backend_info
+        @backend_info ||= setup_backend_info
+      end
+
+      def setup_backend_info
+        raise ::ArgumentError, %(Cannot determine backend for converter: #{self.class}) unless @backend
+        base = @backend.sub TrailingDigitsRx, ''
+        if (ext = DEFAULT_EXTENSIONS[base])
+          type = ext[1..-1]
+        else
+          # QUESTION should we be forcing the basebackend to html if unknown?
+          base = 'html'
+          ext = '.html'
+          type = 'html'
+          syntax = 'html'
+        end
+        {
+          'basebackend' => base,
+          'outfilesuffix' => ext,
+          'filetype' => type,
+          'htmlsyntax' => syntax
+        }
+      end
+
+      def filetype value = nil
+        if value
+          backend_info['filetype'] = value
+        else
+          backend_info['filetype']
+        end
+      end
+
+      def basebackend value = nil
+        if value
+          backend_info['basebackend'] = value
+        else
+          backend_info['basebackend']
+        end
+      end
+
+      def outfilesuffix value = nil
+        if value
+          backend_info['outfilesuffix'] = value
+        else
+          backend_info['outfilesuffix']
+        end
+      end
+
+      def htmlsyntax value = nil
+        if value
+          backend_info['htmlsyntax'] = value
+        else
+          backend_info['htmlsyntax']
+        end
+      end
+    end
+
+    class << self
+      # Mixes the {Config Converter::Config} module into any class that includes the {Converter} module.
+      #
+      # converter - The Class that includes the {Converter} module
+      #
+      # Returns nothing
+      def included converter
+        converter.extend Config
+      end
+    end
+  
+    include Config
+    include BackendInfo
+
+    # Public: Creates a new instance of Converter
+    #
+    # backend - The String backend format to which this converter converts.
+    # opts    - An options Hash (optional, default: {})
+    #
+    # Returns a new instance of [Converter]
+    def initialize backend, opts = {}
+      @backend = backend
+      setup_backend_info
+    end
+
+=begin
+    # Public: Invoked when this converter is added to the chain of converters in a {CompositeConverter}.
+    #
+    # owner - The CompositeConverter instance
+    #
+    # Returns nothing
+    def composed owner
+    end
+=end
+
+    # Public: Converts an {AbstractNode} using the specified transform. If a
+    # transform is not specified, implementations typically derive one from the
+    # {AbstractNode#node_name} property.
+    #
+    # Implementations are free to decide how to carry out the conversion. In
+    # the case of the built-in converters, the tranform value is used to
+    # dispatch to a handler method. The {TemplateConverter} uses the value of
+    # the transform to select a template to render.
+    #
+    # node      - The concrete instance of AbstractNode to convert
+    # transform - An optional String transform that hints at which transformation
+    #             should be applied to this node. If a transform is not specified,
+    #             the transform is typically derived from the value of the
+    #             node's node_name property. (optional, default: nil)
+    #
+    # Returns the [String] result
+    def convert node, transform = nil
+      raise ::NotImplementedError
+    end
+
+    # Public: Converts an {AbstractNode} using the specified transform along
+    # with additional options. Delegates to {#convert} without options by default.
+    #
+    # node      - The concrete instance of AbstractNode to convert
+    # transform - An optional String transform that hints at which transformation
+    #             should be applied to this node. If a transform is not specified,
+    #             the transform is typically derived from the value of the
+    #             node's node_name property. (optional, default: nil)
+    # opts      - An optional Hash of options that provide additional hints about
+    #             how to convert the node.
+    #
+    # Returns the [String] result
+    def convert_with_options node, transform = nil, opts = {}
+      convert node, transform
+    end
+  end
+
+  # A module that can be used to mix the {#write} method into a {Converter}
+  # implementation to allow the converter to control how the output is written
+  # to disk.
+  module Writer
+    # Public: Writes the output to the specified target file name or stream.
+    #
+    # output - The output String to write
+    # target - The String file name or stream object to which the output should
+    #          be written.
+    #
+    # Returns nothing
+    def write output, target
+      if target.respond_to? :write
+        target.write output.chomp
+        # ensure there's a trailing endline to be nice to terminals
+        target.write EOL
+      else
+        ::File.open(target, 'w') {|f| f.write output }
+      end
+      nil
+    end
+  end
+
+  module VoidWriter
+    include Writer
+    # Public: Does not write output
+    def write output, target
+    end
+  end
+end
+
+require 'asciidoctor/converter/base'
+require 'asciidoctor/converter/factory'