deg-yard 0.8.7.1

data/lib/yard/cli/config.rb

@@ -0,0 +1,136 @@
+module YARD
+  module CLI
+    # CLI command to view or edit configuration options
+    # @since 0.6.2
+    class Config < Command
+      # @return [Symbol, nil] the key to view/edit, if any
+      attr_accessor :key
+
+      # @return [Array, nil] the list of values to set (or single value), if modifying
+      attr_accessor :values
+
+      # @return [Boolean] whether to reset the {#key}
+      attr_accessor :reset
+
+      # @return [Boolean] whether the value being set should be inside a list
+      attr_accessor :as_list
+
+      # @return [Boolean] whether to append values to existing key
+      attr_accessor :append
+
+      def initialize
+        super
+        self.key = nil
+        self.values = []
+        self.reset = false
+        self.append = false
+        self.as_list = false
+      end
+
+      def description
+        'Views or edits current global configuration'
+      end
+
+      def run(*args)
+        optparse(*args)
+        if key
+          if reset || values.size > 0
+            modify_item
+          else
+            view_item
+          end
+        else
+          list_configuration
+        end
+      end
+
+      private
+
+      def modify_item
+        if reset
+          log.debug "Resetting #{key}"
+          YARD::Config.options[key] = YARD::Config::DEFAULT_CONFIG_OPTIONS[key]
+        else
+          log.debug "Setting #{key} to #{values.inspect}"
+          items, current_items = encode_values, YARD::Config.options[key]
+          items = [current_items].flatten + [items].flatten if append
+          YARD::Config.options[key] = items
+        end
+        YARD::Config.save
+      end
+
+      def view_item
+        log.debug "Viewing #{key}"
+        log.puts YARD::Config.options[key].inspect
+      end
+
+      def list_configuration
+        log.debug "Listing configuration"
+        require 'yaml'
+        log.puts YAML.dump(YARD::Config.options).sub(/\A--.*\n/, '').gsub(/\n\n/, "\n")
+      end
+
+      def encode_values
+        if values.size == 1 && !as_list
+          encode_value(values.first)
+        else
+          values.map {|v| encode_value(v) }
+        end
+      end
+
+      def encode_value(value)
+        case value
+        when /^-?\d+/; value.to_i
+        when "true"; true
+        when "false"; false
+        else value
+        end
+      end
+
+      def optparse(*args)
+        list = false
+        self.as_list = false
+        self.append = false
+        opts = OptionParser.new
+        opts.banner = "Usage: yard config [options] [item [value ...]]"
+        opts.separator ""
+        opts.separator "Example: yard config load_plugins true"
+        opts.separator ""
+        opts.separator "Views and sets configuration items. If an item is provided"
+        opts.separator "With no value, the item is viewed. If a value is provided,"
+        opts.separator "the item is modified. Specifying no item is equivalent to --list."
+        opts.separator "If you specify multiple space delimited values, these are"
+        opts.separator "parsed as an array of values."
+        opts.separator ""
+        opts.separator "Note that `true` and `false` are reserved words."
+        opts.separator ""
+        opts.separator "General options:"
+
+        opts.on('-l', '--list', 'List current configuration') do
+          list = true
+        end
+        opts.on('-r', '--reset', 'Resets the specific item to default') do
+          self.reset = true
+        end
+
+        opts.separator ""
+        opts.separator "Modifying keys:"
+
+        opts.on('-a', '--append', 'Appends items to existing key values') do
+          self.append = true
+        end
+        opts.on('--as-list', 'Forces the value(s) to be wrapped in an array') do
+          self.as_list = true
+        end
+
+        common_options(opts)
+        parse_options(opts, args)
+        args = [] if list
+        self.key = args.shift.to_sym if args.size >= 1
+        self.values = args if args.size >= 1
+        args
+      end
+
+    end
+  end
+end

data/lib/yard/cli/diff.rb

