giblish 0.8.2 → 1.0.0.rc2

data/lib/giblish/cmdline.rb

@@ -1,284 +1,298 @@
-require_relative "utils"
-require_relative "version"
+require "optparse"
+require "logger"
 
-# Parse the cmd line arguments
-# This implementation is heavily inspired by the following
-# stack overflow answer:
-# http://stackoverflow.com/questions/26434923/parse-command-line-arguments-in-a-ruby-script
-class CmdLineParser
-  attr_accessor :args
+module Giblish
+  # parse the cmd line
+  class CmdLine
+    # Container class for all supported options that are
+    # accessible via the cmd line.
+    class Options
+      attr_accessor :format, :no_index, :index_basename, :graph_basename, :include_regex, :exclude_regex,
+        :copy_asset_folders, :resource_dir, :style_name, :server_css, :branch_regex, :tag_regex, :local_only, :doc_attributes,
+        :resolve_docid, :make_searchable, :search_action_path, :abort_on_error, :log_level, :srcdir, :dstdir, :web_path
 
-  USAGE = <<~ENDUSAGE
-    Usage:
-      giblish [options] source_dir_top dest_dir_top
-  ENDUSAGE
-  HELP = <<ENDHELP
- Options:
-  -h --help                  show this help text
-  -v --version               show version nr and exit
-  -f --format <format>       the output format, currently html or pdf are supported
-                             *html* is used if -f is not supplied
-  -n --no-build-ref          suppress generation of a reference document at the destination
-                             tree root.
-  --index-basename           set the name of the generated index file (default 'index').
-  -r --resource-dir <dir>    specify a directory where fonts, themes, css and other
-                             central stuff needed for document generation are located.
-                             The resources are expected to be located in a subfolder
-                             whose name matches the resource type (font, theme
-                             or css). If no resource dir is specified, the asciidoctor
-                             defaults are used.
-  -s --style <name>          The style information used when converting the documents
-                             using the -r option for specifying resource directories.
-                             For html this is a name of a css file, for pdf, this is
-                             the name of an yml file. You can specify only the
-                             basename of the file and giblish will use the suffix
-                             associated with the output format (i.e specify 'mystyle'
-                             and the mystyle.css and mystyle.yml will be used for html
-                             and pdf generation respectively)
-  -i --include <regexp>      include only files with a path that matches the supplied
-                             regexp (defaults to '.*\.(?i)adoc$' meaning it matches all
-                             files ending in .adoc case-insensitive). The matching is made
-                             on the full path (i.e. the regex '^.*my.*' matches the path
-                             /my/file.adoc).
-  -j --exclude <regexp>      exclude files with a path that matches the supplied
-                             regexp (no files are excluded by default). The matching is made
-                             on the full path (i.e. the regex '^.*my.*' matches the path
-                             /my/file.adoc).
-  -w --web-path <path>       Specifies the URL path to where the generated html documents
-                             will be deployed (only needed when serving the html docs via
-                             a web server).
-                             E.g.
-                             If the docs are deployed to 'www.example.com/site_1/blah',
-                             this flag shall be set to '/site_1/blah'. This switch is only
-                             used when generating html. giblish use this to link the deployed
-                             html docs with the correct stylesheet.
-  -g --git-branches <regExp> if the source_dir_top is located within a git repo,
-                             generate docs for all _remote branches on origin_ that matches
-                             the given regular expression. Each git branch will
-                             be generated to a separate subdir under the destination
-                             root dir.
-                             NOTE: To do this, giblish will _explicitly check out the
-                             matching branches and merge them with the corresponding
-                             branch on origin_.
-                             NOTE 2: In bash, use double quotes around your regexp if
-                             you need to quote it. Single quotes are treated as part
-                             of the regexp itself.
-  -t --git-tags <regExp>     if the source_dir_top is located within a git repo,
-                             generate docs for all tags that matches the given
-                             regular expression. Each tag will be generated to
-                             a separate subdir under the destination root dir.
-  -c --local-only            do not try to fetch git info from any remotes of
-                             the repo before generating documents.
-  -a --attribute <key>=<value> set a document or asciidoctor attribute.
-                             The contents of this flag is passed directly to the
-                             underlying asciidoctor tool, for details above the
-                             syntax and available attributes, see the documentation for
-                             asciidoctor. This option can be specified more than once.
-  -d --resolve-docid         use two passes, the first to collect :docid:
-                             attributes in the doc headers, the second to
-                             generate the documents and use the collected
-                             doc ids to resolve relative paths between the
-                             generated documents
-  -m --make-searchable       (only supported for html generation)
-                             take steps to make it possible to
-                             search the published content via a cgi-script. This
-                             flag will do the following:
-                               1. index all headings in all source files and store
-                                  the result in a JSON file
-                               2. copy the JSON file and all source (adoc) files to
-                                  a 'search_assets' folder in the top-level dir of
-                                  the destination.
-                               3. add html code that displays a search field in the
-                                  index page that will try to call the cgi-script
-                                  'giblish-search' when the user inputs some text.
-                             To actually provide search functionality for a user, you
-                             need to provide the cgi-script and configure your web-server
-                             to invoke it when needed. NOTE: The generated search box cgi
-                             is currently hard-coded to look for the cgi script at the URL:
-                             http://<your-web-domain>/cgi-bin/giblish-search.cgi
-                             E.g.
-                             http://example.com/cgi-bin/giblish-search.cgi
-                             An implementation of the giblish-search cgi-script is found
-                             within the lib folder of this gem, you can copy that to your
-                             cgi-bin dir in your webserver and rename it from .rb to .cgi
-  -mp, --search-assets-deploy <path> the absolute path to the 'search_assets' folder where the search
-                             script can find the data needed for implementing the text search
-                             (default is <dst_dir_top>).
-                             Set this to the file system path where the generated html
-                             docs will be deployed (if different from dst_dir_top):
-                             E.g.
-                             If the generated html docs will be deployed to the folder
-                             '/var/www/mysite/blah/mydocs,'
-                             this is what you shall set the path to.
-  --log-level                set the log level explicitly. Must be one of
-                             debug, info (default), warn, error or fatal.
-ENDHELP
+      OUTPUT_FORMATS = ["html", "pdf"]
 
