rubyshelltools 0.0.1

data/README.md

@@ -0,0 +1,101 @@
+Ruby Shell Tools
+================
+
+RST Version 0.0.1 is an experimental Ruby2-gem by Andreas Altendorfer <andreas@altendorfer.at>
+
+Install from rubygems.org
+-------------------------
+
+    gem install rubyshelltools
+
+
+Clone from Github
+-----------------
+
+You can clone the project from **[Github](https://github.com/iboard/rst)**
+
+    git clone git://github.com/iboard/rst.git
+
+### First steps ...
+
+After downloading the project you can do
+
+    cd rst
+    bundle       # install required Gems
+    rake         # Run all specs
+    rake build   # build the gem
+    rake install # build and install gem
+
+
+Usage
+-----
+
+see file EXAMPLES.md:
+
+ * [At Github](https://github.com/iboard/rst/blob/master/assets/docs/examples.md#examples)
+ * [loacal copy](./file.examples.html)
+ 
+or run
+
+    bin/rst --examples
+
+if you have done `rake install` you don't have to use `bin/rst` in 
+the project-directory but you can use `rst ...` directly from the shell.
+
+Documentation
+-------------
+
+run `yard; open doc/index.html` to build the rdocs and open
+it in your browser.
+
+The documentation can be found also at
+[dav.iboard.cc](http://dav.iboard.cc/container/rst-doc)
+
+TDD
+---
+
+And as always we are **green**
+
+You can find the current output of [simplecov][] at [dav.iboard.cc](http://dav.iboard.cc/container/rst-coverage)
+
+
+> $ rake
+>
+> Finished in _a few_ seconds
+>
+> _n_ examples, 0 failures
+>
+> Coverage report generated for RSpec to rst/coverage. _n_ / _n+-0_ LOC (**100.0%**) covered.
+>
+> $ yard
+>
+> Files:          _n_
+>
+> Modules:         _n_ (    0 undocumented)
+>
+> Classes:         _n_ (    0 undocumented)
+>
+> Constants:      _n_ (    0 undocumented)
+>
+> Methods:        _n_ (    0 undocumented)
+>
+> **100.00% documented**
+
+
+License
+=======
+
+This is free software
+---------------------
+
+Use it without restrications and on your own risk.
+Leaving the copyright is appreciated, though.
+
+
+Copyright
+---------
+
+(c) 2013 by Andreas Altendorfer
+
+
+[simplecov]: http://github.com/colszowka/simplecov 

data/assets/docs/examples.md

@@ -0,0 +1,92 @@
+EXAMPLES
+========
+
+rst --help
+----------
+ 
+Print out available options and commands
+  
+    $ rst --help
+    Usage: rst [COMMAND [COMMAND ....]] [options] [FILES..]
+
+    Options:
+        -v, --[no-]verbose               Run verbosely
+            --examples                   Show some usage examples
+        -h, --help                       Print help
+        -f, --from DATE                  Set from-date
+        -t, --to DATE                    Set to-date
+        -n, --name NAME                  Use this name for the command
+        -e, --new-event DATE,STRING      Add an event
+            --list-calendars             List available calendars
+            --delete-calendar CALENDARNAME
+                                         Delete an calendar and all it's entries!
+            --[no-]empty                 Show empty entries
+    Commands:
+        nil .......... no command. Interpret options only (useful in combination with -v)
+        ls ........... list directory and files
+        cal[endar] ... print a calendar --from --to
+
+        use --example for a more detailed list of commands.
+
+rst ls *
+--------
+
+List directory and files
+
+    $ rst ls *
+    Gemfile	Gemfile.lock	README.md	Rakefile	assets	bin	lib	
+    rst-0.0.0.gem	rst.gemspec	rst.rb	specs
+
+
+rst [nil]  -v SOME FILES HERE
+-----------------------------
+
+show the arguments and options parsed from command-line
+
+    $ rst -v SOME FILES HERE
+    Binary : /Users/aa/.rvm/gems/ruby-head@ruby2/bin/rst
+    Command: 
+    Options: [:verbose, true]
+    Files:   SOME, FILES, HERE
+    
+rst calendar
+------------
+
+RST supports a (very) simple calendar-function. You can store (all-day)events for a given date.
+The calendar can be stored persistently in a PStore file. The default
+location of the file is within the GEM-path/data/development. You can
+overwrite this by defining env-vars for RST_DATA and RST_ENV
+    
+    $ export RST_DATA=$HOME/.rst/data
+    $ export RST_ENV=production
+    $ rst cal --new-event='1964-08-31,Birthday Andreas Altendorfer'
+    $ rst cal -e 'today,Win the jackpot'  # e is an abbreviation for --new-event
+    $ rst cal -f 1964/1                   # f is an abbreviation for --from
+    Mon, Aug 31 1964: Birthday Andreas Altendorfer
+    Fri, Mar 15 2013: Win the jackpot
+    $ find $HOME/.rst
+    /Users/you/.rst
+    /Users/you/.rst/data
+    /Users/you/.rst/data/production
+    /Users/you/.rst/data/production/CALENDAR_FILE
+    
+    $ rst --list-calendars
+    birthdays           : 5 entries
+    work                : 2 entries
+    
+
+The full set of parameters is
+
+    $ rst calendar --from='1964-01-01' --to='today' --empty
+    Wed, Jan 01 1964: 
+    Thu, Jan 02 1964: 
+    Fri, Jan 03 1964: 
+    Sat, Jan 04 1964: 
+    #.... some other empty lines
+    Mon, Aug 31 1964: Birthday Andreas Altendorfer
+    # .... some thousand other empty lines
+    Fri, Mar 15 2013: Win the jackpot
+
+* --empty ...... show empty lines
+* --no-empty ... show no empty lines (default)
+

data/bin/rst

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+
+require File.expand_path('../../rst', __FILE__)
+require_relative '../lib/rst'
+require_relative '../lib/load'
+include RST
+
+
+# Run rst from commandline
+puts RstCommand.new(ARGV).run

data/lib/core_extensions/numeric.rb

@@ -0,0 +1,75 @@
+# Monkey-patch the numeric class to support n.years,days,... as Rails do
+class Numeric
+
+  #:nodoc:
+  SECOND  = 1
+  #:nodoc:
+  SECONDS = SECOND
+  #:nodoc:
+  MINUTES = 60
+  #:nodoc:
+  MINUTE  = MINUTES
+  #:nodoc:
+  HOURS   = MINUTES * 60
+  #:nodoc:
+  HOUR    = HOURS
+  #:nodoc:
+  DAYS    = HOUR * 24
+  #:nodoc:
+  DAY     = DAYS
+  #:nodoc:
+  WEEKS   = DAY * 7
+  #:nodoc:
+  WEEK    = WEEKS
+  #:nodoc:
+  MONTHS  = DAY * 30.5
+  #:nodoc:
+  MONTH   = MONTHS
+  #:nodoc:
+  YEAR    = DAY * 365.25
+  #:nodoc:
+  YEARS   = YEAR
+
+  #:nodoc:
+  def years
+    (self * YEAR).to_f
+  end
+  alias :year :years
+
+  #:nodoc:
+  def months
+    (self * MONTH).to_f
+  end
+  alias :month :months
+
+  #:nodoc:
+  def weeks
+    (self * WEEK).to_f
+  end
+  alias :week :weeks
+
+  #:nodoc:
+  def days
+    (self * DAYS).to_f
+  end
+  alias :day :days
+
+  #:nodoc:
+  def hours
+    (self * HOUR).to_f
+  end
+  alias :hour :hours
+
+  #:nodoc:
+  def minutes
+    (self * MINUTE).to_f
+  end
+  alias :minute :minutes
+
+  #:nodoc:
+  def seconds
+    (self * SECONDS).to_f
+  end
+  alias :second :seconds
+
+end

data/lib/errors/store_errors.rb

@@ -0,0 +1,6 @@
+module RST
+
+  # Exception thrown when an abstract method is called
+  class AbstractMethodCallError < NotImplementedError; end
+
+end

data/lib/load.rb

@@ -0,0 +1,37 @@
+unless defined? LIB_LOADED
+
+  # prevent from double loading
+  LIB_LOADED = true
+
+  # Used with strftime(DEFAULT_DATE_FORMAT) when printing dates
+  DEFAULT_DATE_FORMAT = '%a, %b %d %Y'
+
+  # Filename for the calendar-store
+  CALENDAR_FILE = 'calendars.data'
+
+  require File.expand_path('../../rst',__FILE__)
+
+  # Load all necessary files
+  $LOAD_PATH.unshift(File.expand_path('..',__FILE__))
+
+  $LOAD_PATH.unshift(File.expand_path('../core_extensions',__FILE__))
+  require 'numeric'
+
+  $LOAD_PATH.unshift(File.expand_path('../errors',__FILE__))
+  require 'store_errors'
+
+  $LOAD_PATH.unshift(File.expand_path('../modules/calendar',__FILE__))
+  require 'calendar'
+  require 'eventable'
+  require 'calendar_event'
+
+  $LOAD_PATH.unshift(File.expand_path('../modules/persistent',__FILE__))
+  require 'persistent'
+  require 'store'
+  require 'memory_store'
+  require 'disk_store'
+
+  
+  include RST
+end
+

data/lib/modules/calendar/calendar.rb

@@ -0,0 +1,155 @@
+require 'date'
+require 'modules/persistent/persistent'
+
+module RST
+
+  # Calendar-module provides the Calendar-class which is supposed to hold
+  # 'Eventable'-objects. Where Eventable is a module you can include to any class.
+  # A Calendar has a start- and ending-date, and a name. The name is used
+  # to store the calendar in a store using this name.
+  #
+  # @example
+  #
+  #     class Person
+  #       include Eventable
+  #
+  #       def initialize name, dob
+  #         @name = name
+  #         schedule! dob
+  #       end
+  #
+  #       # override abstract method to format the output
+  #       def event_headline
+  #         '#{name}\'s Birthday'
+  #       end
+  #     end
+  #
+  #     birthdays = Calendar.new('birthdays')
+  #     birthdays << Person.new('Andi',   '31. Aug. 1964')
+  #     birthdays << Person.new('Heidi',  '28. Aug. 1969')
+  #     birthdays << Person.new('Julian', '17. Feb. 1995')
+  #     birthdays << Person.new('Tina',   '22. May. 1997')
+  #
+  #     puts birthdays.list_days('31.8.1963','today') 
+  #     # => Mon, Aug 31 1964: Andi's Birthday
+  #     # => Thu, Aug 28 1969: Heidi's Birthday
+  #     # => Fri, Feb 17 1995: Julian's Birthday
+  #     # => Thu, May 22 1997: Tina's Birthday
+  #
+  module Calendar
+  
+    # Methods useful when dealing with Dates
+    module CalendarHelper
+
+      # You can use 'today' or any format which Date.parse can handle.
+      # @param [nil|String|Time|Date] param
+      # @return [Date] always returns a Date regardless of the type of input
+      def ensure_date(param)
+        if param.is_a?(Date) || param.is_a?(::Time)
+          param
+        elsif param =~ /today/i || param.nil?
+          Date.today 
+        else
+          Date.parse(param)
+        end
+      end
+    end
+
+    # Calendar has a name and will be stored in Persistent::DiskStore(CALENDAR_FILE)
+    # with it's name as the id. Thus you can save different calendars in
+    # the same file. If no name is given 'unnamed' will be the default.
+    class Calendar
+
+      include Persistent::Persistentable
+      include CalendarHelper
+
+      attr_reader :name, :start_date, :end_date, :events
+   
+      # @param [String] _name Name and persistent-id of this calendar.
+      # @param [Date|Time|String] _start The date when the calendar starts
+      # @param [Date|Time|String] _end   The date when the calendar ends
+      def initialize(_name='unnamed', _start=nil, _end=nil, _events=[])
+        @name       = _name
+        @start_date = parse_date_param(_start)
+        @end_date   = parse_date_param(_end)
+        @events     = _events
+      end
+
+
+      # Setter for from_date
+      # @param [Date|String] _from - new starting date
+      def from=(_from)
+        @start_date = parse_date_param(_from)
+      end
+
+      # Setter for to-date
+      # @param [Date|String] _to - new ending date
+      def to=(_to)
+        @end_date = parse_date_param(_to)
+      end
+
+      # Override Persistentable's id-method
+      # @return [String] - the calendar-name is it's id
+      def id
+        @name || super
+      end
+
+      # Add Eventables to the calendar
+      # @param [Eventable] add - the Object to add
+      def <<(add)
+        events << add 
+      end
+  
+      # Calculate the span between start and end in seconds
+      # @return [Float]
+      def span
+        ((end_date - start_date)*Numeric::DAYS).to_f
+      end
+  
+      # Array of strings for each day with events on it.
+      #
+      # @example
+      #     Mon, Aug 31 1964: Birthday Andreas Altendorfer
+      #
+      # @param [String|Date] start_on - output begins on this day
+      # @param [String|Date] end_on   - output ends on this day
+      # @param [Boolean] show_empty   - output days with no events
+      # @return [Array] of Strings DATE: EVENT + EVENT + ....
+      def list_days(start_on=start_date,end_on=end_date,show_empty=false)
+        (parse_date_param(start_on)..parse_date_param(end_on)).to_a.map { |_date|
+          format_events_for(_date,show_empty)
+        }.compact
+      end
+      
+  
+      private
+      # List Event-headlines for a given date
+      # @param [Date] date 
+      # @return [Array] of CalendarEvents
+      def events_on(date)
+        events.select { |event| event.event_date == date }
+      end
+      
+      # Convert strings to a date
+      # @param [Date|Time|String] param - default is 'today'
+      # @return [Date|Time]
+      def parse_date_param(param=Date.today)
+        ensure_date(param)
+      end
+
+      # Output date and Events on this date in one line
+      # @param [Date] _date
+      # @param [Boolean] show_empty - do not output lines with no events
+      # @return [String]
+      def format_events_for(_date,show_empty=false)
+        if show_empty ||
+          (_events = events_on(_date).map(&:event_headline).join(' + ').strip) != ''
+          [_date.strftime(DEFAULT_DATE_FORMAT), _events].compact.join(": ")
+        end
+      end
+  
+    end
+
+  end
+
+end

data/lib/modules/calendar/calendar_event.rb

@@ -0,0 +1,30 @@
+module RST
+
+  module Calendar
+
+    # A CalendarEvent happens on a given date and
+    # has a label. It's supposed to be appended to a Calendar-object
+    # @see Calendar
+    class CalendarEvent 
+
+      attr_reader :event_date, :label
+
+      include Eventable
+      include CalendarHelper
+
+      # @param [String|Date] _date - Date of the event (only all-day-events are possible yet)
+      # @param [String] _label - Events name
+      def initialize(_date,_label)
+        @event_date = ensure_date(_date)
+        @label = _label
+      end
+
+      # override abstract method for an Eventable
+      def event_headline
+        self.label.to_s.strip
+      end
+    end
+
+  end
+
+end 

data/lib/modules/calendar/eventable.rb

@@ -0,0 +1,50 @@
+module RST
+  module Calendar
+
+    # Inject Eventable to any Class to make it event-able in a Calendar
+    # You have to define a method :event_headline for the class
+    # in order to list the event in a Calendar
+    # @example
+    #
+    #   class Birthday < Struct.new(:name,:dob)
+    #     include Eventable
+    #     def initialize(*args)
+    #       super
+    #       schedule!(dob)
+    #     end
+    #
+    #     protected
+    #     def event_headline
+    #       "It's #{name}'s Birthday"
+    #     end
+    #  end
+    #
+    # @see RST::Calendar::Calendar
+    module Eventable
+
+      # @return [Date] the date when the event is scheduled
+      def event_date
+        @event_date
+      end
+      
+      # @return [Boolean] true if the object is scheduled (has an event_date)
+      def scheduled?
+        !event_date.nil?
+      end
+
+      # @param [Date|String] date schedule this object for the given date
+      # @return [Eventable] - self
+      def schedule!(date)
+        @event_date = date.is_a?(Date) ? date : Date.parse(date)
+        self
+      end
+
+      # used in calendar-output as a short entry
+      # @return [String]
+      def event_headline
+        "(untitled event)"
+      end
+
+    end
+  end
+end

data/lib/modules/persistent/disk_store.rb

@@ -0,0 +1,90 @@
+module RST
+  module Persistent
+
+    # #DiskStore is responsible to save an Array of objects
+    # persistently to the disk - PStore is used to effort this.
+    # @see RST::Persistent::Store
+    # @api persistent
+    class DiskStore < Store
+
+      attr_reader :filename
+
+      # The first argument is the filename
+      # Following args are passed to base-class
+      # @example
+      #
+      #     DiskStore.new('myfile')
+      #     DiskStore.new(filename: 'myfile', other_option: '...')
+      #
+      # @param [String] _filename 
+      # @param [Array] args - arguments passed to the super-class
+      def initialize(_filename='store.data',args={})
+        @filename = _filename
+        super(args)
+      end
+
+      # @return [String] full path of PStore-file
+      def path
+        @store.path
+      end
+
+      # @todo This is bad for performance and memory - refactor!
+      # @return [Array]
+      def all
+        _all = []
+        @store.transaction(true) do |s|
+          s.roots.each do |_r|
+            _all << s[_r]
+          end
+        end
+        _all
+      end
+
+      # Delete the store
+      def delete!
+        File.unlink(store_path)
+      end
+
+      private
+
+      # Initialize a PStore-instance
+      def setup_backend
+        @store = PStore.new(store_path)
+      end
+
+
+      # Determine the store-path from RST::STOREPATH and
+      # environment. Creates the path if not exists.
+      #
+      # @example
+      #     .../data/development/store.data
+      # 
+      # @return [String] 
+      def store_path
+        prefix = ENV['RST_DATA'] || RST::STOREPATH
+        env = ENV['RST_ENV'] || 'development'
+        _dir = File.join( prefix, env )
+        FileUtils.mkdir_p(_dir)
+        File.join(_dir, filename)
+      end
+
+      # Find and update or add object to the store.
+      # @param [Object] object
+      def update_or_add(object)
+        @store.transaction do |s|
+          s[object.id] = object
+        end
+      end
+     
+      # @param [Object] object - the object to be removed.
+      def remove_object(object)
+        @store.transaction do |s|
+          s.delete(object.id)
+        end
+      end
+
+    end
+
+  end
+end
+

data/lib/modules/persistent/memory_store.rb

@@ -0,0 +1,37 @@
+module RST
+
+  module Persistent
+
+    # # MemoryStore 
+    # doesn't really store the objects but holds them in
+    # memory, in a simple Array. Perfect for testing
+    # @api persistent
+    class MemoryStore < Store
+
+      # @return [Array]
+      def all
+        @objects || []
+      end
+
+      private
+
+      # Initialize an empty array as an in-memory-store
+      def setup_backend
+        @objects = []
+      end
+
+      # Find and update or add an object to the store
+      # @param [Object] object
+      def update_or_add(object)
+        @objects -= [object]
+        @objects << object
+      end
+
+      # @param [Object] object - the object to be removed
+      def remove_object(object)
+        @objects -= [object]
+      end
+    end
+  end
+end
+

data/lib/modules/persistent/persistent.rb

@@ -0,0 +1,36 @@
+require 'securerandom'
+require 'fileutils'
+
+module RST
+
+  # The Persistent-module injects Store-functions
+  # to any Object including it.
+  # @api persistent
+  module Persistent
+
+    KEY_LENGTH=8  # Length of Store-IDs
+
+    # The interface for persistent-able objects
+    module Persistentable
+
+      # Save the object to Store
+      def save
+      end
+
+      # Remove the object from Store
+      def delete
+      end
+
+      # If the object doesn't provide an id-method
+      # define one
+      unless respond_to?(:id)
+        # Set and return an unique ID
+        def id
+          @id ||= SecureRandom::hex(KEY_LENGTH)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/modules/persistent/store.rb

@@ -0,0 +1,118 @@
+require 'pstore'
+require 'store_errors'
+
+module RST
+
+  module Persistent
+
+    # # The abstract Store-base-class
+    # 
+    # Store provides the interface for all store-able classes
+    #
+    # ## Usage:
+    #
+    #   Derive a concrete store-class from 'Store' and overwrite the
+    #   following methods:
+    #
+    #   * setup_backend
+    #   * sync_store
+    #
+    # @abstract
+    #
+    class Store
+
+      # Sets options-hash and calls the abstract
+      # 'setup_backend'-callback
+      def initialize(args={})
+        @options = {}.merge(args)
+        setup_backend
+      end
+
+      # Add an object and sync store
+      # @param [Persistentable] object - object including the Persistent-module
+      def <<(object)
+        update_or_add(object)
+      end
+
+      # Remove an object from the store
+      # @param [Persistentable] object - the object to be removed from store
+      # @return [Store] self
+      def -(object)
+        remove_object(object)
+        self
+      end
+
+      # @return Enumerable
+      # @abstract
+      def all
+        raise AbstractMethodCallError.new("Please, overwrite #{__callee__} in #{self.class.to_s}")
+      end
+
+      # @return [Object|nil] the first object in the store
+      def first
+        all.first
+      end
+
+      # @param [Array] ids to search
+      # @return [nil] if nothing found
+      # @return [Object] if exactly one object found
+      # @return [Array] of objects with matching ids if more than one matched
+      def find(*ids)
+        flatten all.select { |obj| ids.include?(obj.id) }
+      end
+
+      # Delete the store
+      # @abstract - override this for real persistent store-classes
+      def delete!
+        @objects = []
+      end
+
+      private
+
+      # callback called from initializer and aimed to initialize the
+      # objects-array, PStore, database-connection,...
+      # @abstract
+      def setup_backend
+        raise AbstractMethodCallError.new("Please override method :setup_backend in class #{self.class.to_s}")
+      end
+
+      # Make sure the current state of objects is stored
+      # @abstract
+      def sync_store
+        # RST.logger.warn("Store class #{self.class.to_s} should overwrite method :sync_store" )
+      end
+
+      # Flatten the result of a select
+      # @param [Array] result
+      # @return [Array] if result contains more than one element
+      # @return [Object] if result contains exactly one element
+      # @return [nil] if result is empty
+      def flatten result
+        if result.count == 1
+          result.first
+        elsif result.nil? || result.empty?
+          nil
+        else
+          result
+        end
+      end
+
+
+      # Find and update or add an object to the store
+      # @param [Object] object
+      # @abstract - override in other StoreClasses
+      def update_or_add(object)
+        raise AbstractMethodCallError.new("Please, overrwrite #{__callee__} in #{self.class.to_s}")
+      end
+
+      # @param [Object] object
+      # @abstract - override in concrete StoreClasses
+      def remove_object(object)
+        raise AbstractMethodCallError.new("Please, overrwrite #{__callee__} in #{self.class.to_s}")
+      end
+
+    end
+
+  end
+
+end

data/lib/rst.rb

@@ -0,0 +1,295 @@
+require 'optparse'
+require 'ostruct'
+
+# # Ruby Shell Tools main namespace RST
+#
+# By now only two commands/features are available:
+#
+#  * **ls** - List files from the filesystem (OS-like ls)
+#  * **cal[endar]** - Stores and lists events in one calendar-file, 
+#    separated in different named calendars 
+#
+# See [EXAMPLES.md](./file.examples.html) for detailed instruction.
+#
+#
+# @author Andi Altendorfer <andreas@altendorfer.at>
+# @see https://github.com/iboard/rst
+# @see http://altendorfer.at
+module RST
+
+  # Interprets and runs options and commands.
+  # @example
+  #   runner = RstCommand.new(ARGV)
+  #   puts runner.run
+  # See [EXAMPLES.md](../file.examples.html)
+  class RstCommand
+
+    # Default options are always present, even if the user will not provide them.
+    # They can be overwritten, though. 
+    # @see #parse_options
+    DEFAULT_OPTIONS = { name: 'unnamed', from: 'today', to: 'today', show_empty: false }
+
+    # @group PUBLIC INTERFACE
+
+    # the hash stores options parsed in mehtod parse_options.
+    # @see #parse_options
+    attr_reader :options
+
+    # the first argument of ARGV is the command. It's extracted in run_command
+    # @see #run_command
+    attr_reader :command
+
+    # Initialize the Command-runner with arguments and parse them.
+    def initialize(args)
+      parse_options(args)
+    end
+
+    # Call 'run_options' and 'run_command', reject empty returns and join
+    #   output with CR
+    # @return [String]
+    def run
+      [run_options, run_command].compact.reject{|l| l.strip == '' }.join("\n")
+    end
+
+    private
+
+    # @group PREPARE OPTIONS AND COMMAND
+
+    # Interpret options from ARGV using OptionParser. No action here. The parsed
+    #   options get stored in '@options' and then will be used in run_options.
+    # @see #options
+    # @see #DEFAULT_OPTIONS
+    # @see #run_options
+    # @see #run_option
+    def parse_options(args)
+      @options = DEFAULT_OPTIONS
+      OptionParser.new do |opts|
+        opts.banner = 'Usage: rst [COMMAND [COMMAND ....]] [options] [FILES..]'
+
+        opts.separator "\nOptions:"
+
+        opts.on('-v', '--[no-]verbose', 'Run verbosely') do |v|
+          @options[:verbose] = v
+        end
+
+        opts.on('--examples', 'Show some usage examples') do |x|
+          @options[:examples] = x
+        end
+
+        opts.on('-h', '--help', 'Print help') do |h|
+          puts opts
+        end
+
+        opts.on('-f', '--from DATE', String, 'Set from-date') do |from|
+          @options[:from] = from
+        end
+
+        opts.on('-t', '--to DATE', String, 'Set to-date') do |to|
+          @options[:to] = to
+        end
+
+        opts.on('-n', '--name NAME', String, 'Use this name for the command') do |name|
+          @options[:name] = name
+        end
+
+        opts.on('-e', '--new-event DATE,STRING', Array, 'Add an event') do |date,name|
+          @options[:new_event] = {date: date, label: name}
+        end
+
+        opts.on('--list-calendars', 'List available calendars') do
+          @options[:list_calendars] = true
+        end
+
+        opts.on('--delete-calendar CALENDARNAME', String, 'Delete an calendar and all it\'s entries!') do |name|
+          @options[:delete_calendar] = name
+        end
+
+        opts.on('--[no-]empty', 'Show empty entries') do |show|
+          @options[:show_empty] = show
+        end
+
+        opts.separator 'Commands:'
+
+        opts.separator <<-EOT
+          nil .......... no command. Interpret options only (useful in combination with -v)
+          ls ........... list directory and files
+          cal[endar] ... print a calendar --from --to
+        EOT
+        .gsub(/^\s+/,'    ')
+
+        opts.separator "\n    use --example for a more detailed list of commands."
+      end
+      .parse!(args)
+    rescue => e
+      puts "#{e.class} => #{e.message}"
+      puts "Try #{File.basename($0)} --help"
+    end
+
+    # Iterate over all given options and call run_option for each
+    # @see #run_option
+    # @return [String]
+    def run_options
+      options.map { |k,_v| run_option(k) }.compact.join("\n")
+    end
+
+    # Run the 'command', the first argument of ARGV.
+    # If a command is not known/invalid print out a hint to --help
+    # Known commands are:
+    # @see #directory_listing
+    # @see #print_calendar
+    # @see #command
+    # @return [String]
+    def run_command
+      case @command=ARGV.shift
+      when nil, 'nil', 'null'
+        ''
+      when 'ls'
+        directory_listing(ARGV.empty? ? ['*'] : ARGV)
+      when 'cal', 'calendar'
+        print_calendar
+      else
+        "unknown command '#{cmd.inspect}' - try --help"
+      end
+    end
+
+
+    # @group EXECUTE COMMANDS
+
+    # Do a Dir for each file-mask given.
+    # Duplicated files are stripped.
+    # @example
+    #   rst ls lib/*rb
+    # @param [Array] files - a list of files/wildcards
+    # @return [String] - tab-delimited files found
+    def directory_listing(files)
+      files.map { |f| Dir[f].join("\t") }.uniq.join("\t")
+    end
+
+    # Output one line per day between start and end-date
+    # Start- and end-date are given with options --from, and --to
+    # Option --empty will output dates without events too.
+    # default is --no-empty which will suppress those lines in output
+    # @example 
+    #   rst cal --from 1.1.1990 --to today --name Birthdays
+    # @return [Array] - one string Date: Event + Event + ... for each day.
+    def print_calendar
+      cal = find_calendar( Persistent::DiskStore.new(CALENDAR_FILE) )
+      cal.list_days(options[:from], options[:to], options[:show_empty]).compact.join("\n")
+    end
+
+    # @group EXECUTE ACTION FROM OPTIONS
+
+    # Execute a single option
+    # @see #parse_options
+    # @see #run_options
+    # @param [String] option (examples, verbose, new_event,...)
+    def run_option(option)
+      case option.to_s
+      when 'examples'
+        File.read(File.join(DOCS,'examples.md')).strip
+      when 'verbose'
+        print_arguments
+      when 'new_event'
+        new_event = add_event
+        "Added: %s: %s" % [new_event.event_date.strftime(DEFAULT_DATE_FORMAT), new_event.event_headline.strip]
+      when 'list_calendars'
+        list_calendars
+      when 'delete_calendar'
+        delete_calendar
+      else
+        nil #noop ignore unknown options likely it's a param for an argument
+      end
+    end
+
+    # Add an event to the calendar.
+    # @example
+    #   --add-event DATE,LABEL
+    # @return [CalendarEvent] - the just created event
+    def add_event
+      event_environment do |ee|
+        ee[:calendar] << ee[:event]
+        ee[:store] << ee[:calendar]
+        ee[:event]
+      end
+    end
+
+    # remove a calendar from calendar-file named in options[:delete_calendar]
+    # @example
+    #   --delete-calendar CALENDARNAME
+    def delete_calendar
+      store = Persistent::DiskStore.new(CALENDAR_FILE)
+      store -= OpenStruct.new(id: options[:delete_calendar])
+      nil
+    end
+
+    # List available calendars and count events of each one.
+    # @return [Array] One line/String for each calendar
+    def list_calendars
+      store = Persistent::DiskStore.new(CALENDAR_FILE)
+      store.all.map { |calendar|
+        cnt = calendar.events.count
+        "%-20.20s: %d %s" % [calendar.id, cnt > 0 ? cnt : 'no', cnt > 1 ? 'entries' : 'entry']
+      }
+    end
+
+    # Output the previous interpreted and parsed arguments
+    # Called when --verbose is given as an option
+    # @example
+    #   rst --verbose
+    def print_arguments
+      puts "Binary : #{$0}"
+      puts "Command: #{command}"
+      puts "Options: #{options.map(&:inspect).join(', ')}"
+      puts "Files  : #{ARGV.any? ? ARGV[1..-1].join(', ') : ''}"
+    end
+
+    # @group HELPERS
+
+    # Find or initialize a calendar-object. The name comes from option --name.
+    # @param [Store] store - the Store-object where to search for calendar
+    # @return [Calendar]
+    def find_calendar(store)
+      store.find(options[:name]) || Calendar::Calendar.new(options[:name], options[:from], options[:to])
+    end
+
+    # Find the date, label, and calendar_name for an event from options
+    # @yield [EventOptions]
+    def get_event_options
+      date = options[:new_event].fetch(:date) { Date.today.strftime('%Y-%m-%d') }
+      label = options[:new_event].fetch(:label) { 'unnamed event' }
+      calendar_name = options.fetch(:name) { 'calendar' }
+      yield(EventOptions.new(date, label, calendar_name))
+    end
+
+
+    # Initialize an EventEnvironment used to operate events in stores.
+    # @see #add_event
+    # @yield [EventEnvironment]
+    def event_environment
+      get_event_options do |eo|
+        event    = Calendar::CalendarEvent.new(eo[:date], eo[:label])
+        store    = Persistent::DiskStore.new(CALENDAR_FILE)
+        calendar = store.find(eo[:calendar_name]) || Calendar::Calendar.new(eo[:calendar_name])
+        yield(EventEnvironment.new(event,store,calendar))
+      end
+    end
+
+  end
+
+  # @group HELPER CLASSES
+
+  # EventEnvironment holds the CalendarEvent and the DiskStore, and Calendar to which the event belongs
+  # @api private
+  # @see RstCommand#event_environment
+  class EventEnvironment < Struct.new(:event,:store,:calendar)
+  end
+
+  # EventOptions holds the options date,label, and calendar_name
+  # @api private
+  # @see RstCommand#get_event_options
+  class EventOptions < Struct.new(:date,:label,:calendar_name,)
+  end
+
+
+
+end

data/rst.rb

@@ -0,0 +1,31 @@
+require 'logger'
+
+# # Ruby Shell Tools Top-level file
+module RST
+  # Gem-version
+  VERSION   = '0.0.1'
+
+  # Path to the docs used by the software
+  DOCS      = File.expand_path('../assets/docs', __FILE__)
+
+  # Default DataStore-path. You can overwrite this by
+  # defining `ENV[RST_DATA]`
+  STOREPATH = File.expand_path('../data/', __FILE__)
+
+  
+  # intialize the logger
+  # @example Usage
+  #   RST.logger.info('This will output to STDERR')
+  def logger
+    @logger ||= Logger.new(STDERR)
+  end
+
+  # initialize a new logger. Necessary from within specs to capture the
+  # output for testing.
+  # @param [File|Stream] _output
+  def logger!(_output)
+    @logger = Logger.new(_output)
+  end
+
+
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: rubyshelltools
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Andi Altendorfer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Tools for the unix shell
+email: andreas@altendorfer.at
+executables:
+- rst
+extensions: []
+extra_rdoc_files:
+- README.md
+- assets/docs/examples.md
+files:
+- ./rst.rb
+- lib/core_extensions/numeric.rb
+- lib/errors/store_errors.rb
+- lib/load.rb
+- lib/modules/calendar/calendar.rb
+- lib/modules/calendar/calendar_event.rb
+- lib/modules/calendar/eventable.rb
+- lib/modules/persistent/disk_store.rb
+- lib/modules/persistent/memory_store.rb
+- lib/modules/persistent/persistent.rb
+- lib/modules/persistent/store.rb
+- lib/rst.rb
+- bin/rst
+- README.md
+- assets/docs/examples.md
+homepage: http://rubygems.org/gems/rubyshelltools
+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.25
+signing_key: 
+specification_version: 3
+summary: Ruby Shell Tools
+test_files: []
+has_rdoc: