jsduck 5.3.4 → 6.0.0beta

data/lib/jsduck/member_registry.rb

@@ -0,0 +1,41 @@
+require "jsduck/tag_registry"
+
+module JsDuck
+
+  # Access to member tags
+  class MemberRegistry
+    class << self
+      # Same as #definitions, but returns just the names of member types.
+      def names
+        definitions.map {|mt| mt[:name] }
+      end
+
+      # Returns array of available member type definitions.
+      # Sorted in the order defined by :position.
+      def definitions
+        if !@definitions
+          @definitions = TagRegistry.tags.find_all do |tag|
+            tag.respond_to?(:member_type) && tag.member_type
+          end.map do |tag|
+            cfg = tag.member_type
+            cfg[:name] = tag.tagname
+            cfg
+          end
+          @definitions.sort! {|a, b| a[:position] <=> b[:position] }
+        end
+
+        @definitions
+      end
+
+      # Regex for matching member type name in member reference.
+      #
+      # The regex matches strings like: "method-" or "event-".  It
+      # contains a capture group to capture the actual name of the
+      # member, leaving out the dash "-".
+      def regex
+        @regex ||= Regexp.new("(?:(" + names.join("|") + ")-)")
+      end
+    end
+  end
+
+end

data/lib/jsduck/news.rb

@@ -7,7 +7,7 @@ module JsDuck
     # Creates News object from relations data when --import option
     # specified.
     def self.create(relations, doc_formatter, opts)
-      if opts[:imports].length > 0
+      if opts.import.length > 0
         News.new(relations, doc_formatter)
       else
         Util::NullObject.new(:to_html => "")
@@ -63,10 +63,11 @@ module JsDuck
       new_items
     end
 
+    # Returns all members of a class that have been marked as new, or
+    # have parameters marked as new.
     def filter_new_members(cls)
-      members = []
-      cls.all_local_members.each do |m|
-        members << m if m[:new] && visible?(m)
+      members = cls.all_local_members.find_all do |m|
+        visible?(m) && (m[:new] || new_params?(m))
       end
       members = discard_accessors(members)
       members.sort! {|a, b| a[:name] <=> b[:name] }
@@ -76,6 +77,10 @@ module JsDuck
       !member[:private] && !member[:hide]
     end
 
+    def new_params?(member)
+      Array(member[:params]).any? {|p| p[:new] }
+    end
+
     def discard_accessors(members)
       accessors = {}
       members.find_all {|m| m[:accessor] }.each do |cfg|
@@ -127,7 +132,15 @@ module JsDuck
       if m[:tagname] == :class
         @doc_formatter.link(m[:name], nil, m[:name])
       else
-        @doc_formatter.link(m[:owner], m[:name], m[:name], m[:tagname], m[:static])
+        @doc_formatter.link(m[:owner], m[:name], m[:name], m[:tagname], m[:static]) + params_note(m)
+      end
+    end
+
+    def params_note(m)
+      if !m[:new] && new_params?(m)
+        " <small>+parameters</small>"
+      else
+        ""
       end
     end
 

data/lib/jsduck/options/config.rb

@@ -0,0 +1,35 @@
+require 'jsduck/util/json'
+
+module JsDuck
+  module Options
+
+    # Handles reading JSON config file, specified by --config option.
+    class Config
+
+      # Reads JSON configuration from file and returns an array of
+      # config options that can be feeded into optparser.
+      def self.read(filename)
+        config = []
+        json = Util::Json.read(filename)
+        json.each_pair do |key, value|
+          if key == "--"
+            # filenames
+            config += Array(value).map(&:to_s)
+          elsif value == true
+            # simple switch
+            config += [key.to_s]
+          else
+            # An option with value or with multiple values.
+            # In the latter case, add the option multiple times.
+            Array(value).each do |v|
+              config += [key.to_s, v.to_s]
+            end
+          end
+        end
+        config
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/options/helpful_parser.rb