-  def initialize(cmdline_args)
-    parse_cmdline cmdline_args
+      LOG_LEVELS = {
+        "debug" => Logger::DEBUG,
+        "info" => Logger::INFO,
+        "warn" => Logger::WARN,
+        "error" => Logger::ERROR,
+        "fatal" => Logger::FATAL
+      }
 
-    # handle help and version requests
-    if @args[:help]
-      puts USAGE
-      puts ""
-      puts HELP
-      exit 0
-    end
-    if @args[:version]
-      puts "Giblish v#{Giblish::VERSION}"
-      exit 0
-    end
-
-    # act on the parsed cmd line args
-    set_log_level
-    sanity_check_input
-    set_gitrepo_root
-  end
+      def initialize
+        @format = OUTPUT_FORMATS[0]
+        @publish_type = :local
+        @no_index = false
+        @index_basename = "index"
+        @graph_basename = "gibgraph"
+        @include_regex, @exclude_regex = /.*\.(?i)adoc$/, nil
+        @copy_asset_folders = nil
+        @resource_dir = nil
+        @style_name = nil
+        @server_css = nil
+        # TODO: remove this soon
+        @web_path = nil
+        @branch_regex, @tag_regex = nil, nil
+        @local_only = false
+        @doc_attributes = {}
+        @resolve_docid = false
+        @make_searchable = false
+        @search_action_path = nil
+        @abort_on_error = true
+        @log_level = "info"
+      end
 
-  def usage
-    USAGE
-  end
+      def define_options(parser)
+        parser.banner = "Usage: #{parser.program_name} [options] srcdir dstdir"
+        parser.separator ""
+        parser.separator "Converts asciidoc files found under 'srcdir' and store the converted"
+        parser.separator "files under 'dstdir'"
+        parser.separator ""
+        parser.separator "  Options:"
 