@@ -0,0 +1,270 @@
+require 'tmpdir'
+require 'fileutils'
+require 'open-uri'
+
+module YARD
+  module CLI
+    # CLI command to return the objects that were added/removed from 2 versions
+    # of a project (library, gem, working copy).
+    # @since 0.6.0
+    class Diff < Command
+      def initialize
+        super
+        @list_all = false
+        @use_git = false
+        @compact = false
+        @modified = true
+        @verifier = Verifier.new
+        @old_git_commit = nil
+        @old_path = Dir.pwd
+        log.show_backtraces = true
+      end
+
+      def description
+        'Returns the object diff of two gems or .yardoc files'
+      end
+
+      def run(*args)
+        registry = optparse(*args).map do |gemfile|
+          if @use_git
+            load_git_commit(gemfile)
+            all_objects
+          else
+            if load_gem_data(gemfile)
+              log.info "Found #{gemfile}"
+              all_objects
+            else
+              log.error "Cannot find gem #{gemfile}"
+              nil
+            end
+          end
+        end.compact
+
+        return if registry.size != 2
+
+        first_object = nil
+        [   ["Added objects", "A", added_objects(*registry)],
+            ["Modified objects", "M", modified_objects(*registry)],
+            ["Removed objects", "D", removed_objects(*registry)]].each do |name, short, objects|
+          next if short == "M" && @modified == false
+          next if objects.empty?
+          last_object = nil
+          all_objects_notice = false
+          log.puts name + ":" unless @compact
+          objects.sort_by {|o| o.path }.each do |object|
+            if !@list_all && last_object && object.parent == last_object
+              log.print " (...)" unless all_objects_notice
+              all_objects_notice = true
+              next
+            elsif @compact
+              log.puts if first_object
+            else
+              log.puts
+            end
+            all_objects_notice = false
+            log.print "" + (@compact ? "#{short} " : "  ") +
+              object.path + " (#{object.file}:#{object.line})"
+            last_object = object
+            first_object = true
+          end
+          unless @compact
+            log.puts; log.puts
+          end
+        end
+        log.puts if @compact
+      end
+
+      private
+
+      def all_objects
+        return Registry.all if @verifier.expressions.empty?
+        @verifier.run(Registry.all)
+      end
+
+      def added_objects(registry1, registry2)
+        registry2.reject {|o| registry1.find {|o2| o2.path == o.path } }
+      end
+
+      def modified_objects(registry1, registry2)
+        registry1.select do |obj|
+          case obj
+          when CodeObjects::MethodObject
+            registry2.find {|o| obj == o && o.source != obj.source }
+          when CodeObjects::ConstantObject
+            registry2.find {|o| obj == o && o.value != obj.value }
+          end
+        end.compact
+      end
+
+      def removed_objects(registry1, registry2)
+        registry1.reject {|o| registry2.find {|o2| o2.path == o.path } }
+      end
+
+      def load_git_commit(commit)
+        Registry.clear
+        commit_path = 'git_commit' + commit.gsub(/\W/, '_')
+        tmpdir = File.join(Dir.tmpdir, commit_path)
+        log.info "Expanding #{commit} to #{tmpdir}..."
+        Dir.chdir(@old_path)
+        FileUtils.mkdir_p(tmpdir)
+        FileUtils.cp_r('.', tmpdir)
+        Dir.chdir(tmpdir)
+        log.info("git says: " + `git reset --hard #{commit}`.chomp)
+        generate_yardoc(tmpdir)
+      ensure
+        Dir.chdir(@old_path)
+        cleanup(commit_path)
+      end
+
+      def load_gem_data(gemfile)
+        require_rubygems
+        Registry.clear
+
+        # First check for argument as .yardoc file
+        [File.join(gemfile, '.yardoc'), gemfile].each do |yardoc|
+          log.info "Searching for .yardoc db at #{yardoc}"
+          if File.directory?(yardoc)
+            Registry.load_yardoc(yardoc)
+            Registry.load_all
+            return true
+          end
+        end
+
+        # Next check installed RubyGems
+        gemfile_without_ext = gemfile.sub(/\.gem$/, '')
+        log.info "Searching for installed gem #{gemfile_without_ext}"
+        Gem.source_index.find_name('').find do |spec|
+          if spec.full_name == gemfile_without_ext
+            if yardoc = Registry.yardoc_file_for_gem(spec.name, "= #{spec.version}")
+              Registry.load_yardoc(yardoc)
+              Registry.load_all
+            else
+              log.enter_level(Logger::ERROR) do
+                olddir = Dir.pwd
+                Gems.run(spec.name, spec.version.to_s)
+                Dir.chdir(olddir)
+              end
+            end
+            return true
+          end
+        end
+
+        # Look for local .gem file
+        gemfile += '.gem' unless gemfile =~ /\.gem$/
+        log.info "Searching for local gem file #{gemfile}"
+        if File.exist?(gemfile)
+          File.open(gemfile, 'rb') do |io|
+            expand_and_parse(gemfile, io)
+          end
+          return true
+        end
+
+        # Remote gemfile from rubygems.org
+        url = "http://rubygems.org/downloads/#{gemfile}"
+        log.info "Searching for remote gem file #{url}"
+        begin
+          open(url) {|io| expand_and_parse(gemfile, io) }
+          return true
+        rescue OpenURI::HTTPError
+        end
+        false
+      end
+
+      def expand_and_parse(gemfile, io)
+        dir = expand_gem(gemfile, io)
+        generate_yardoc(dir)
+        cleanup(gemfile)
+      end
+
+      def generate_yardoc(dir)
+        olddir = Dir.pwd
+        Dir.chdir(dir) do
+          log.enter_level(Logger::ERROR) { Yardoc.run('-n', '--no-save') }
+        end
+      end
+
+      def expand_gem(gemfile, io)
+        tmpdir = File.join(Dir.tmpdir, gemfile)
+        FileUtils.mkdir_p(tmpdir)
+        log.info "Expanding #{gemfile} to #{tmpdir}..."
+
+        if Gem::VERSION >= '2.0.0'
+          require 'rubygems/package/tar_reader'
+          reader = Gem::Package::TarReader.new(io)
+          reader.each do |pkg|
+            if pkg.full_name == 'data.tar.gz'
+              Zlib::GzipReader.wrap(pkg) do |gzio|
+                tar = Gem::Package::TarReader.new(gzio)
+                tar.each do |entry|
+                  mode = entry.header.mode
+                  file = File.join(tmpdir, entry.full_name)
+                  FileUtils.mkdir_p(File.dirname(file))
+                  File.open(file, 'wb') do |out|
+                    out.write(entry.read)
+                    out.fsync rescue nil
+                  end
+                end
+              end
+              break
+            end
+          end
+        else
+          Gem::Package.open(io) do |pkg|
+            pkg.each do |entry|
+              pkg.extract_entry(tmpdir, entry)
+            end
+          end
+        end
+
+        tmpdir
+      end
+
+      def require_rubygems
+        require 'rubygems'
+        require 'rubygems/package'
+      rescue LoadError => e
+        log.error "Missing RubyGems, cannot run this command."
+        raise(e)
+      end
+
+      def cleanup(gemfile)
+        dir = File.join(Dir.tmpdir, gemfile)
+        log.info "Cleaning up #{dir}..."
+        FileUtils.rm_rf(dir)
+      end
+
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = "Usage: yard diff [options] oldgem newgem"
+        opts.separator ""
+        opts.separator "Example: yard diff yard-0.5.6 yard-0.5.8"
+        opts.separator ""
+        opts.separator "If the files don't exist locally, they will be grabbed using the `gem fetch`"
+        opts.separator "command. If the gem is a .yardoc directory, it will be used. Finally, if the"
+        opts.separator "gem name matches an installed gem (full name-version syntax), that gem will be used."
+
+        opts.on('-a', '--all', 'List all objects, even if they are inside added/removed module/class') do
+          @list_all = true
+        end
+        opts.on('--compact', 'Show compact results') { @compact = true }
+        opts.on('--git', 'Compare versions from two git commit/branches') do
+          @use_git = true
+        end
+        opts.on('--query QUERY', 'Only diff filtered objects') do |query|
+          @verifier.add_expressions(query)
+        end
+        opts.on('--no-modified', 'Ignore modified objects') do
+          @modified = false
+        end
+        common_options(opts)
+        parse_options(opts, args)
+        unless args.size == 2
+          log.puts opts.banner
+          exit(0)
+        end
+
+        args
+      end
+    end
+  end
+end