@@ -0,0 +1,111 @@
+require 'optparse'
+
+module JsDuck
+  module Options
+
+    # JSDuck version of OptionParser
+    #
+    # Enhanced with ability to output options help in two ways:
+    #
+    # - short list of all options (with the built-in #help method)
+    # - long description of one option (with the added #help_single method)
+    #
+    class HelpfulParser < ::OptionParser
+      def initialize
+        @full_options_index = {}
+        super
+      end
+
+      # Override the #on method to do some pre-processing on its
+      # parameters before passing them to the original #on method.
+      #
+      # Options are defined as usual:
+      #
+      #     opts.on("-v", "--version", Type, "First line of description.",
+      #             "Second line of description.",
+      #             "Third line of description.")
+      #
+      # But only the first line of description will be passed to
+      # original #on method - meaning that #help method will also only
+      # list this first line.
+      #
+      # The remaining lines are saved to a separate place and can be
+      # retrieved through asking for full docs for an option with
+      # #help_single method.
+      #
+      def on(*opts, &block)
+        core = []
+        keys = []
+        desc = []
+
+        desc_started = false
+        opts.each do |o|
+          if desc_started
+            desc << o
+          elsif String === o
+            if o =~ /^-/
+              core << o
+              keys << o
+            else
+              core << o
+              desc << o
+              desc_started = true
+            end
+          else
+            core << o
+          end
+        end
+
+        full = {:keys => keys, :desc => desc}
+
+        keys.each do |op|
+          each_index_key(op) {|k| @full_options_index[k] = full }
+        end
+
+        super(*core, &block)
+      end
+
+      # Helper that turns option name like --images=PATH into list of
+      # keys by which we index the options:
+      #
+      #     "--images=PATH" --> ["--images", "images"]
+      #
+      # For options containing "[no-]" all the alternative forms are expanded:
+      #
+      #     "--[no-]seo"    --> ["--[no-]seo", "[no-]seo", "--seo", "seo", "--no-seo", "no-seo"]
+      #
+      def each_index_key(option_name)
+        key = option_name.sub(/\[?=.*/, '')
+        plain_key = key.sub(/^-*/, '')
+        [key, plain_key].each do |k|
+          yield k
+          if k =~ /\[no-\]/
+            yield k.sub(/\[no-\]/, '')
+            yield k.sub(/\[no-\]/, 'no-')
+          end
+        end
+      end
+
+      # Returns long help text for a single option.
+      def help_single(option_name)
+        o = @full_options_index[option_name] || {:keys => [option_name], :desc => ["No such option. See --help=help"]}
+
+        r = []
+
+        r << ""
+        r << "    " + o[:keys].join(", ")
+        r << ""
+
+        o[:desc].each do |line|
+          r << "            " + line
+        end
+
+        r << ""
+        r << ""
+
+        return r.join("\n")
+      end
+    end
+
+  end
+end

data/lib/jsduck/options/input_files.rb

@@ -0,0 +1,60 @@
+require 'jsduck/options/jsb'
+require 'jsduck/logger'
+
+module JsDuck
+  module Options
+
+    # Finalizes the list of input files.
+    class InputFiles
+      def initialize(opts)
+        @opts = opts
+      end
+
+      # Expands opts.input_files (modifying its contents):
+      #
+      # - When file is a directory, scans all JS, SCSS files in there.
+      # - When file is a .jsb3 file, extracts list of files from it.
+      # - Otherwise returns array with this same input filename.
+      #
+      # Then excludes the files and dirs listed in opts.exclude.
+      def expand!
+        @opts.input_files = expand_files(@opts.input_files)
+        exclude_files!(@opts.input_files, @opts.exclude)
+      end
+
+      private
+
+      def expand_files(unexpanded_files)
+        unexpanded_files.map {|fname| expand_filename(fname) }.flatten
+      end
+
+      def expand_filename(fname)
+        files = []
+
+        if File.exists?(fname)
+          if File.directory?(fname)
+            Dir[fname+"/**/*.{js,scss}"].each {|f| files << f }
+          elsif fname =~ /\.jsb3$/
+            Options::Jsb.read(fname).each {|fn| read_filenames(fn) }
+          else
+            files << fname
+          end
+        else
+          Logger.warn(nil, "File not found", {:filename => fname})
+        end
+
+        files
+      end
+
+      # Removes the files matching exclude_paths from list of files
+      def exclude_files!(files, exclude_paths)
+        exclude_paths.each do |exclude_path|
+          exclude_re = Regexp.new('\A' + Regexp.escape(exclude_path))
+          files.reject! {|f| f =~ exclude_re }
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/options/jsb.rb

@@ -0,0 +1,25 @@
+require 'jsduck/util/json'
+
+module JsDuck
+  module Options
+
+    # Handles reading of JSB3 files.
+    class Jsb
+
+      # Extracts files of first build in JSB3 file.
+      def self.read(filename)
+        json = Util::Json.read(filename)
+        basedir = File.dirname(filename)
+
+        return json["builds"][0]["packages"].map do |package_id|
+          package = json["packages"].find {|p| p["id"] == package_id }
+          (package ? package["files"] : []).map do |file|
+            File.expand_path(basedir + "/" + file["path"] + file["name"])
+          end
+        end.flatten
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/{options.rb → options/parser.rb}

@@ -1,221 +1,95 @@
-require 'jsduck/option_parser'
+require 'jsduck/options/helpful_parser'
+require 'jsduck/options/record'
+require 'jsduck/options/config'
+require 'jsduck/warning/parser'
+require 'jsduck/warning/warn_exception'
 require 'jsduck/logger'
-require 'jsduck/util/json'
-require 'jsduck/util/os'
 require 'jsduck/util/io'
-require 'jsduck/util/parallel'
-require 'jsduck/tag_registry'
-require 'jsduck/js/ext_patterns'
-require 'jsduck/warning/parser'
 require 'jsduck/version'
 
 module JsDuck
+  module Options
 
-  # Keeps command line options
-  class Options
-    attr_accessor :input_files
-
-    attr_accessor :output_dir
-    attr_accessor :ignore_global
-    attr_accessor :external_classes
-    attr_accessor :ext4_events
-
-    # Customizing output
-    attr_accessor :title
-    attr_accessor :header
-    attr_accessor :footer
-    attr_accessor :head_html
-    attr_accessor :body_html
-    attr_accessor :css
-    attr_accessor :message
-    attr_accessor :welcome
-    attr_accessor :guides
-    attr_accessor :videos
-    attr_accessor :examples
-    attr_accessor :categories_path
-    attr_accessor :source
-    attr_accessor :images
-    attr_accessor :link_tpl
-    attr_accessor :img_tpl
-    attr_accessor :export
-    attr_accessor :seo
-    attr_accessor :eg_iframe
-    attr_accessor :examples_base_url
-    attr_accessor :tests
-    attr_accessor :comments_url
-    attr_accessor :comments_domain
-    attr_accessor :search
-    attr_accessor :ignore_html
-
-    # Debugging
-    attr_accessor :warnings_exit_nonzero
-    attr_accessor :cache
-    attr_accessor :cache_dir
-    attr_accessor :template_dir
-    attr_accessor :template_links
-    attr_accessor :extjs_path
-    attr_accessor :local_storage_db
-    attr_accessor :touch_examples_ui
-    attr_accessor :ext_namespaces
-    attr_accessor :imports
-    attr_accessor :new_since
-
-    def initialize
-      @input_files = []
-      @exclude = []
-
-      @output_dir = nil
-      @ignore_global = false
-      @external_classes = [
-        # JavaScript builtins
-        "Object",
-        "String",
-        "Number",
-        "Boolean",
-        "RegExp",
-        "Function",
-        "Array",
-        "Arguments",
-        "Date",
-        # JavaScript builtin error classes
-        # https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error
-        "Error",
-        "EvalError",
-        "RangeError",
-        "ReferenceError",
-        "SyntaxError",
-        "TypeError",
-        "URIError",
-        # DOM
-        "HTMLElement",
-        "XMLElement",
-        "NodeList",
-        "TextNode",
-        "CSSStyleSheet",
-        "CSSStyleRule",
-        "Event",
-        # Other browser-environment classes
-        "Window",
-        "XMLHttpRequest",
-        # Special anything-goes type
-        "Mixed",
-      ]
-      @ext4_events = nil
-
-      # Customizing output
-      @title = "Documentation - JSDuck"
-      @header = "<strong>Documentation</strong> JSDuck"
-      @footer = format_footer("Generated on {DATE} by {JSDUCK} {VERSION}.")
-      @head_html = ""
-      @body_html = ""
-      @css = ""
-      @message = ""
-      @welcome = nil
-      @guides = nil
-      @videos = nil
-      @examples = nil
-      @categories_path = nil
-      @source = true
-      @images = []
-      @custom_tag_paths = []
-      @link_tpl = '<a href="#!/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
-      # Note that we wrap image template inside <p> because {@img} often
-      # appears inline within text, but that just looks ugly in HTML
-      @img_tpl = '<p><img src="%u" alt="%a" width="%w" height="%h"></p>'
-      @export = nil
-      @seo = false
-      @eg_iframe = nil
-      @examples_base_url = "extjs-build/examples/"
-      @tests = false
-      @comments_url = nil
-      @comments_domain = nil
-      @search = {}
-      @ignore_html = {}
-
-      # Debugging
-      @warnings_exit_nonzero = false
-      @cache = false
-      @cache_dir = nil
-      @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
-      @template_dir = @root_dir + "/template-min"
-      @template_links = false
-      @extjs_path = "extjs/ext-all.js"
-      @local_storage_db = "docs"
-      @touch_examples_ui = false
-      @imports = []
-      @new_since = nil
-
-      # Turn multiprocessing off by default in Windows
-      Util::Parallel.in_processes = Util::OS::windows? ? 0 : nil
-
-      # Enable all warnings except the following:
-      Logger.set_warning(:all, true)
-      Logger.set_warning(:link_auto, false)
-      Logger.set_warning(:param_count, false)
-      Logger.set_warning(:fires, false)
-      Logger.set_warning(:nodoc, false)
-
-      @optparser = create_option_parser
-    end
+    # Performs parsing of JSDuck options.
+    class Parser
 
-    # Make options object behave like hash.
-    # This allows us to substitute it with hash in unit tests.
-    def [](key)
-      instance_variable_get("@#{key}")
-    end
-    def []=(key, value)
-      instance_variable_set("@#{key}", value)
-    end
+      def initialize(file_class=File, config_class=Options::Config)
+        @file = file_class
+        @config = config_class
 
-    def parse!(argv)
-      parse_options(argv)
-      auto_detect_config_file unless @config_option_specified
-      exclude_input_files
-      validate
-
-      if @custom_tag_paths.length > 0
-        TagRegistry.reconfigure(@custom_tag_paths)
-      else
-        # Ensure the TagRegistry get instantiated just once.
-        # Otherwise the parallel processing causes multiple requests
-        # to initialize the TagRegistry, resulting in loading the Tag
-        # definitions multiple times.
-        TagRegistry.instance
+        @opts = Options::Record.new
+        @defaults = {}
+
+        @root_dir = @file.dirname(@file.dirname(@file.dirname(@file.dirname(__FILE__))))
+
+        @optparser = Options::HelpfulParser.new
+        init_parser
+      end
+
+      # Parses array of command line options, returning
+      # Options::Record object containing all the options.
+      def parse(argv)
+        init_defaults
+        parse_options(argv)
+        auto_detect_config_file unless @opts.config
+        @opts
       end
-    end
 
-    private
-
-    def create_option_parser
-      return JsDuck::OptionParser.new do | opts |
-        opts.banner = "Usage: jsduck [options] files/dirs..."
-        opts.separator ""
-        opts.separator "For example:"
-        opts.separator ""
-        opts.separator "    # Documentation for builtin JavaScript classes like Array and String"
-        opts.separator "    jsduck --output output/dir  --builtin-classes"
-        opts.separator ""
-        opts.separator "    # Documentation for your own JavaScript"
-        opts.separator "    jsduck --output output/dir  input-file.js some/input/dir"
-        opts.separator ""
-        opts.separator "The main options:"
-        opts.separator ""
-
-        opts.on('-o', '--output=PATH',
+      private
+
+      def init_parser
+        banner "Usage: jsduck [options] files/dirs..."
+
+        separator ""
+        separator "For example:"
+        separator ""
+        separator "    # Documentation for builtin JavaScript classes like Array and String"
+        separator "    jsduck --output output/dir  --builtin-classes"
+        separator ""
+        separator "    # Documentation for your own JavaScript"
+        separator "    jsduck --output output/dir  input-file.js some/input/dir"
+        separator ""
+        separator "The main options:"
+        separator ""
+
+        attribute :input_files, []
+        validator :input_files do
+          if @opts.input_files.empty? && !@opts.welcome && !@opts.guides && !@opts.videos && !@opts.examples
+            "Please specify some input files, otherwise there's nothing I can do :("
+          end
+        end
+
+        attribute :output
+        option('-o', '--output=PATH',
           "Directory to write all this documentation.",
           "",
           "This option is REQUIRED.  When the directory exists,",
           "it will be overwritten.  Give dash '-' as argument",
           "to write docs to STDOUT (works only with --export).") do |path|
           if path == "-"
-            @output_dir = :stdout
+            @opts.output = :stdout
           else
-            @output_dir = canonical(path)
-            @cache_dir = @output_dir + "/.cache" unless @cache_dir
+            @opts.output = canonical(path)
+            @opts.cache_dir = @opts.output + "/.cache" unless @opts.cache_dir
+          end
+        end
+        validator :output do
+          if @opts.output == :stdout
+            # No output dir needed for export
+            if !@opts.export
+              "Output to STDOUT only works when using --export option"
+            end
+          elsif !@opts.output
+            "Please specify an output directory, where to write all this amazing documentation"
+          elsif @file.exists?(@opts.output) && !@file.directory?(@opts.output)
+            "The output directory is not really a directory at all :("
+          elsif !@file.exists?(@file.dirname(@opts.output))
+            "The parent directory for #{@opts.output} doesn't exist"
           end
         end
 
-        opts.on('--export=full/examples',
+        attribute :export
+        option('--export=full/examples',
           "Exports docs in JSON.",
           "",
           "For each JavaScript class a JSON file gets written,",
@@ -223,16 +97,15 @@ module JsDuck
           "",
           "- full     - docs and metadata for class and its members.",
           "- examples - inline examples from classes and guides.") do |format|
-          export_type = format.to_sym
-          if [:full, :examples].include?(export_type)
-            @export = export_type
-          else
-            Logger.fatal("Unsupported export type: '#{export_type}'")
-            exit(1)
+          @opts.export = format.to_sym
+        end
+        validator :export do
+          if ![nil, :full, :examples].include?(@opts.export)
+            "Unknown export format: #{@opts.export}"
           end
         end
 
-        opts.on('--builtin-classes',
+        option('--builtin-classes',
           "Includes docs for JavaScript builtins.",
           "",
           "Docs for the following classes are included:",
@@ -245,18 +118,22 @@ module JsDuck
           "- Object",
           "- RegExp",
           "- String") do
-          read_filenames(@root_dir + "/js-classes")
+          @opts.input_files << @root_dir + "/js-classes"
         end
 
-        opts.on('--seo', "Enables SEO-friendly print version.",
+        attribute :seo, false
+        option('--[no-]seo', "Enables SEO-friendly print version. (OFF)",
           "",
           "Instead of index.html creates index.php that will serve",
           "the regular docs, print-friendly docs, and search-engine-",
-          "friendly docs (the latter two are pretty much the same).") do
-          @seo = true
+          "friendly docs (the latter two are pretty much the same).",
+          "",
+          "Disabled by default.") do |on|
+          @opts.seo = on
         end
 
-        opts.on('--config=PATH',
+        attribute :config
+        option('--config=PATH',
           "Loads config options from JSON file.",
           "",
           "An alternative to listing all options on command line.",
@@ -266,7 +143,7 @@ module JsDuck
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Config-file") do |path|
           path = canonical(path)
-          if File.exists?(path)
+          if @file.exists?(path)
             config = read_json_config(path)
           else
             Logger.fatal("The config file #{path} doesn't exist")
@@ -274,30 +151,33 @@ module JsDuck
           end
           # treat paths inside JSON config relative to the location of
           # config file.  When done, switch back to current working dir.
-          @working_dir = File.dirname(path)
+          @working_dir = @file.dirname(path)
           parse_options(config)
           @working_dir = nil
-          @config_option_specified = true
+          @opts.config = path
         end
 
-        opts.on('--encoding=NAME', "Input encoding (defaults to UTF-8).") do |encoding|
-          JsDuck::Util::IO.encoding = encoding
+        attribute :encoding
+        option('--encoding=NAME', "Input encoding (defaults to UTF-8).") do |encoding|
+          @opts.encoding = encoding
         end
 
-        opts.on('--exclude=PATH', "Exclude input file or directory.",
+        attribute :exclude, []
+        option('--exclude=PATH1,PATH2', Array, "Exclude input file or directory.",
           "",
           "For example to include all the subdirs of",
           "/app/js except /app/js/new, run JSDuck with:",
           "",
-          "  jsduck /app/js --exclude /app/js/new") do |path|
-          @exclude << path
+          "  jsduck /app/js --exclude /app/js/new") do |paths|
+          @opts.exclude += paths.map {|p| canonical(p) }
         end
 
-        opts.separator ""
-        opts.separator "Customizing output:"
-        opts.separator ""
+        separator ""
+        separator "Customizing output:"
+        separator ""
 
-        opts.on('--title=TEXT',
+        attribute :title, "Documentation - JSDuck"
+        option('--title=TEXT',
           "Custom title text for the documentation.",
           "",
           "Defaults to 'Documentation - JSDuck'",
@@ -305,11 +185,11 @@ module JsDuck
           "The title will be used both inside <title> and in",
           "the header of the page.  Inside page header the left",
           "part (from ' - ' separator) will be shown in bold.") do |text|
-          @title = text
-          @header = text.sub(/^(.*?) +- +/, "<strong>\\1 </strong>")
+          @opts.title = text
         end
 
-        opts.on('--footer=TEXT',
+        attribute :footer, "Generated on {DATE} by {JSDUCK} {VERSION}."
+        option('--footer=TEXT',
           "Custom footer text for the documentation.",
           "",
           "The text can contain various placeholders:",
@@ -319,10 +199,11 @@ module JsDuck
           "  {VERSION} - JSDuck version number.",
           "",
           "Defaults to: 'Generated on {DATE} by {JSDUCK} {VERSION}.'") do |text|
-          @footer = format_footer(text)
+          @opts.footer = text
         end
 
-        opts.on('--head-html=HTML',
+        attribute :head_html, ""
+        option('--head-html=HTML',
           "HTML for the <head> section of index.html.",
           "",
           "Useful for adding extra <style> and other tags.",
@@ -332,10 +213,11 @@ module JsDuck
           "",
           "This option can be used repeatedly to append several",
           "things to the header.") do |html|
-          @head_html += maybe_file(html)
+          @opts.head_html += maybe_file(html)
         end
 
-        opts.on('--body-html=HTML',
+        attribute :body_html, ""
+        option('--body-html=HTML',
           "HTML for the <body> section of index.html.",
           "",
           "Useful for adding extra markup to the page.",
@@ -345,10 +227,11 @@ module JsDuck
           "",
           "This option can be used repeatedly to append several",
           "things to the body.") do |html|
-          @body_html += maybe_file(html)
+          @opts.body_html += maybe_file(html)
         end
 
-        opts.on('--css=CSS',
+        attribute :css, ""
+        option('--css=CSS',
           "Extra CSS rules to include to the page.",
           "",
           "Also a name of a CSS file can be passed.",
@@ -356,19 +239,21 @@ module JsDuck
           "",
           "This option can be used repeatedly to append multiple",
           "chunks of CSS.") do |css|
-          @css += maybe_file(css)
+          @opts.css += maybe_file(css)
         end
 
-        opts.on('--message=HTML',
+        attribute :message, ""
+        option('--message=HTML',
           "(Warning) message to show prominently.",
           "",
           "Useful for warning users that they are viewing an old",
           "version of the docs, and prividing a link to the new",
           "version.") do |html|
-          @message += html
+          @opts.message += html
         end
 
-        opts.on('--welcome=PATH',
+        attribute :welcome
+        option('--welcome=PATH',
           "File with content for welcome page.",
           "",
           "Either HTML or Markdown file with content for welcome page.",
@@ -376,10 +261,11 @@ module JsDuck
           "Markdown file must have a .md or .markdown extension.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Welcome-page") do |path|
-          @welcome = canonical(path)
+          @opts.welcome = canonical(path)
         end
 
-        opts.on('--guides=PATH',
+        attribute :guides
+        option('--guides=PATH',
           "JSON file describing the guides.",
           "",
           "The file should be in a dir containing the actual guides.",
@@ -387,55 +273,86 @@ module JsDuck
           "other images referenced by the README.md file.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Guides") do |path|
-          @guides = canonical(path)
+          @opts.guides = canonical(path)
         end
 
-        opts.on('--videos=PATH',
+        attribute :guides_toc_level, 2
+        option('--guides-toc-level=LEVEL',
+          "Max heading level for guides' tables of contents.",
+          "",
+          "Values between 1 and 6 define the maximum level of a heading",
+          "to be included into guides' Table of Contents:",
+          "",
+          "1 - Hides the table of contents.",
+          "2 - <H2> headings are included.",
+          "3 - <H2>,<H3> headings are included.",
+          "4 - <H2>,<H3>,<H4> headings are included.",
+          "5 - <H2>,<H3>,<H4>,<H5> headings are included.",
+          "6 - <H2>,<H3>,<H4>,<H5>,<H6> headings are included.") do |level|
+          @opts.guides_toc_level = level.to_i
+        end
+        validator :guides_toc_level do
+          if !(1..6).include?(@opts.guides_toc_level)
+            "Unsupported --guides-toc-level: '#{@opts.guides_toc_level}'"
+          end
+        end
+
+        attribute :videos
+        option('--videos=PATH',
           "JSON file describing the videos.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Videos") do |path|
-          @videos = canonical(path)
+          @opts.videos = canonical(path)
         end
 
-        opts.on('--examples=PATH',
+        attribute :examples
+        option('--examples=PATH',
           "JSON file describing the examples.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Examples") do |path|
-          @examples = canonical(path)
+          @opts.examples = canonical(path)
         end
 
-        opts.on('--categories=PATH',
+        attribute :categories
+        option('--categories=PATH',
           "JSON file defining categories for classes.",
           "",
           "Without this option the classes will be categorized",
           "based on how they are namespaced.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Categories") do |path|
-          @categories_path = canonical(path)
+          @opts.categories = canonical(path)
         end
 
-        opts.on('--no-source',
-          "Turns off the output of source files.") do
-          @source = false
+        attribute :source, true
+        option('--[no-]source',
+          "Enables output of source files. (ON)",
+          "",
+          "Enabled by default.") do |on|
+          @opts.source = on
         end
 
-        opts.on('--images=PATH',
-          "Path for images referenced by {@img} tag.",
+        attribute :images, []
+        option('--images=PATH1,PATH2', Array,
+          "Paths for images referenced by {@img} tag.",
           "",
-          "Several paths can be specified by using the option",
-          "multiple times.  This option only applies to {@img}",
-          "tags used in API (classes/members) documentation.",
-          "Images used in guides must be located inside the",
-          "directory of the specific guide.") do |path|
-          @images << canonical(path)
+          "This option only applies to {@img} tags used in",
+          "API (classes/members) documentation.  Images used",
+          "in guides must be located inside the directory of",
+          "the specific guide.") do |paths|
+          @opts.images += paths.map {|p| canonical(p) }
         end
 
-        opts.on('--tests',
-          "Creates page for testing inline examples.") do
-          @tests = true
+        attribute :tests, false
+        option('--[no-]tests',
+          "Creates page for testing inline examples. (OFF)",
+          "",
+          "Disabled by default.") do |on|
+          @opts.tests = on
         end
 
-        opts.on('--import=VERSION:PATH',
+        attribute :import, []
+        option('--import=VERSION:PATH',
           "Imports docs generating @since & @new.",
           "",
           "For example:",
@@ -455,32 +372,35 @@ module JsDuck
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/@since") do |v|
           if v =~ /\A(.*?):(.*)\z/
-            @imports << {:version => $1, :path => canonical($2)}
+            @opts.import << {:version => $1, :path => canonical($2)}
           else
-            @imports << {:version => v}
+            @opts.import << {:version => v}
           end
         end
 
-        opts.on('--new-since=VERSION',
+        attribute :new_since
+        option('--new-since=VERSION',
           "Since when to label items with @new tag.",
           "",
           "The VERSION must be one of the version names defined",
           "with --import option.",
           "",
           "Defaults to the last version listed by --import.") do |v|
-          @new_since = v
+          @opts.new_since = v
         end
 
-        opts.on('--comments-url=URL',
+        attribute :comments_url
+        option('--comments-url=URL',
           "Address of comments server.",
           "",
           "For example: http://projects.sencha.com/auth",
           "",
           "Must be used together with --comments-domain option.") do |url|
-          @comments_url = url
+          @opts.comments_url = url
         end
 
-        opts.on('--comments-domain=STRING',
+        attribute :comments_domain
+        option('--comments-domain=STRING',
           "A name identifying the subset of comments.",
           "",
           "A string consisting of <name>/<version>.",
@@ -488,10 +408,11 @@ module JsDuck
           "For example: ext-js/4",
           "",
           "Must be used together with --comments-url option.") do |domain|
-          @comments_domain = domain
+          @opts.comments_domain = domain
         end
 
-        opts.on('--search-url=URL',
+        attribute :search, {}
+        option('--search-url=URL',
           "Address of guides search server.",
           "",
           "When supplied, the search for guides is performed through this",
@@ -503,10 +424,10 @@ module JsDuck
           "Must be used together with --search-domain option.",
           "",
           "This option is EXPERIMENTAL.") do |url|
-          @search[:url] = url
+          @opts.search[:url] = url
         end
 
-        opts.on('--search-domain=STRING',
+        option('--search-domain=STRING',
           "A name identifying the subset to search from.",
           "",
           "A string consisting of <name>/<version>.",
@@ -519,27 +440,27 @@ module JsDuck
           "Must be used together with --search-url option.",
           "",
           "This option is EXPERIMENTAL.") do |domain|
-          @search[:product], @search[:version] = domain.split(/\//)
+          @opts.search[:product], @opts.search[:version] = domain.split(/\//)
         end
 
-        opts.separator ""
-        opts.separator "Tweaking:"
-        opts.separator ""
+        separator ""
+        separator "Tweaking:"
+        separator ""
 
-        opts.on('--tags=PATH',
-          "Path to custom tag implementations.",
-          "",
-          "Can be a path to single Ruby file or a directory.",
+        attribute :tags, []
+        option('--tags=PATH1,PATH2', Array,
+          "Paths to custom tag implementations.",
           "",
-          "This option can be used repeatedly to include multiple",
-          "tags from different places.",
+          "Paths can point to specific Ruby files or to a directory,",
+          "in which case all ruby files in that directory are loaded.",
           "",
-          "See also: https://github.com/senchalabs/jsduck/wiki/Custom-tags") do |path|
-          @custom_tag_paths << canonical(path)
+          "See also: https://github.com/senchalabs/jsduck/wiki/Custom-tags") do |paths|
+          @opts.tags += paths.map {|p| canonical(p) }
         end
 
-        opts.on('--ignore-global',
-          "Turns off the creation of 'global' class.",
+        attribute :ignore_global, false
+        option('--[no-]ignore-global',
+          "Turns off the creation of 'global' class. (OFF)",
           "",
           "The 'global' class gets created when members that",
           "don't belong to any class are found - all these",
@@ -547,11 +468,36 @@ module JsDuck
           "",
           "Using this option won't suppress the warning that's",
           "given when global members are found.  For that you",
-          "need to additionally use --warnings=-global") do
-          @ignore_global = true
-        end
-
-        opts.on('--external=Foo,Bar,Baz', Array,
+          "need to additionally use --warnings=-global",
+          "",
+          "Disabled by default.") do |on|
+          @opts.ignore_global = on
+        end
+
+        attribute :external, [
+          # JavaScript builtins
+          "Object",
+          "String",
+          "Number",
+          "Boolean",
+          "RegExp",
+          "Function",
+          "Array",
+          "Arguments",
+          "Date",
+          # JavaScript builtin error classes
+          # https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error
+          "Error",
+          "EvalError",
+          "RangeError",
+          "ReferenceError",
+          "SyntaxError",
+          "TypeError",
+          "URIError",
+          # Special anything-goes type
+          "Mixed",
+        ]
+        option('--external=Foo,Bar,Baz', Array,
           "Declares list of external classes.",
           "",
           "These classes will then no more generate warnings",
@@ -562,12 +508,30 @@ module JsDuck
           "",
           "The wildcard '*' can be used to match a set of classes",
           "e.g. to ignore all classes of a particular namespace:",
-          "--external='Foo.*'") do |classes|
-          @external_classes += classes
+          "",
+          "  --external='Foo.*'",
+          "",
+          "The special keyword '@browser' includes a slew of standard",
+          "browser API classes like HTMLElement and XMLHttpRequest:",
+          "",
+          "  --external='@browser'",
+          "",
+          "The list of these classes comes from Mozilla docs, not",
+          "including experimental, non-standard or obsolete APIs:",
+          "https://developer.mozilla.org/en-US/docs/Web/API",
+          "",
+          "NB! If you only need to reference a few of these classes",
+          "in your docs, it's better to define these explicitly, as",
+          "using '@browser' will bring along a slew of names like",
+          "Node, Attr, Blob, CSS, Range, Element, which you might",
+          "mistakenly use in your docs by writing Node instead of",
+          "MyNamespace.Node and JSDuck won't warn you about it.") do |classes|
+          @opts.external += classes
         end
 
-        opts.on('--[no-]ext4-events',
-          "Forces Ext4 options param on events.",
+        attribute :ext4_events
+        option('--[no-]ext4-events',
+          "Forces Ext4 options param on events. (AUTO)",
           "",
           "In Ext JS 4 and Sencha Touch 2 all event handlers are",
           "passed an additional options object at the end of the",
@@ -580,18 +544,20 @@ module JsDuck
           "classes using Ext.define(), and only then append the",
           "options parameter.  This should work most of the time.",
           "",
-          "Use this option to override the auto-detection.") do |e|
-          @ext4_events = e
+          "Use this option to override the auto-detection.") do |on|
+          @opts.ext4_events = on
         end
 
-        opts.on('--examples-base-url=URL',
+        attribute :examples_base_url
+        option('--examples-base-url=URL',
           "Base URL for examples with relative URL-s.",
           " ",
           "Defaults to: 'extjs-build/examples/'") do |path|
-          @examples_base_url = path
+          @opts.examples_base_url = path
         end
 
-        opts.on('--link=TPL',
+        attribute :link, '<a href="#!/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
+        option('--link=TPL',
           "HTML template for replacing {@link}.",
           "",
           "Possible placeholders:",
@@ -604,10 +570,11 @@ module JsDuck
           "%a - anchor text for link",
           "",
           "Defaults to: '<a href=\"#!/api/%c%-%m\" rel=\"%c%-%m\" class=\"docClass\">%a</a>'") do |tpl|
-          @link_tpl = tpl
+          @opts.link = tpl
         end
 
-        opts.on('--img=TPL',
+        attribute :img, '<p><img src="%u" alt="%a" width="%w" height="%h"></p>'
+        option('--img=TPL',
           "HTML template for replacing {@img}.",
           "",
           "Possible placeholders:",
@@ -618,10 +585,11 @@ module JsDuck
           "%h - height of image",
           "",
           "Defaults to: '<p><img src=\"%u\" alt=\"%a\" width=\"%w\" height=\"%h\"></p>'") do |tpl|
-          @img_tpl = tpl
+          @opts.img = tpl
         end
 
-        opts.on('--eg-iframe=PATH',
+        attribute :eg_iframe
+        option('--eg-iframe=PATH',
           "HTML file used to display inline examples.",
           "",
           "The file will be used inside <iframe> that renders the",
@@ -630,10 +598,11 @@ module JsDuck
           "with the example code.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Inline-examples") do |path|
-          @eg_iframe = canonical(path)
+          @opts.eg_iframe = canonical(path)
         end
 
-        opts.on('--ext-namespaces=Ext,Foo', Array,
+        attribute :ext_namespaces
+        option('--ext-namespaces=Ext,Foo', Array,
           "Additional Ext JS namespaces to recognize.",
           "",
           "Defaults to 'Ext'",
@@ -644,18 +613,22 @@ module JsDuck
           "and JSDuck will recognize both Ext.define() and",
           "YourNs.define() plus few other things that depend on",
           "Ext namespace like Ext.emptyFn.") do |namespaces|
-          Js::ExtPatterns.set(namespaces)
+          @opts.ext_namespaces = namespaces
         end
 
-        opts.on('--touch-examples-ui',
-          "Turns on phone/tablet UI for examples.",
+        attribute :touch_examples_ui, false
+        option('--[no-]touch-examples-ui',
+          "Turns on phone/tablet UI for examples. (OFF)",
           "",
           "This is a very Sencha Touch 2 docs specific option.",
-          "Effects both normal- and inline-examples.") do
-          @touch_examples_ui = true
+          "Effects both normal- and inline-examples.",
+          "",
+          "Disabled by default") do |on|
+          @opts.touch_examples_ui = on
         end
 
-        opts.on('--ignore-html=TAG1,TAG2', Array,
+        attribute :ignore_html, {}
+        option('--ignore-html=TAG1,TAG2', Array,
           "Ignore a particular unclosed HTML tag.",
           "",
           "Normally all tags like <foo> that aren't followed at some",
@@ -668,15 +641,16 @@ module JsDuck
           "<locale> and <debug> which would otherwise be reported",
           "as unclosed tags.") do |tags|
           tags.each do |tag|
-            @ignore_html[tag] = true
+            @opts.ignore_html[tag] = true
           end
         end
 
-        opts.separator ""
-        opts.separator "Performance:"
-        opts.separator ""
+        separator ""
+        separator "Performance:"
+        separator ""
 
-        opts.on('-p', '--processes=COUNT',
+        attribute :processes
+        option('-p', '--processes=COUNT',
           "The number of parallel processes to use.",
           "",
           "Defaults to the number of processors/cores.",
@@ -686,13 +660,17 @@ module JsDuck
           "results.",
           "",
           "In Windows this option is disabled.") do |count|
-          Util::Parallel.in_processes = count.to_i
+          @opts.processes = count.to_i
+        end
+        validator :processes do
+          if @opts.processes.to_i < 0
+            "Number of processes must be a positive number."
+          end
         end
 
-        opts.on('--[no-]cache',
-          "Turns parser cache on/off (EXPERIMENTAL).",
-          "",
-          "Defaults to off.",
+        attribute :cache, false
+        option('--[no-]cache',
+          "Turns parser cache on/off. (OFF)",
           "",
           "When enabled, the results of parsing source files is saved",
           "inside the JSDuck output directory. Next time JSDuck runs,",
@@ -704,11 +682,14 @@ module JsDuck
           "don't invalidate the cache, so avoid caching when developing",
           "your custom tags.",
           "",
-          "To change the cache directory location, use --cache-dir.") do |enabled|
-          @cache = enabled
+          "To change the cache directory location, use --cache-dir.",
+          "",
+          "Disabled by default.") do |on|
+          @opts.cache = on
         end
 
-        opts.on('--cache-dir=PATH',
+        attribute :cache_dir
+        option('--cache-dir=PATH',
           "Directory where to cache the parsed source.",
           "",
           "Defaults to: <output-dir>/.cache",
@@ -726,29 +707,34 @@ module JsDuck
           "won't work.",
           "",
           "This option only has an effect when --cache is also used.") do |path|
-          @cache_dir = path
+          @opts.cache_dir = path
         end
 
-        opts.separator ""
-        opts.separator "Debugging:"
-        opts.separator ""
+        separator ""
+        separator "Debugging:"
+        separator ""
 
-        opts.on('-v', '--verbose',
+        attribute :verbose, false
+        option('-v', '--verbose',
           "Turns on excessive logging.",
           "",
           "Log messages are written to STDERR.") do
-          Logger.verbose = true
+          @opts.verbose = true
         end
 
-        opts.on('--warnings=+A,-B,+C',
+        attribute :warnings, []
+        option('--warnings=+A,-B,+C',
           "Turns warnings selectively on/off.",
           "",
           " +all - to turn on all warnings.",
           " -all - to turn off all warnings.",
           "",
           "Additionally a pattern can be specified to only apply the",
-          "setting for a particular set of files.  For example to turn",
-          "off all warnings related to chart classes:",
+          "setting for a particular set of files.  (The pattern is just",
+          "a string against which the the full path of each filename",
+          "gets matched - attempting to use a pattern like '../foo' will",
+          "fail.)  For example to turn off all warnings related to chart",
+          "classes:",
           "",
           " -all:extjs/src/chart",
           "",
@@ -761,68 +747,91 @@ module JsDuck
           "",
           *Logger.doc_warnings) do |warnings|
           begin
-            Warning::Parser.new(warnings).parse.each do |w|
-              Logger.set_warning(w[:type], w[:enabled], w[:path], w[:params])
-            end
+            @opts.warnings += Warning::Parser.new(warnings).parse
           rescue Warning::WarnException => e
             Logger.warn(nil, e.message)
           end
         end
 
-        opts.on('--warnings-exit-nonzero',
-          "Exits with non-zero exit code on warnings.",
+        attribute :warnings_exit_nonzero, false
+        option('--[no-]warnings-exit-nonzero',
+          "Exits with non-zero exit code on warnings. (OFF)",
           "",
           "By default JSDuck only exits with non-zero exit code",
           "when a fatal error is encountered (code 1).",
           "",
           "With this option the exit code will be 2 when any warning",
-          "gets printed.") do
-          @warnings_exit_nonzero = true
+          "gets printed.") do |on|
+          @opts.warnings_exit_nonzero = on
         end
 
-        opts.on('--[no-]color',
-          "Turn on/off colorized terminal output.",
+        attribute :color
+        option('--[no-]color',
+          "Turn on/off colorized terminal output. (AUTO)",
           "",
           "By default the colored output is on, but gets disabled",
           "automatically when output is not an interactive terminal",
           "(or when running on Windows system).") do |on|
-          Logger.colors = on
+          @opts.color = on
         end
 
-        opts.on('--pretty-json',
-          "Turns on pretty-printing of JSON.",
+        attribute :pretty_json
+        option('--[no-]pretty-json',
+          "Turns on pretty-printing of JSON. (OFF)",
           "",
           "This is useful when studying the JSON files generated",
           "by --export option.  But the option effects any JSON",
           "that gets generated, so it's also useful when debugging",
-          "the resource files generated for the docs app.") do
-          Util::Json.pretty = true
+          "the resource files generated for the docs app.") do |on|
+          @opts.pretty_json = on
         end
 
-        opts.on('--template=PATH',
+        attribute :template, @root_dir + "/template-min"
+        option('--template=PATH',
           "Dir containing the UI template files.",
           "",
           "Useful when developing the template files.") do |path|
-          @template_dir = canonical(path)
+          @opts.template = canonical(path)
+        end
+        validator :template do
+          if @opts.export
+            # Don't check these things when exporting
+          elsif !@file.exists?(@opts.template + "/extjs")
+            [
+              "Oh noes!  The template directory does not contain extjs/ directory :(",
+              "Please copy ExtJS over to template/extjs or create symlink.",
+              "For example:",
+              "    $ cp -r /path/to/ext-4.0.0 " + @opts.template + "/extjs",
+            ]
+          elsif !@file.exists?(@opts.template + "/resources/css")
+            [
+              "Oh noes!  CSS files for custom ExtJS theme missing :(",
+              "Please compile SASS files in template/resources/sass with compass.",
+              "For example:",
+              "    $ compass compile " + @opts.template + "/resources/sass",
+            ]
+          end
         end
 
-        opts.on('--template-links',
-          "Creates symlinks to UI template files.",
+        attribute :template_links, false
+        option('--[no-]template-links',
+          "Creates symlinks to UI template files. (OFF)",
           "",
           "Useful for template files development.",
-          "Only works on platforms supporting symbolic links.") do
-          @template_links = true
+          "Only works on platforms supporting symbolic links.") do |on|
+          @opts.template_links = on
         end
 
-        opts.on('-d', '--debug',
+        option('-d', '--debug',
           "Same as --template=template --template-links.",
           "",
           "Useful shorthand during development.") do
-          @template_dir = canonical("template")
-          @template_links = true
+          @opts.template = canonical("template")
+          @opts.template_links = true
         end
 
-        opts.on('--extjs-path=PATH',
+        attribute :extjs_path, "extjs/ext-all.js"
+        option('--extjs-path=PATH',
           "Path for main ExtJS JavaScript file.",
           "",
           "This is the ExtJS file that's used by the docs app UI.",
@@ -830,17 +839,18 @@ module JsDuck
           "Defaults to extjs/ext-all.js",
           "",
           "Useful for switching to extjs/ext-all-debug.js in development.") do |path|
-          @extjs_path = path # NB! must be relative path
+          @opts.extjs_path = path # NB! must be relative path
         end
 
-        opts.on('--local-storage-db=NAME',
+        attribute :local_storage_db, "docs"
+        option('--local-storage-db=NAME',
           "Prefix for LocalStorage database names.",
           "",
           "Defaults to 'docs'") do |name|
-          @local_storage_db = name
+          @opts.local_storage_db = name
         end
 
-        opts.on('-h', '--help[=--some-option]',
+        option('-h', '--help[=--some-option]',
           "Use --help=--option for help on option.",
           "",
           "For example To get help on --processes option any of the",
@@ -851,159 +861,101 @@ module JsDuck
           "    --help=-p",
           "    --help=p") do |v|
           if v
-            puts opts.help_single(v)
+            puts @optparser.help_single(v)
           else
-            puts opts.help
+            puts @optparser.help
           end
           exit
         end
 
-        opts.on('--version', "Prints JSDuck version") do
+        option('--version', "Prints JSDuck version") do
           puts "JSDuck " + JsDuck::VERSION + " (Ruby #{RUBY_VERSION})"
           exit
         end
       end
-    end
 
-    # Parses the given command line options
-    # (could have also been read from config file)
-    def parse_options(options)
-      @optparser.parse!(options).each {|fname| read_filenames(canonical(fname)) }
-    end
+      # A little language for describing the options.
+      # Simple delegetions to @optparser and @opts.
 
-    # Reads jsduck.json file in current directory
-    def auto_detect_config_file
-      fname = Dir.pwd + "/jsduck.json"
-      if File.exists?(fname)
-        Logger.log("Auto-detected config file", fname)
-        parse_options(read_json_config(fname))
+      def banner(txt)
+        @optparser.banner = txt
       end
-    end
 
-    # Reads JSON configuration from file and returns an array of
-    # config options that can be feeded into optparser.
-    def read_json_config(fname)
-      config = []
-      json = Util::Json.read(fname)
-      json.each_pair do |key, value|
-        if key == "--"
-          # filenames
-          config += Array(value).map(&:to_s)
-        elsif value == true
-          # simple switch
-          config += [key.to_s]
-        else
-          # An option with value or with multiple values.
-          # In the latter case, add the option multiple times.
-          Array(value).each do |v|
-            config += [key.to_s, v.to_s]
-          end
-        end
+      def separator(txt)
+        @optparser.separator(txt)
       end
-      config
-    end
 
-    # scans directory for .js files or simply adds file to input files list
-    def read_filenames(fname)
-      if File.exists?(fname)
-        if File.directory?(fname)
-          Dir[fname+"/**/*.{js,css,scss}"].each {|f| @input_files << f }
-        elsif fname =~ /\.jsb3$/
-          extract_jsb_files(fname).each {|fn| read_filenames(fn) }
-        else
-          @input_files << fname
-        end
-      else
-        Logger.warn(nil, "File not found", fname)
+      def option(*params, &block)
+        @optparser.on(*params, &block)
       end
-    end
 
-    # When --exclude option used, removes the files matching the
-    # exclude path from @input_files
-    def exclude_input_files
-      @exclude.each do |exclude_path|
-        exclude_re = Regexp.new('\A' + Regexp.escape(canonical(exclude_path)))
-        @input_files.reject! {|f| f =~ exclude_re }
+      def attribute(name, value=nil)
+        @opts.attribute(name, value)
+        @defaults[name] = value
       end
-    end
 
-    # Extracts files of first build in jsb file
-    def extract_jsb_files(jsb_file)
-      json = Util::Json.read(jsb_file)
-      basedir = File.dirname(jsb_file)
+      def validator(name, &block)
+        @opts.validator(name, &block)
+      end
 
-      return json["builds"][0]["packages"].map do |package_id|
-        package = json["packages"].find {|p| p["id"] == package_id }
-        (package ? package["files"] : []).map do |file|
-          File.expand_path(basedir + "/" + file["path"] + file["name"])
+      # Initializes attributes with default values.  This is needed to
+      # be able to run the most tests without re-instantiating this
+      # class every time.
+      def init_defaults
+        @defaults.each_pair do |name, value|
+          @opts.send(:"#{name}=", clone(value))
         end
-      end.flatten
-    end
+      end
 
-    # When given string is a file, returns the contents of the file.
-    # Otherwise returns the string unchanged.
-    def maybe_file(str)
-      path = canonical(str)
-      if File.exists?(path)
-        Util::IO.read(path)
-      else
-        str
+      # clones hashes and arrays.
+      def clone(obj)
+        (obj.is_a?(Array) || obj.is_a?(Hash)) ? obj.clone : obj
       end
-    end
 
-    # Converts relative path to full path
-    #
-    # Especially important for running on Windows where C:\foo\bar
-    # pathnames are converted to C:/foo/bar which ruby can work on
-    # more easily.
-    def canonical(path)
-      File.expand_path(path, @working_dir)
-    end
+      # Parses the given command line options
+      # (could have also been read from config file)
+      def parse_options(options)
+        @optparser.parse!(options).each do |fname|
+          @opts.input_files << canonical(fname)
+        end
+      end
 
-    # Replace special placeholders in footer text
-    def format_footer(text)
-      jsduck = "<a href='https://github.com/senchalabs/jsduck'>JSDuck</a>"
-      date = Time.new.strftime('%a %d %b %Y %H:%M:%S')
-      text.gsub(/\{VERSION\}/, JsDuck::VERSION).gsub(/\{JSDUCK\}/, jsduck).gsub(/\{DATE\}/, date)
-    end
+      # Reads jsduck.json file in current directory
+      def auto_detect_config_file
+        fname = Dir.pwd + "/jsduck.json"
+        if @file.exists?(fname)
+          Logger.log("Auto-detected config file", fname)
+          parse_options(read_json_config(fname))
+        end
+      end
+
+      # Reads JSON configuration from file and returns an array of
+      # config options that can be feeded into optparser.
+      def read_json_config(filename)
+        @config.read(filename)
+      end
 
-    # Runs checks on the options
-    def validate
-      if @input_files.length == 0 && !@welcome && !@guides && !@videos && !@examples
-        Logger.fatal("You should specify some input files, otherwise there's nothing I can do :(")
-        exit(1)
-      elsif @output_dir == :stdout && !@export
-        Logger.fatal("Output to STDOUT only works when using --export option")
-        exit(1)
-      elsif ![nil, :full, :api, :examples].include?(@export)
-        Logger.fatal("Unknown export format: #{@export}")
-        exit(1)
-      elsif @output_dir != :stdout
-        if !@output_dir
-          Logger.fatal("You should also specify an output directory, where I could write all this amazing documentation")
-          exit(1)
-        elsif File.exists?(@output_dir) && !File.directory?(@output_dir)
-          Logger.fatal("The output directory is not really a directory at all :(")
-          exit(1)
-        elsif !File.exists?(File.dirname(@output_dir))
-          Logger.fatal("The parent directory for #{@output_dir} doesn't exist")
-          exit(1)
-        elsif !@export && !File.exists?(@template_dir + "/extjs")
-          Logger.fatal("Oh noes!  The template directory does not contain extjs/ directory :(")
-          Logger.fatal("Please copy ExtJS over to template/extjs or create symlink.")
-          Logger.fatal("For example:")
-          Logger.fatal("    $ cp -r /path/to/ext-4.0.0 " + @template_dir + "/extjs")
-          exit(1)
-        elsif !@export && !File.exists?(@template_dir + "/resources/css")
-          Logger.fatal("Oh noes!  CSS files for custom ExtJS theme missing :(")
-          Logger.fatal("Please compile SASS files in template/resources/sass with compass.")
-          Logger.fatal("For example:")
-          Logger.fatal("    $ compass compile " + @template_dir + "/resources/sass")
-          exit(1)
+      # When given string is a file, returns the contents of the file.
+      # Otherwise returns the string unchanged.
+      def maybe_file(str)
+        path = canonical(str)
+        if @file.exists?(path)
+          Util::IO.read(path)
+        else
+          str
         end
       end
+
+      # Converts relative path to full path
+      #
+      # Especially important for running on Windows where C:\foo\bar
+      # pathnames are converted to C:/foo/bar which ruby can work on
+      # more easily.
+      def canonical(path)
+        @file.expand_path(path, @working_dir)
+      end
+
     end
 
   end
-
 end