-  private
+        parser.on("-f", "--format [FORMAT]", OUTPUT_FORMATS,
+          "The output format of the converted files",
+          "Supported formats are: #{OUTPUT_FORMATS}") do |fmt|
+          @format = fmt
+        end
+        parser.on("-n", "--no-build-ref ", "Suppress generation of indices and",
+          "dependency graphs.") do |n|
+          @no_index = true
+        end
+        parser.on("--index-basename ", "Set the basename for generated index files",
+          "(default #{@index_basename})") do |name|
+          @index_basename = name
+        end
+        parser.on("-r", "--resource-dir [DIR]",
+          "Specify a directory tree within which fonts, themes, css and other",
+          "central stuff needed for document generation are located.",
+          "If no resource dir is specified, the asciidoctor",
+          "defaults are used. (default: nil)") do |resource_dir|
+          r = Pathname.new(resource_dir)
+          @resource_dir = (r.absolute? ? r : (Pathname.new(Dir.pwd) / r)).cleanpath
+        end
+        parser.on("-s", "--style [NAME]",
+          "The style information used when converting the documents",
+          "using the -r option for specifying resource directories.",
+          "For html this is a name of a css file, for pdf, this is",
+          "the name of an yml file. You can specify only the",
+          "basename of the file and giblish will use the suffix",
+          "associated with the output format (i.e specify 'mystyle'",
+          "and the mystyle.css and mystyle.yml will be used for html",
+          "and pdf generation respectively)",
+          "(default: nil -> use default style") do |style_name|
+          @style_name = style_name.to_s
+        end
+        parser.on("-i", "--include [REGEX]",
+          "include only files with a path that matches the supplied",
+          "regexp (defaults to #{@include_regex} meaning it matches all",
+          "files ending in .adoc case-insensitive). The matching is made",
+          "on the full path (i.e. the regex '^.*my.*' matches the path",
+          "/my/file.adoc).") do |regex_str|
+          @include_regex = Regexp.new(regex_str)
+        end
+        parser.on("-j", "--exclude [REGEX]",
+          "exclude files with a path that matches the supplied",
+          "regexp (no files are excluded by default). The matching is made",
+          "on the full path (i.e. the regex '^.*my.*' matches the path",
+          "/my/file.adoc).") do |regex_str|
+          @exclude_regex = Regexp.new(regex_str)
+        end
+        parser.on("--copy-asset-folders [REGEX]",
+          "copy the content of all folders matching the given regex.",
+          "The folders will be copied to the corresponding location under 'dstdir'",
+          "Default is to not copy any directories at all.",
+          "The matching is made on the full path (i.e. the regex '_assets$' matches the path",
+          "'my/subdir/doc_assets').") do |regex_str|
+          @copy_asset_folders = Regexp.new(regex_str)
+        end
+        parser.on("-w", "--web-path [PATH]",
+          "DEPRECATED!! You should use the server-search-path and",
+          "server-css-path flags instead.") do |path|
+          Giblog.logger.error { "The '-w' flag is DEPRECATED, use the '--server-search-path' and '--server-css-path' flags instead." }
+          @web_path = true
+        end
+        parser.on("--server-css-path [PATH]",
+          "Sets a specific path to the stylesheet used by the generated",
+          "html documents. This flag can be used instead of the 's' and",
+          "'r' flags if a pre-existing stylesheet exists at a known",
+          "location that is accessible from the generated documents via",
+          "an 'href' element.",
+          "This flag is only used for html generation.") do |path|
+          @server_css = Pathname.new(path)
+        end
+        parser.on("-g", "--git-branches [REGEX]",
+          "if the source_dir_top is located within a git repo,",
+          "generate docs for all _remote branches on origin_ that matches",
+          "the given regular expression. Each git branch will",
+          "be generated to a separate subdir under the destination",
+          "root dir.",
+          "NOTE: To do this, giblish will _explicitly check out the",
+          "matching branches and merge them with the corresponding",
+          "branch on origin_.",
+          "NOTE 2: In bash, use double quotes around your regexp if",
+          "you need to quote it. Single quotes are treated as part",
+          "of the regexp itself.") do |regex_str|
+            @branch_regex = Regexp.new(regex_str)
+          end
+        parser.on("-t", "--git-tags [REGEX]",
+          "if the source_dir_top is located within a git repo,",
+          "generate docs for all tags that matches the given",
+          "regular expression. Each tag will be generated to",
+          "a separate subdir under the destination root dir.") do |regex_str|
+            @tag_regex = Regexp.new(regex_str)
+          end
+        parser.on("-c", "--local-only",
+          "do not try to fetch git info from any remotes of",
+          "the repo before generating documents.") do |local_only|
+            @local_only = true
+          end
+        parser.on("-a", "--attribute [KEY=VALUE]",
+          "set a document or asciidoctor attribute.",
+          "The contents of this flag is passed directly to the",
+          "underlying asciidoctor tool, for details above the",
+          "syntax and available attributes, see the documentation for",
+          "asciidoctor. This option can be specified more than once.") do |attr_str|
+          tokens = attr_str.split("=")
+          raise OptionParser::InvalidArgument, "Document attributs must be specified as 'key=value'!" unless tokens.count == 2
+          @doc_attributes[tokens[0]] = tokens[1]
+        end
+        parser.on("-d", "--resolve-docid",
+          "Collect document ids in the form of :docid:",
+          "attributes in the doc headers. Use these ids to",
+          "resolve cross-references of docid:s from one document",
+          "to another.") do |d|
+          @resolve_docid = d
+        end
+        parser.on("-m", "--make-searchable",
+          "(only supported for html generation)",
+          "take steps to make it possible to search the generated",
+          "docs via the web server through which they are published.",
+          "This flag will do the following:",
+          "  1. index all headings in all source files and store",
+          "     the result in a JSON file",
+          "  2. copy the JSON file and all source (adoc) files to",
+          "     a 'search_assets' folder in the top-level dir of",
+          "     the destination.",
+          "  3. add html/javascript code that displays a search form",
+          "     at the top of the generated documents. The search form",
+          "     sends a html POST to the path specified with the ",
+          "     'server-search-path' flag when the user inputs some text.",
+          "To actually provide search functionality for readers, you",
+          "need to provide a server side script or application that can",
+          "respond to the html POST and return relevant info.",
+          "giblish contains most of the functionality for this and an",
+          "implementation of a cgi-script is bundled with this gem.") do |m|
+          @make_searchable = m
+        end
+        parser.on("--server-search-path URLPATH",
+          "the url path to which search requests are sent.",
+          "(default is #{@search_action_path}).",
+          "E.g.",
+          "If the search script resides under 'www.mysite.com/actions/gibsearch'",
+          "you would set this as '--server-search-path /actions/gibsearch'") do |p|
+          @search_action_path = Pathname.new(p)
+        end
+        parser.on("--continue", "Continue even if a conversion fails. Default is to stop") do
+          @abort_on_error = false
+        end
+        parser.on("-l", "--log-level LEVEL", LOG_LEVELS,
+          "set the log level explicitly. Must be one of",
+          LOG_LEVELS.keys.join(",").to_s, "(default 'info')") do |level|
+          @log_level = level
+        end
+        parser.on_tail("-h", "--help", "Show this message") do
+          puts parser
+          exit 0
+        end
+        parser.on_tail("-v", "--version", "Show version") do
+          puts "Giblish v#{Giblish::VERSION}"
+          exit 0
+        end
+      end
 