data/lib/yard/cli/display.rb

@@ -0,0 +1,68 @@
+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? {|o| o.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/lib/yard/cli/gems.rb

@@ -0,0 +1,83 @@
+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
+      # @param [Array] 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)
+            log.info "Building yardoc index for gem: #{spec.full_name}"
+            Yardoc.run('--no-stats', '-n', '-b', yfile)
+          end
+        end
+      end
+
+      def add_gems(gems)
+        0.step(gems.size - 1, 2) do |index|
+          gem, ver_require = gems[index], gems[index + 1] || ">= 0"
+          specs = Gem.source_index.find_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 += Gem.source_index.find_name('') if @gems.empty?
+        end
+      end
+    end
+  end
+end

data/lib/yard/cli/graph.rb

@@ -0,0 +1,126 @@
+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)
+        if args.first
+          @objects = args.map {|o| Registry.at(o) }.compact
+        else
+          @objects = [Registry.root]
+        end
+      end
+    end
+  end
+end

data/lib/yard/cli/help.rb

@@ -0,0 +1,18 @@
+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)
+        if args.first && cmd = CommandParser.commands[args.first.to_sym]
+          cmd.run('--help')
+        else
+          log.puts "Command #{args.first} not found." if args.first
+          CommandParser.run('--help')
+        end
+      end
+    end
+  end
+end