etude_for_ruby 0.1.0 → 0.1.4

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/display.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # Display one object
+    # @since 0.8.6
+    class Display < Yardoc
+      def description; 'Displays a formatted object' end
+
+      def initialize(*args)
+        super
+        options.format = :text # default for this command
+        @layout = nil
+        @objects = []
+      end
+
+      # Runs the commandline utility, parsing arguments and displaying an object
+      # from the {Registry}.
+      #
+      # @param [Array<String>] args the list of arguments.
+      # @return [void]
+      def run(*args)
+        return unless parse_arguments(*args)
+        log.puts wrap_layout(format_objects)
+      end
+
+      # @return [String] the output data for all formatted objects
+      def format_objects
+        @objects.inject([]) do |arr, obj|
+          arr.push obj.format(options)
+        end.join("\n")
+      end
+
+      def wrap_layout(contents)
+        return contents unless @layout
+        opts = options.merge(
+          :contents => contents,
+          :object => @objects.first,
+          :objects => @objects
+        )
+        args = [options.template, @layout, options.format]
+        Templates::Engine.template(*args).run(opts)
+      end
+
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
+      def parse_arguments(*args)
+        opts = OptionParser.new
+        opts.banner = "Usage: yard display [options] OBJECT [OTHER OBJECTS]"
+        general_options(opts)
+        output_options(opts)
+        parse_options(opts, args)
+
+        Registry.load
+        @objects = args.map {|o| Registry.at(o) }
+
+        # validation
+        return false if @objects.any?(&:nil?)
+        verify_markup_options
+      end
+
+      def output_options(opts)
+        super(opts)
+        opts.on('-l', '--layout [LAYOUT]', 'Wraps output in layout template (good for HTML)') do |layout|
+          @layout = layout || 'layout'
+        end
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/gems.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # @since 0.6.0
+    class Gems < Command
+      def initialize
+        @rebuild = false
+        @gems = []
+      end
+
+      def description; "Builds YARD index for gems" end
+
+      # Runs the commandline utility, parsing arguments and generating
+      # YARD indexes for gems.
+      #
+      # @param [Array<String>] args the list of arguments
+      # @return [void]
+      def run(*args)
+        require 'rubygems'
+        optparse(*args)
+        build_gems
+      end
+
+      private
+
+      # Builds .yardoc files for all non-existing gems
+      def build_gems
+        require 'rubygems'
+        @gems.each do |spec|
+          ver = "= #{spec.version}"
+          dir = Registry.yardoc_file_for_gem(spec.name, ver)
+          if dir && File.directory?(dir) && !@rebuild
+            log.debug "#{spec.name} index already exists at '#{dir}'"
+          else
+            yfile = Registry.yardoc_file_for_gem(spec.name, ver, true)
+            next unless yfile
+            next unless File.directory?(spec.full_gem_path)
+            Registry.clear
+            Dir.chdir(spec.full_gem_path) do
+              log.info "Building yardoc index for gem: #{spec.full_name}"
+              Yardoc.run('--no-stats', '-n', '-b', yfile)
+            end
+          end
+        end
+      end
+
+      def add_gems(gems)
+        0.step(gems.size - 1, 2) do |index|
+          gem = gems[index]
+          ver_require = gems[index + 1] || ">= 0"
+          specs = YARD::GemIndex.find_all_by_name(gem, ver_require)
+          if specs.empty?
+            log.warn "#{gem} #{ver_require} could not be found in RubyGems index"
+          else
+            @gems += specs
+          end
+        end
+      end
+
+      # Parses options
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = 'Usage: yard gems [options] [gem_name [version]]'
+        opts.separator ""
+        opts.separator "#{description}. If no gem_name is given,"
+        opts.separator "all gems are built."
+        opts.separator ""
+        opts.on('--rebuild', 'Rebuilds index') do
+          @rebuild = true
+        end
+
+        common_options(opts)
+        parse_options(opts, args)
+        add_gems(args)
+
+        if !args.empty? && @gems.empty?
+          log.error "No specified gems could be found for command"
+        elsif @gems.empty?
+          @gems += YARD::GemIndex.all if @gems.empty?
+        end
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/graph.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # Options to pass to the {Graph} CLI.
+    class GraphOptions < Templates::TemplateOptions
+      # @return [:dot] the default output format
+      default_attr :format, :dot
+
+      # @return [Boolean] whether to list the full class diagram
+      attr_accessor :full
+
+      # @return [Boolean] whether to show the object dependencies
+      attr_accessor :dependencies
+
+      # @return [String] any contents to pass to the digraph
+      attr_accessor :contents
+    end
+
+    # A command-line utility to generate Graphviz graphs from
+    # a set of objects
+    #
+    # @see Graph#run
+    # @since 0.6.0
+    class Graph < YardoptsCommand
+      # The options parsed out of the commandline.
+      # Default options are:
+      #   :format => :dot
+      attr_reader :options
+
+      # The set of objects to include in the graph.
+      attr_reader :objects
+
+      # Creates a new instance of the command-line utility
+      def initialize
+        super
+        @use_document_file = false
+        @options = GraphOptions.new
+        options.reset_defaults
+        options.serializer = YARD::Serializers::StdoutSerializer.new
+      end
+
+      def description
+        "Graphs class diagram using Graphviz"
+      end
+
+      # Runs the command-line utility.
+      #
+      # @example
+      #   grapher = Graph.new
+      #   grapher.run('--private')
+      # @param [Array<String>] args each tokenized argument
+      def run(*args)
+        parse_arguments(*args)
+
+        contents = objects.map do |o|
+          o.format(options.merge(:serialize => false))
+        end.join("\n")
+        opts = {:type => :layout, :contents => contents}
+        options.update(opts)
+        Templates::Engine.render(options)
+      end
+
+      private
+
+      def unrecognized_option(err) end
+
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
+      def optparse(*args)
+        visibilities = [:public]
+        opts = OptionParser.new
+
+        opts.separator ""
+        opts.separator "General Options:"
+
+        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to load from or save to. (defaults to .yardoc)') do |yfile|
+          YARD::Registry.yardoc_file = yfile
+        end
+
+        opts.on('--full', 'Full class diagrams (show methods and attributes).') do
+          options[:full] = true
+        end
+
+        opts.on('-d', '--dependencies', 'Show mixins in dependency graph.') do
+          options[:dependencies] = true
+        end
+
+        opts.on('--no-public', "Don't show public methods. (default shows public)") do
+          visibilities.delete(:public)
+        end
+
+        opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
+          visibilities.push(:protected)
+        end
+
+        opts.on('--private', "Show or don't show private methods. (default hides private)") do
+          visibilities.push(:private)
+        end
+
+        opts.separator ""
+        opts.separator "Output options:"
+
+        opts.on('--dot [OPTIONS]', 'Send the results directly to `dot` with optional arguments.') do |dotopts|
+          options.serializer = Serializers::ProcessSerializer.new('dot ' + dotopts.to_s)
+        end
+
+        opts.on('-f', '--file [FILE]', 'Writes output to a file instead of stdout.') do |file|
+          options.serializer = Serializers::FileSystemSerializer.new(:basepath => '.', :extension => nil)
+          options.serializer.instance_eval "def serialized_path(object) #{file.inspect} end"
+        end
+
+        common_options(opts)
+        parse_options(opts, args)
+
+        Registry.load
+
+        expression = "#{visibilities.uniq.inspect}.include?(object.visibility)"
+        options.verifier = Verifier.new(expression)
+        @objects = args.first ?
+          args.map {|o| Registry.at(o) }.compact :
+          [Registry.root]
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/help.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # Handles help for commands
+    # @since 0.6.0
+    class Help < Command
+      def description; "Retrieves help for a command" end
+
+      def run(*args)
+        cmd = args.first && CommandParser.commands[args.first.to_sym]
+        if cmd
+          cmd.run('--help')
+        else
+          log.puts "Command #{args.first} not found." if args.first
+          CommandParser.run('--help')
+        end
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/i18n.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+require "pathname"
+
+module YARD
+  module CLI
+    # CLI command to support internationalization (a.k.a. i18n).
+    # I18n feature is based on gettext technology.
+    # This command generates .pot file from docstring and extra
+    # documentation.
+    #
+    # @since 0.8.0
+    # @todo Support msgminit and msgmerge features?
+    class I18n < Yardoc
+      def initialize
+        super
+        @options.serializer.basepath = "po/yard.pot"
+      end
+
+      def description
+        'Generates .pot file from source code and extra documentation'
+      end
+
+      def run(*args)
+        if args.empty? || !args.first.nil?
+          # fail early if arguments are not valid
+          return unless parse_arguments(*args)
+        end
+
+        YARD.parse(files, excluded)
+
+        serializer = options.serializer
+        pot_file_path = Pathname.new(serializer.basepath).expand_path
+        pot_file_dir_path, pot_file_basename = pot_file_path.split
+        relative_base_path = Pathname.pwd.relative_path_from(pot_file_dir_path)
+        serializer.basepath = pot_file_dir_path.to_s
+        serializer.serialize(pot_file_basename.to_s,
+                             generate_pot(relative_base_path.to_s))
+
+        true
+      end
+
+      private
+
+      def general_options(opts)
+        opts.banner = "Usage: yard i18n [options] [source_files [- extra_files]]"
+        opts.top.list.clear
+        opts.separator "(if a list of source files is omitted, "
+        opts.separator "  {lib,app}/**/*.rb ext/**/*.c is used.)"
+        opts.separator ""
+        opts.separator "Example: yard i18n -o yard.pot - FAQ LICENSE"
+        opts.separator "  The above example outputs .pot file for files in"
+        opts.separator "  lib/**/*.rb to yard.pot including the extra files"
+        opts.separator "  FAQ and LICENSE."
+        opts.separator ""
+        opts.separator "A base set of options can be specified by adding a .yardopts"
+        opts.separator "file to your base path containing all extra options separated"
+        opts.separator "by whitespace."
+        super(opts)
+      end
+
+      def generate_pot(relative_base_path)
+        generator = YARD::I18n::PotGenerator.new(relative_base_path)
+        objects = run_verifier(all_objects)
+        generator.parse_objects(objects)
+        generator.parse_files(options.files || [])
+        generator.generate
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/list.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # Lists all constant and method names in the codebase. Uses {Yardoc} --list.
+    class List < Command
+      def description; 'Lists all constant and methods. Uses `yard doc --list`' end
+
+      # Runs the commandline utility, parsing arguments and displaying a
+      # list of objects
+      #
+      # @param [Array<String>] args the list of arguments.
+      # @return [void]
+      def run(*args)
+        if args.include?('--help')
+          log.puts "Usage: yard list [yardoc_options]"
+          log.puts "Takes the same arguments as yardoc. See yardoc --help"
+        else
+          Yardoc.run('-c', '--list', *args)
+        end
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/markup_types.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # Lists all markup types
+    # @since 0.8.6
+    class MarkupTypes < Command
+      def description; 'Lists all available markup types and libraries' end
+
+      # Runs the commandline utility, parsing arguments and displaying a
+      # list of markup types
+      #
+      # @param [Array<String>] args the list of arguments.
+      # @return [void]
+      def run(*args) # rubocop:disable Lint/UnusedMethodArgument
+        log.puts "Available markup types for `doc' command:"
+        log.puts
+        types = Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS
+        exts = Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS
+        types.sort_by {|name, _| name.to_s }.each do |name, providers|
+          log.puts "[#{name}]"
+          libs = providers.map {|p| p[:lib] }.compact
+          log.puts "  Providers: #{libs.join(" ")}" unless libs.empty?
+          if exts[name]
+            log.puts "  Extensions: #{exts[name].map {|e| ".#{e}" }.join(" ")}"
+          end
+
+          log.puts
+        end
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/cli/server.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+module YARD
+  module CLI
+    # A local documentation server
+    # @since 0.6.0
+    class Server < Command
+      # @return [Hash] a list of options to pass to the doc server
+      attr_accessor :options
+
+      # @return [Hash] a list of options to pass to the web server
+      attr_accessor :server_options
+
+      # @return [Hash] a list of library names and yardoc files to serve
+      attr_accessor :libraries
+
+      # @return [Adapter] the adapter to use for loading the web server
+      attr_accessor :adapter
+
+      # @return [Array<String>] a list of scripts to load
+      # @since 0.6.2
+      attr_accessor :scripts
+
+      # @return [Array<String>] a list of template paths to register
+      # @since 0.6.2
+      attr_accessor :template_paths
+
+      # Creates a new instance of the Server command line utility
+      def initialize
+        super
+        self.scripts = []
+        self.template_paths = []
+        self.libraries = {}
+        self.options = SymbolHash.new(false).update(
+          :single_library => true,
+          :caching => false
+        )
+        self.server_options = {:Port => 8808}
+      end
+
+      def description
+        "Runs a local documentation server"
+      end
+
+      def run(*args)
+        optparse(*args)
+
+        select_adapter.setup
+        load_scripts
+        load_template_paths
+        adapter.new(libraries, options, server_options).start
+      end
+
+      private
+
+      def load_scripts
+        scripts.each {|file| load_script(file) }
+      end
+
+      def load_template_paths
+        return if YARD::Config.options[:safe_mode]
+        Templates::Engine.template_paths |= template_paths
+      end
+
+      def select_adapter
+        return adapter if adapter
+        require 'rubygems'
+        require 'rack'
+        self.adapter = YARD::Server::RackAdapter
+      rescue LoadError
+        self.adapter = YARD::Server::WebrickAdapter
+      end
+
+      def add_libraries(args)
+        (0...args.size).step(2) do |index|
+          library = args[index]
+          dir = args[index + 1]
+
+          libver = nil
+          if dir
+            if File.exist?(dir)
+              # Provided dir contains a .yardopts file
+              libver = create_library_version_if_yardopts_exist(library, dir)
+              libver ||= YARD::Server::LibraryVersion.new(library, nil, dir)
+            end
+          else
+            # Check if this dir contains a .yardopts file
+            pwd = Dir.pwd
+            libver = create_library_version_if_yardopts_exist(library, pwd)
+
+            # Check default location
+            yfile = File.join(pwd, Registry::DEFAULT_YARDOC_FILE)
+            libver ||= YARD::Server::LibraryVersion.new(library, nil, yfile)
+          end
+
+          # Register library
+          if libver
+            libver.yardoc_file = File.expand_path(libver.yardoc_file) if libver.yardoc_file
+            libver.source_path = File.expand_path(libver.source_path) if libver.source_path
+            libraries[library] ||= []
+            libraries[library] |= [libver]
+          else
+            log.warn "Cannot find yardoc db for #{library}: #{dir.inspect}"
+          end
+        end
+      end
+
+      # @param [String] library The library name.
+      # @param [String, nil] dir The argument provided on the CLI after the
+      #   library name. Is supposed to point to either a project directory
+      #   with a Yard options file, or a yardoc db.
+      # @return [LibraryVersion, nil]
+      def create_library_version_if_yardopts_exist(library, dir)
+        if dir
+          options_file = File.join(dir, Yardoc::DEFAULT_YARDOPTS_FILE)
+          if File.exist?(options_file)
+            # Found yardopts, extract db path
+            yfile = extract_db_from_options_file(options_file)
+            db = File.expand_path(yfile, dir)
+
+            # Create libver
+            libver = YARD::Server::LibraryVersion.new(library, nil, db)
+            libver.source_path = dir
+            libver
+          end
+        end
+      end
+
+      def add_gems
+        require 'rubygems'
+        YARD::GemIndex.each do |spec|
+          libraries[spec.name] ||= []
+          libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
+        end
+      end
+
+      def add_gems_from_gemfile(gemfile = nil)
+        require 'bundler'
+        gemfile ||= "Gemfile"
+        if File.exist?("#{gemfile}.lock")
+          Bundler::LockfileParser.new(File.read("#{gemfile}.lock")).specs.each do |spec|
+            libraries[spec.name] ||= []
+            libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
+          end
+        else
+          log.warn "Cannot find #{gemfile}.lock, ignoring --gemfile option"
+        end
+      rescue LoadError
+        log.error "Bundler not available, ignoring --gemfile option"
+      end
+
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
+        opts.separator ''
+        opts.separator 'Example: yard server -m yard .yardoc ruby-core ../ruby/.yardoc'
+        opts.separator 'The above example serves documentation for YARD and Ruby-core'
+        opts.separator ''
+        opts.separator 'If no library/yardoc_file is specified, the server uses'
+        opts.separator 'the name of the current directory and `.yardoc` respectively'
+        opts.separator ''
+        opts.separator "General Options:"
+        opts.on('-m', '--multi-library', 'Serves documentation for multiple libraries') do
+          options[:single_library] = false
+        end
+        opts.on('-c', '--cache', 'Caches all documentation to document root (see --docroot)') do
+          options[:caching] = true
+        end
+        opts.on('-r', '--reload', 'Reparses the library code on each request') do
+          options[:incremental] = true
+        end
+        opts.on('-g', '--gems', 'Serves documentation for installed gems') do
+          add_gems
+        end
+        opts.on('-G', '--gemfile [GEMFILE]', 'Serves documentation for gems from Gemfile') do |gemfile|
+          add_gems_from_gemfile(gemfile)
+        end
+        opts.on('-t', '--template-path PATH',
+                'The template path to look for templates in. (used with -t).') do |path|
+          template_paths << path
+        end
+        opts.separator ''
+        opts.separator "Web Server Options:"
+        opts.on('-d', '--daemon', 'Daemonizes the server process') do
+          server_options[:daemonize] = true
+        end
+        opts.on('-B HOST', '--bind', 'The host address to bind to') do |host|
+          server_options[:Host] = host.to_s
+        end
+        opts.on('-p PORT', '--port', 'Serves documentation on PORT') do |port|
+          server_options[:Port] = port.to_i
+        end
+        opts.on('--docroot DOCROOT', 'Uses DOCROOT as document root') do |docroot|
+          server_options[:DocumentRoot] = File.expand_path(docroot)
+        end
+        opts.on('-a', '--adapter ADAPTER', 'Use the ADAPTER (full Ruby class) for web server') do |adapter|
+          if adapter.casecmp('webrick') == 0
+            self.adapter = YARD::Server::WebrickAdapter
+          elsif adapter.casecmp('rack') == 0
+            self.adapter = YARD::Server::RackAdapter
+          else
+            self.adapter = eval(adapter) # rubocop:disable Lint/Eval
+          end
+        end
+        opts.on('-s', '--server TYPE', 'Use a specific server type eg. thin,mongrel,cgi (Rack specific)') do |type|
+          server_options[:server] = type
+        end
+        opts.on('--fork', 'Use process forking when serving requests') do
+          options[:use_fork] = true
+        end
+        common_options(opts)
+        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+          scripts << file
+        end
+        parse_options(opts, args)
+
+        if args.empty? && libraries.empty?
+          # No args - try to use current dir
+          add_libraries([File.basename(Dir.pwd), nil])
+
+          # Generate doc for first time
+          # This is not necessary but makes for a better first-run experience
+          libver = libraries.empty? ? nil : libraries.values.first.first
+          generate_doc_for_first_time(libver) if libver && !libver.ready?
+        else
+          add_libraries(args)
+          options[:single_library] = false if libraries.size > 1
+        end
+      end
+
+      def generate_doc_for_first_time(libver)
+        log.enter_level(Logger::INFO) do
+          yardoc_file = libver.yardoc_file.sub(%r{^#{Regexp.quote Dir.pwd}[\\/]+}, '')
+          log.info "No yardoc db found in #{yardoc_file}, parsing source before starting server..."
+        end
+        Dir.chdir(libver.source_path) do
+          Yardoc.run('-n')
+        end
+      end
+
+      def extract_db_from_options_file(options_file)
+        args = File.read_binary(options_file).shell_split
+        db = YARD::Registry.yardoc_file
+        opts = OptionParser.new
+        opts.on('-b', '--db FILE') {|file| db = file }
+
+        begin
+          opts.parse!(args)
+        rescue OptionParser::ParseError
+          args.shift if args.first && args.first[0, 1] != '-'
+          retry
+        end
+
+        db
+      end
+    end
+  end
+end