-  def set_log_level
-    log_level = @args[:logLevel] || "info"
-    case log_level
-    when "debug" then Giblog.logger.sev_threshold = Logger::DEBUG
-    when "info"  then Giblog.logger.sev_threshold = Logger::INFO
-    when "warn"  then Giblog.logger.sev_threshold = Logger::WARN
-    when "error" then Giblog.logger.sev_threshold = Logger::ERROR
-    when "fatal" then Giblog.logger.sev_threshold = Logger::FATAL
-    else
-      puts "Invalid log level specified. Run with -h to see supported levels"
-      puts USAGE
-      exit 1
+      # enable pattern matching of instances as if they were
+      # a hash
+      def deconstruct_keys(keys)
+        h = {}
+        instance_variables.each do |v|
+          value = instance_variable_get(v)
+          h[v[1..].to_sym] = value unless value.nil?
+        end
+        h
+      end
     end
-  end
-
-  def sanity_check_input
-    ensure_required_args
-    prevent_invalid_combos
-  end
 
-  def parse_cmdline(cmdline_args)
-    # default values for cmd line switches
-    @args = {
-      help: false,
-      version: false,
-      force: true,
-      format: "html",
-      # note that the single quotes are important for the regexp
-      includeRegexp: '.*\.(?i)adoc$',
-      excludeRegexp: nil,
-      flatten: false,
-      suppressBuildRef: false,
-      indexBaseName: "index",
-      localRepoOnly: false,
-      resolveDocid: false,
-      makeSearchable: false,
-      searchAssetsDeploy: nil,
-      webPath: nil
-    }
+    # converts the given cmd line args to an Options instance.
+    #
+    # Raises MissingArgument or InvalidArgument if the cmd line arg
+    # validation fails.
+    #
+    # === Returns
+    # the CmdLine::Options instance corresponding to the given cmd line args
+    def parse(args)
+      @cmd_opts = Options.new
+      @args = OptionParser.new do |parser|
+        @cmd_opts.define_options(parser)
+        parser.parse!(args)
 
