yard-thunder 0.1.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+v0.1.0
++ first version

data/README.md

@@ -0,0 +1,32 @@
+[Yard-Thunder](http://stevenkaras.github.com/yard-thunder)
+=======
+YARD plugin for Thunder integration.
+
+Code is based upon yard-thor by Loren Segal (who also maintains YARD itself). Way to go Loren!
+
+Usage
+-----
+
+    gem install yard-thunder
+
+    yard --plugin thunder COMMANDS
+
+Goals
+-----
+Provide integration for Thunder CLI programs with YARD
+
+Development Phases
+
+1. provide a section called "CLI usage" for each command (method)
+2. integrate options into the generated docs for a command
+3. handle subcommands (along with all the other stuff)
+4. add a CLI usage section/file in the YARD output (manpage style)
+5. activate only if Thunder is included (or has been included in a parent class)
+
+Development
+-----------
+If you'd like to contribute, fork, commit, and request a pull. I'll get around to it. No special dependencies, or anything fancy
+
+License
+-------
+MIT License

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/test_*.rb']
+  t.test_files = FileList['spec/*_spec.rb']
+  t.test_files = FileList['spec/spec_*.rb']
+  t.libs << 'spec'
+  t.libs << 'test'
+end
+
+gemspec = eval(File.read(Dir["*.gemspec"].first))
+
+desc "Run tests"
+task :default => :test
+
+desc "Validate the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+desc "Build the gem locally"
+task :build => :gemspec do
+  system "gem build #{gemspec.name}.gemspec"
+end
+
+desc "Install the gem locally"
+task :install => :build do
+  system "gem uninstall -a #{gemspec.name}"
+  system "gem install #{gemspec.name}-#{gemspec.version}.gem"
+end
+
+desc "check syntax"
+task :syntax do
+  Dir["**/*.rb"].each do |file|
+    print "#{file}: "
+    system("ruby -c #{file}")
+  end
+end
+
+desc "delete all temporary files"
+task :clean
+
+desc "delete all temporary files and build artifacts"
+task :clobber => :clean do
+  FileUtils.rm_rf Dir["#{gemspec.name}-*.gem"]
+end

data/lib/sample.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path("../lib/", __FILE__)
+require 'thunder'
+require 'thunder/options/trollop'
+
+class Bar
+  include Thunder
+
+  desc "doit", "do something with the Bar class"
+  option :verb, type: Boolean, desc: "verbosity"
+  def doit(options={})
+    p options
+  end
+end
+
+class Foo
+  include Thunder
+
+  #options_processor TrollopAdapter
+
+  desc "bar A", "desc"
+  def bar(a)
+    p a
+  end
+
+  desc "baz [options]"
+  option :flag, type: Boolean, desc: "run with a flag"
+  option :some, type: String, desc: "something", default: "some default value"
+  def baz(options = {})
+    p options
+  end
+
+  desc "quux COMMAND...", "send COMMAND to Bar"
+  subcommand "quux", ::Bar.new
+
+end
+
+
+Foo.new.start

data/lib/yard-thunder.rb

@@ -0,0 +1,45 @@
+$: << File.expand_path("..", __FILE__)
+
+module YardThunder
+
+  require 'yard-thunder/description'
+  require 'yard-thunder/options'
+  require 'yard-thunder/subcommand'
+  require 'yard-thunder/default_command'
+
+  module ThunderMethodHandlerMixin
+    def register(*objs)
+      @registered_object = objs.first
+      super(*objs)
+    end
+  end
+end
+
+class YARD::Handlers::Processor
+  attr_accessor :extra_state
+end
+
+class YARD::Handlers::Ruby::MethodHandler 
+  include YardThunder::ThunderMethodHandlerMixin
+  include YardThunder::MethodHandlerDescriptionMixin
+  include YardThunder::MethodHandlerOptionMixin
+end
+
+# class YARD::Handlers::Ruby::Legacy::MethodHandler 
+#   include ::YardThunder::ThunderMethodHandlerMixin
+#   include ::YardThunder::MethodHandlerDescriptionMixin
+#   include YardThunder::MethodHandlerOptionMixin
+# end
+
+# module YARD::Templates::Helpers::HtmlHelper
+#   def signature_for_thunder_command(meth, link = true, *args)
+#     if meth.has_tag?(:thunder_command)
+#       sig = link ? link_object(meth, meth.signature) : meth.signature
+#       "$ " + sig 
+#     else
+#       old_signature(meth, link, *args)
+#     end
+#   end
+#   alias old_signature signature
+#   alias signature signature_for_thunder_command
+# end

data/lib/yard-thunder/default_command.rb

@@ -0,0 +1,31 @@
+module YardThunder
+  class DefaultCommandHandler < YARD::Handlers::Ruby::Base
+    handles method_call(:default_command)
+
+    process do
+      # statement.parameters(false).map do |param|
+      #   param.jump(:string_content).source
+      # end
+      # name = statement.parameters.first.jump(:tstring_content, :ident).source
+      # object = YARD::CodeObjects::MethodObject.new(namespace, name)
+      # register(object)
+      # parse_block(statement.last.last, :owner => object)
+
+      # # modify the object 
+      # object.dynamic = true 
+
+      # # add custom metadata to the object
+      # object['custom_field'] = 'Generated by Methodify'
+    end
+  end
+
+  # class LegacyDefaultCommandHandler < YARD::Handlers::Ruby::Legacy::Base
+  #   namespace_only
+  #   handles /\Adefault_command(\s|\()/
+    
+  #   process do
+  #     #TODO: write this
+  #   end
+  # end
+  
+end

data/lib/yard-thunder/description.rb

@@ -0,0 +1,46 @@
+module YardThunder
+  class DescriptionHandler < YARD::Handlers::Ruby::Base
+    handles method_call(:desc)
+
+    process do
+      parser.extra_state.thunder_desc = statement.parameters(false).map do |param|
+        param.jump(:string_content).source
+      end
+    end
+  end
+
+  # class LegacyDescriptionHandler < YARD::Handlers::Ruby::Legacy::Base
+  #   namespace_only
+  #   handles /\Adesc(\s|\()/
+    
+  #   process do
+  #     parser.extra_state ||= {}
+  #     parser.extra_state[:thunder_desc] = tokval_list(statement.tokens[1..-1], :attr)
+  #   end
+  # end
+
+  module MethodHandlerDescriptionMixin
+    def process
+      super
+      return unless parser.extra_state
+      #TODO: create a second code object for the thunder command itself
+
+      # handle a command description for this method
+      if parser.extra_state.thunder_desc
+        usage, desc = *parser.extra_state.thunder_desc
+        # drop in the description, if there is no "real" docstring
+        tags = @registered_object.tags
+        @registered_object.docstring = desc
+        tags.each { |tag| @registered_object.docstring.add_tag(tag) }
+        @registered_object.signature = usage
+
+        # add a second code object to describe the command line interface for this command
+        @registered_object.namespace.groups << ["Thunder Commands"] unless @registered_object.namespace.groups.include? "Thunder Commands"
+        # @registered_object.group = "Thunder Commands"
+        # @registered_object.docstring.add_tag YARD::Tags::Tag.new(:thunder_command, '')
+        parser.extra_state.thunder_desc = nil
+      end
+    end
+  end
+
+end

data/lib/yard-thunder/options.rb

@@ -0,0 +1,61 @@
+module YardThunder
+  class OptionHandler < YARD::Handlers::Ruby::Base
+    handles method_call(:option)
+
+    process do
+      parser.extra_state.thunder_options ||= []
+      parser.extra_state.thunder_options << {}.tap do |option|
+        params = statement.parameters(false)
+        option[:name] = params[0].jump(:ident, :string_content).source
+        params[1].each do |param|
+          key = param.first.jump(:label, :ident)[0].to_sym
+          value = param[1][0].jump(:const, :kw, :string_content).source
+          option[key] = value
+        end
+      end
+    end
+  end
+
+  # class LegacyOptionHandler < YARD::Handlers::Ruby::Legacy::Base
+  #   handles /\Aoption(\s|\()/
+    
+  #   process do
+  #     parser.extra_state ||= {}
+  #     parser.extra_state[:thunder_options] ||= []
+  #     parser.extra_state[:thunder_options] << tokval_list(statement.tokens[1..-1], :attr)
+  #   end
+  # end
+
+  module MethodHandlerOptionMixin
+    def process
+      super
+      return unless parser.extra_state
+      # handle any options for this command
+      if parser.extra_state.thunder_options
+        # add the options parameter to the method if it's not already there
+        unless @registered_object.tags(:param).find {|x| x.name == "options"}
+          option_param = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", "options")
+          @registered_object.docstring.add_tag(option_param)
+        end
+
+        # trick the parser to parse the option as a YARDoc tag
+        parser.extra_state.thunder_options.each do |option|
+          name = option[:name]
+          description = option[:desc] || ""
+          if option[:default]
+            unless description.lstrip.start_with? /\(.+\)/
+              description = "(#{option[:default]}) #{description}"
+            end
+          end
+          type = option[:type] || "String"
+
+          text = "options #{name} [#{type}] #{description}"
+          option_tag = YARD::Tags::Library.default_factory.parse_tag_with_options(:option, text)
+          @registered_object.docstring.add_tag(option_tag)
+        end
+        parser.extra_state.thunder_options = nil
+      end
+    end
+  end
+
+end

data/lib/yard-thunder/subcommand.rb

@@ -0,0 +1,31 @@
+module YardThunder
+  class SubcommandHandler < YARD::Handlers::Ruby::Base
+    handles method_call(:subcommand)
+
+    process do
+      # statement.parameters(false).map do |param|
+      #   param.jump(:string_content).source
+      # end
+      # name = statement.parameters.first.jump(:tstring_content, :ident).source
+      # object = YARD::CodeObjects::MethodObject.new(namespace, name)
+      # register(object)
+      # parse_block(statement.last.last, :owner => object)
+
+      # # modify the object 
+      # object.dynamic = true 
+
+      # # add custom metadata to the object
+      # object['custom_field'] = 'Generated by Methodify'
+    end
+  end
+
+  # class LegacySubcommandHandler < YARD::Handlers::Ruby::Legacy::Base
+  #   namespace_only
+  #   handles /\Asubcommand(\s|\()/
+    
+  #   process do
+  #     #TODO: write this
+  #   end
+  # end
+  
+end

data/lib/yard-thunder/version.rb

@@ -0,0 +1,3 @@
+module YardThunder
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: yard-thunder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Steven Karas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-20 00:00:00.000000000 Z
+dependencies: []
+description: Integrates Thunder command line interfaces into YARD
+email: steven.karas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sample.rb
+- lib/yard-thunder/default_command.rb
+- lib/yard-thunder/description.rb
+- lib/yard-thunder/options.rb
+- lib/yard-thunder/subcommand.rb
+- lib/yard-thunder/version.rb
+- lib/yard-thunder.rb
+- CHANGELOG
+- Rakefile
+- README.md
+homepage: http://stevenkaras.github.com/yard-thunder
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: YARD integration for Thunder
+test_files: []
+has_rdoc: