rubikon 0.2.1 → 0.3.0

data/README.md

@@ -3,10 +3,14 @@ Rubikon
 
 Rubikon is a simple to use, yet powerful Ruby framework for building
 console-based applications.
+Rubikon aims to provide an easy to write and easy to read domain-specific
+language (DSL) to speed up development of command-line applications. With
+Rubikon it's a breeze to implement applications with only few options as well
+as more complex programs like RubyGems, Homebrew or even Git.
 
 ## Installation
 
-You can install Rubikon using RubyGem. This is the easiest way of installing
+You can install Rubikon using RubyGems. This is the easiest way of installing
 and recommended for most users.
 
     $ gem install rubikon
@@ -45,27 +49,39 @@ This is done using `default`:
 
 If you run this application it will just print `Hello World!`.
 
-You can also add command-line options to your appication using `action`:
+You can also add command-line options to your appication using `command`:
 
     class MyApplication < Rubikon::Application
 
-      action 'hello' do
+      command :hello do
         puts 'Hello World!'
       end
 
     end
 
 This way your application would do nothing when called without options, but it
-would print `Hello World!` when called using `ruby myapp.rb --hello`.
-Please note that Rubikon will add dashes to options by default. If you don't
-like this behaviour and want options like RubyGem's `install` or `update` just
-use the following inside your application class:
+would print `Hello World!` when called using `ruby myapp.rb hello`. A command
+is code that is executed when the application is called with the command's name
+as the first argument - just like RubyGem's `install` or Git's `commit`.
+
+Another part of Rubikon's DSL are flags and options. Both are parameter types
+that change the behaviour of the application. While a flag is a parameter
+without arguments, an option may take one or more additional arguments. Typical
+examples for flags are `--debug` or `--verbose` (or short `-d` and `-v`).
+RubyGem's `--version` is an example for an option that requires additional
+arguments.
+Flags and options are easily added to your application's commands using
+Rubikon's DSL:
+
+    flag :more
+    option :name, 2
+    command :hello do
+      ...
+    end
 
-    set :dashed_options, false
 
 Please see the `samples` directory for more in detail sample applications.
 
-
 **Warning**:
 
 Rubikon is still in an early development stage. If you want to use it be aware
@@ -76,29 +92,32 @@ Contribute section if you want to help making Rubikon better.
 
 * A simple to use DSL
 * Automatic checks for option arguments
-* User defined type safety of option arguments
-* Built-in methods to capture user input and display throbbers
+* Built-in methods to capture user input
+* Built-in methods to display progress bars and throbbers
 
 ## Future plans
 
+* User defined type safety of option arguments
 * Automatic generation of help screens
 * Improved error handling
 * Built-in support for configuration files
-* Built-in support for colored output and progress bars
+* Built-in support for colored output
 
 ## Requirements
 
 * Linux, MacOS X or Windows
-* Ruby 1.8.6 or newer
+* Ruby 1.8.6 or newer (see the [compatibility page][4] in Rubikon's wiki)
 
 ## Contribute
 
+Rubikon is a open-source project. Therefore you are free to help improving it.
 There are several ways of contributing to Rubikon's development:
 
-* Build apps using it and spread the word.<br />
+* Build apps using it and spread the word.
 * Report problems and request features using the [issue tracker][2].
 * Write patches yourself to fix bugs and implement new functionality.
-* Create a Rubikon fork on [GitHub][1] and start hacking.
+* Create a Rubikon fork on [GitHub][1] and start hacking. Extra points for
+  using GitHubs pull requests and feature branches.
 
 ## About the name
 
@@ -107,7 +126,8 @@ relevance in ancient Rome when Julius Caesar crossed that river with his army
 and thereby declared war to the Roman senate. The phrase "to cross the Rubicon"
 originates from this event.
 
-You may also see Rubikon as a morphed composition of *"Ruby"* and *"console"*.
+You may also see Rubikon as a portmanteau word consisting of *"Ruby"* and
+*"console"*.
 
 ## License
 
@@ -121,9 +141,12 @@ file.
 
 ## See Also
 
+* [Rubikon's homepage][3]
 * [API documentation](http://www.rdoc.info/projects/koraktor/rubikon)
 * [GitHub project page][1]
 * [GitHub issue tracker][2]
 
  [1]: http://github.com/koraktor/rubikon
  [2]: http://github.com/koraktor/rubikon/issues
+ [3]: http://koraktor.github.com/rubikon
+ [4]: http://github.com/koraktor/rubikon/wiki/Compatibility

data/Rakefile

@@ -1,9 +1,8 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
-require 'rake/rdoctask'
 require 'rake/testtask'
 
 src_files = Dir.glob(File.join('lib', '**', '*.rb'))
@@ -20,31 +19,45 @@ end
 
 begin
   require 'jeweler'
+
+  gemspec = Gem::Specification.new do |gem|
+    line = File.read('lib/rubikon.rb')[/^\s*VERSION\s*=\s*.*/]
+    gem.version = line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+  end
+
   # Gem specification
-  Jeweler::Tasks.new do |gem|
+  Jeweler::Tasks.new(gemspec) do |gem|
     gem.authors = ['Sebastian Staudt']
     gem.email = 'koraktor@gmail.com'
     gem.description = 'A simple to use, yet powerful Ruby framework for building console-based applications.'
     gem.date = Time.now
+    gem.files = %w(README.md Rakefile LICENSE) + src_files + test_files
+    gem.has_rdoc = false
     gem.homepage = 'http://koraktor.github.com/rubikon'
     gem.name = gem.rubyforge_project = 'rubikon'
     gem.summary = 'Rubikon - A Ruby console app framework'
 
-    gem.files = %w(README.md Rakefile LICENSE VERSION.yml) + src_files + test_files
-    gem.rdoc_options = ['--all', '--inline-source', '--line-numbers', '--charset=utf-8', '--webcvs=http://github.com/koraktor/rubikon/blob/master/%s']
+    gem.add_development_dependency('jeweler')
+    gem.add_development_dependency('yard')
   end
 rescue LoadError
-  puts "You need Jeweler to build the gem. Install it using `gem install jeweler`."
+  puts 'You need Jeweler to build the gem. Install it using `gem install jeweler`.'
 end
 
-# Create a rake task +:rdoc+ to build the documentation
-desc 'Building docs'
-Rake::RDocTask.new do |rdoc|
-  rdoc.title = 'Rubikon - API documentation'
-  rdoc.rdoc_files.include ['lib/**/*.rb', 'LICENSE', 'README.md']
-  rdoc.main = 'README.md'
-  rdoc.rdoc_dir = 'doc'
-  rdoc.options = ['--all', '--inline-source', '--line-numbers', '--charset=utf-8', '--webcvs=http://github.com/koraktor/rubikon/blob/master/%s']
+begin
+  require 'yard'
+
+  # Create a rake task +:doc+ to build the documentation using YARD
+  YARD::Rake::YardocTask.new do |yardoc|
+    yardoc.name    = 'doc'
+    yardoc.files   = ['lib/**/*.rb', 'LICENSE', 'README.md']
+    yardoc.options = ['--private', '--title', 'Rubikon — API Documentation']
+  end
+rescue LoadError
+  desc 'Generate YARD Documentation (not available)'
+  task :doc do
+    puts 'You need YARD to build the documentation. Install it using `gem install yard`.'
+  end
 end
 
 # Task for cleaning documentation and package directories

data/lib/core_ext/string.rb

@@ -0,0 +1,16 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2010, Sebastian Staudt
+
+unless String.method_defined?(:start_with?)
+
+  class String
+
+    def start_with?(start)
+      !/^#{start}/.match(self).nil?
+    end
+
+  end
+
+end

data/lib/rubikon/application/base.rb

@@ -1,31 +1,31 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 require 'singleton'
 require 'yaml'
 
-require 'rubikon/action'
 require 'rubikon/application/class_methods'
+require 'rubikon/application/dsl_methods'
 require 'rubikon/application/instance_methods'
-require 'rubikon/exceptions'
 
 module Rubikon
 
-  version = YAML.load_file(File.join(File.dirname(__FILE__), '..', '..', '..', 'VERSION.yml'))
-  VERSION = "#{version[:major]}.#{version[:minor]}.#{version[:patch]}"
-
   module Application
 
-    # The main class of Rubikon. Let your own application class inherit from this
-    # one.
+    # The main class of Rubikon. Let your own application class inherit from
+    # this one.
+    #
+    # @author Sebastian Staudt
+    # @since 0.2.0
     class Base
 
       class << self
         include Rubikon::Application::ClassMethods
       end
 
+      include Rubikon::Application::DSLMethods
       include Rubikon::Application::InstanceMethods
       include Singleton
 

data/lib/rubikon/application/class_methods.rb

@@ -1,27 +1,34 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 module Rubikon
 
   module Application
 
+    # This module contains all class methods of +Application::Base+ and its
+    # subclasses.
+    #
+    # @author Sebastian Staudt
+    # @see Application::Base
+    # @since 0.2.0
     module ClassMethods
 
       private
 
-      # Returns whether this application should be ran automatically
+      # Returns whether this application should be run automatically
       def autorun?
         instance.instance_variable_get(:@settings)[:autorun] || false
       end
 
       # Enables autorun functionality using <tt>Kernel#at_exit</tt>
       #
-      # +subclass+:: The subclass inheriting from Application. This is the user's
-      #              application.
+      # <em>This is called automatically when subclassing
+      # Application::Base.</em>
       #
-      # <em>This is called automatically when subclassing Application.</em>
+      # @param [Class] subclass The subclass inheriting from Application::Base.
+      #        This is the user's application.
       def inherited(subclass)
         super
         Singleton.__init__(subclass)
@@ -31,35 +38,16 @@ module Rubikon
       # This is used for convinience. Method calls on the class itself are
       # relayed to the singleton instance.
       #
-      # +method_name+:: The name of the method being called
-      # +args+::        Any arguments that are given to the method
-      # +block+::       A block that may be given to the method
+      # <em>This is called automatically when calling methods on the
+      # application class.</em>
       #
-      # <em>This is called automatically when calling methods on the class.</em>
+      # @param [Symbol] method_name The name of the method being called
+      # @param [Array] args Any arguments that are given to the method
+      # @param [Proc] block A block that may be given to the method
       def method_missing(method_name, *args, &block)
         instance.send(method_name, *args, &block)
       end
 
-      # Relay putc to the instance method
-      #
-      # This is used to hide <tt>Kernel#putc</tt> so that the Application's
-      # output IO object is used for printing text
-      #
-      # +text+:: The text to write into the output stream
-      def putc(text)
-        instance.putc text
-      end
-
-      # Relay puts to the instance method
-      #
-      # This is used to hide <tt>Kernel#puts</tt> so that the Application's
-      # output IO object is used for printing text
-      #
-      # +text+:: The text to write into the output stream
-      def puts(text)
-        instance.puts text
-      end
-
     end
 
   end