-    # set default log level
-    Giblog.logger.sev_threshold = Logger::WARN
+        # take care of positional arguments
+        raise OptionParser::MissingArgument, "Both srcdir and dstdir must be provided!" unless args.count == 2
 
-    # defines args without a corresponding flag, the order is important
-    unflagged_args = %i[srcDirRoot dstDirRoot]
-
-    # parse cmd line
-    next_arg = unflagged_args.first
-    cmdline_args.each do |arg|
-      case arg
-      when "-h", "--help"         then @args[:help]      = true
-      when "-v", "--version"      then @args[:version]   = true
-      when "-f", "--format   "    then next_arg = :format
-      when "-r", "--resource-dir" then next_arg = :resourceDir
-      when "-n", "--no-build-ref" then @args[:suppressBuildRef] = true
-      when "--index-basename"     then next_arg = :indexBaseName
-      when "-i", "--include"      then next_arg = :includeRegexp
-      when "-j", "--exclude"      then next_arg = :excludeRegexp
-      when "-g", "--git-branches" then next_arg = :gitBranchRegexp
-      when "-t", "--git-tags"     then next_arg = :gitTagRegexp
-      when "-c", "--local-only"   then @args[:localRepoOnly] = true
-      when "-a", "--attribute"    then next_arg = :attributes
-      when "-d", "--resolve-docid" then @args[:resolveDocid] = true
-      when "-m", "--make-searchable" then @args[:makeSearchable] = true
-      when "-mp", "--search-assets-deploy" then next_arg = :searchAssetsDeploy
-      when "-s", "--style"        then next_arg = :userStyle
-      when "-w", "--web-path"     then next_arg = :webPath
-      when "--log-level"          then next_arg = :logLevel
-      else
-        if next_arg
-          if next_arg == :attributes
-            # support multiple invocations of -a
-            add_attribute arg
-          else
-            @args[next_arg] = arg
-          end
-          unflagged_args.delete(next_arg)
+        # we always work with absolute paths
+        @cmd_opts.srcdir, @cmd_opts.dstdir = [args[0], args[1]].collect do |arg|
+          d = Pathname.new(arg)
+          d = Pathname.new(Dir.pwd) / d unless d.absolute?
+          d.cleanpath
         end
-        next_arg = unflagged_args.first
+
+        validate_options(@cmd_opts)
       end
+      @cmd_opts
     end
-  end
 
-  # adds the str (must be in key=value format) to the
-  # user defined attributes
-  def add_attribute(attrib_str)
-    kv = attrib_str.split("=")
-    if kv.length != 2
-      puts "Invalid attribute format: #{attrib_str} Must be <key>=<value>"
-      exit 1
-    end
+    private
 
-    @args[:attributes] ||= {}
-    @args[:attributes][kv[0]] = kv[1]
-  end
+    # Raise InvalidArgument if an unsupported cmd line combo is
+    # discovered
+    def validate_options(opts)
+      unless opts.branch_regex || opts.tag_regex
+        # If git branches/tags are given, the source path might exist in the branch/tag, thus only check this
+        # for non-git executions
+        raise OptionParser::InvalidArgument, "Could not find source path #{opts.srcdir}" unless opts.srcdir.exist?
+      end
 
-  def prevent_invalid_combos
-    # Prevent contradicting options
-    if !@args[:resourceDir] && @args[:userStyle]
-      puts "Error: The given style would not be used since no resource dir "\
-           "was specified (-s specified without -r)"
-    elsif @args[:makeSearchable] && @args[:format] != "html"
-      puts "Error: The --make-searchable option is only supported for "\
-           "html rendering."
-    elsif @args[:searchAssetsDeploy] && !@args[:makeSearchable]
-      puts "Error: The --search-assets-deploy (-mp) flag is only supported in "\
-           "combination with the --make-searchable (-m) flag."
-    else
-      return
-    end
+      if opts.web_path
+        raise OptionParser::InvalidArgument, "The '-w/--web-path' flag is DEPRECATED. Use the --server-css-path and --server--search-path flags instead."
+      end
 
-    puts USAGE
-    exit 1
-  end
+      if opts.server_css && (opts.resource_dir || opts.style_name)
+        raise OptionParser::InvalidArgument, "The '-w' flag can not be used with either of the '-r' or '-s' flags"
+      end
 
-  def ensure_required_args
-    # Exit if the user does not supply the required arguments
-    return unless !@args[:srcDirRoot] || !@args[:dstDirRoot]
+      if opts.server_css && opts.format != "html"
+        raise OptionParser::InvalidArgument, "The '-w' flag can only be used for the 'html' format flags"
+      end
 
-    puts "Error: Too few arguments."
-    puts USAGE
-    exit 1
-  end
+      if opts.resource_dir.nil? ^ opts.style_name.nil?
+        raise OptionParser::InvalidArgument, "Either both '-s' and '-r' flags must be given or none of them."
+      end
 
-  def set_gitrepo_root
-    # if user don't want no git repo, we're done
-    return unless @args[:gitBranchRegexp] || @args[:gitTagRegexp]
+      if opts.resource_dir && !opts.resource_dir.exist?
+        raise OptionParser::InvalidArgument, "Could not find resource path #{opts.resource_dir}"
+      end
 
-    # The user wants to parse a git repo, check that the srcDirRoot is within a
-    # git repo if the user wants to generate git-branch specific docs
-    @args[:gitRepoRoot] = Giblish::PathManager.find_gitrepo_root(
-      @args[:srcDirRoot]
-    )
-    return unless @args[:gitRepoRoot].nil?
+      if opts.make_searchable && opts.format != "html"
+        raise OptionParser::InvalidArgument, "Error: The --make-searchable option "\
+        "is only supported for html rendering."
+      end
 
-    # We should not get here if everything is koscher...
-    puts "Error: Source dir not in a git working dir despite -g or -t option given!"
-    puts USAGE
-    exit 1
+      if opts.search_action_path && !opts.make_searchable
+        raise OptionParser::InvalidArgument, "Error: The --server-search-path "\
+        "flag is only supported in combination with the --make-searchable (-m) flag."
+      end
+    end
   end
 end

data/lib/giblish/config_utils.rb

@@ -0,0 +1,41 @@
+module Giblish
+  # delegates all method calls to the first supplied delegate that
+  # implements it.
+  class DataDelegator
+    attr_reader :delegates
+
+    def initialize(*delegate_arr)
+      @delegates = Array(delegate_arr)
+    end
+
+    def add(delegate)
+      @delegates << delegate
+    end
+
+    # define this to short-cut circular references
+    #
+    # TODO: This should probably be avoided by refactoring the SuccessfulConversion
+    # class which, as of this writing, is part of a circular ref to a PathTree which
+    # throws 'inspect' calls into an eternal loop instead of implementing a custom 'inspect'
+    # method.
+    def inspect
+      @delegates.map do |d|
+        "<#{d.class}:#{d.object_id}>"
+      end.join(",")
+    end
+
+    def method_missing(m, *args, &block)
+      del = @delegates&.find { |d| d.respond_to?(m) }
+
+      del.nil? ? super : del.send(m, *args, &block)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      ok = @delegates.find { |d|
+        d.respond_to?(method_name)
+      }
+
+      ok || super(method_name, include_private)
+    end
+  end
+end