rubyshelltools 0.0.1 → 0.0.2

data/lib/core_extensions/mutex.rb

@@ -0,0 +1,17 @@
+# Not sure if this is a bug. 
+# Anyhow, PStore works only if the two methods are defined for Muttex.
+# @see Persistent::DiskStore
+class Mutex
+  if  RUBY_VERSION >= "1.9"
+    #:nodoc
+    def marshal_dump
+      []
+    end
+
+    #:nodoc
+    def marshal_load array
+      # do nothing
+    end
+  end
+end
+

data/lib/load.rb

@@ -7,8 +7,13 @@ unless defined? LIB_LOADED
   DEFAULT_DATE_FORMAT = '%a, %b %d %Y'
 
   # Filename for the calendar-store
+  # @see Calendar::Calendar
   CALENDAR_FILE = 'calendars.data'
 
+  # If no calendar-name is given
+  # @see Calendar::Calendar
+  DEFAULT_CALENDAR_NAME = 'unnamed'
+
   require File.expand_path('../../rst',__FILE__)
 
   # Load all necessary files
@@ -16,6 +21,7 @@ unless defined? LIB_LOADED
 
   $LOAD_PATH.unshift(File.expand_path('../core_extensions',__FILE__))
   require 'numeric'
+  require 'mutex'
 
   $LOAD_PATH.unshift(File.expand_path('../errors',__FILE__))
   require 'store_errors'

data/lib/modules/calendar/calendar.rb

@@ -6,7 +6,9 @@ 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.
+  # to store the calendar in a store using this name as the id.
+  #
+  # @see Persistent::DiskStore
   #
   # @example
   #
@@ -38,7 +40,7 @@ module RST
   #
   module Calendar
   
-    # Methods useful when dealing with Dates
+    # Some helper-methods useful when dealing with dates
     module CalendarHelper
 
       # You can use 'today' or any format which Date.parse can handle.
@@ -58,6 +60,9 @@ module RST
     # 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.
+    # @see CALENDAR_FILE
+    # @see Persistent::DiskStore
+    # @see Calendar::CalendarEvent
     class Calendar
 
       include Persistent::Persistentable
@@ -68,7 +73,8 @@ module RST
       # @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=[])
+      # @see DEFAULT_CALENDAR_NAME
+      def initialize(_name=DEFAULT_CALENDAR_NAME, _start=nil, _end=nil, _events=[])
         @name       = _name
         @start_date = parse_date_param(_start)
         @end_date   = parse_date_param(_end)
@@ -89,6 +95,7 @@ module RST
       end
 
       # Override Persistentable's id-method
+      # @see Persistent::Persistentable
       # @return [String] - the calendar-name is it's id
       def id
         @name || super
@@ -123,9 +130,9 @@ module RST
       
   
       private
-      # List Event-headlines for a given date
+      # All events on the given date
       # @param [Date] date 
-      # @return [Array] of CalendarEvents
+      # @return [Array] of [CalendarEvents]
       def events_on(date)
         events.select { |event| event.event_date == date }
       end
@@ -139,14 +146,20 @@ module RST
 
       # Output date and Events on this date in one line
       # @param [Date] _date
-      # @param [Boolean] show_empty - do not output lines with no events
+      # @param [Boolean] show_empty - do 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(": ")
+        if show_empty || (_line=event_headlines_for(_date)) != ''
+          "%s: %s" % [_date.strftime(DEFAULT_DATE_FORMAT), _line]
         end
       end
+
+      # Concatenate headlines of all events on this date
+      # @param [Date] _date
+      # @return [String]
+      def event_headlines_for(_date)
+        events_on(_date).map(&:event_headline).join(' + ').strip
+      end
   
     end
 

data/lib/modules/calendar/calendar_event.rb

@@ -2,9 +2,22 @@ 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
+    # A CalendarEvent happens on a given date and has a label. 
+    # It's can be used in a Calendar
+    # @see Calendar::Calendar
+    # @see Calendar::Eventable
+    # @example
+    #
+    #  calendar = Calendar::Calendar.new('my calendar')
+    #  event = Calendar::CalendarEvent.new( 'today', "I'm happy" )
+    #  calendar << event
+    #  calendar.format_events_for(Date.today) 
+    #    => "Sun, Mar 17 2013: I'm happy"
+    #  calendar << Calendar::CalendarEvent.new('2013-03-18', "Back to work :(")
+    #  calendar.list_days('today','4/2013')
+    #    => Sun, Mar 17 2013: I'm happy
+    #    => Mon, Mar 18 2013: Back to work :(
+    #
     class CalendarEvent 
 
       attr_reader :event_date, :label
@@ -15,8 +28,8 @@ module RST
       # @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
+        schedule! ensure_date(_date)
       end
 
       # override abstract method for an Eventable

data/lib/modules/calendar/eventable.rb

@@ -40,9 +40,10 @@ module RST
       end
 
       # used in calendar-output as a short entry
+      # @abstract - overwrite in descendants
       # @return [String]
       def event_headline
-        "(untitled event)"
+        self.inspect
       end
 
     end

data/lib/modules/persistent/disk_store.rb

@@ -4,21 +4,25 @@ module RST
     # #DiskStore is responsible to save an Array of objects
     # persistently to the disk - PStore is used to effort this.
     # @see RST::Persistent::Store
+    # @see Mutex
     # @api persistent
     class DiskStore < Store
 
-      attr_reader :filename
+      # [String] filename - used for PStore (no path! filename only) 
+      # @see #store_path
+      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: '...')
-      #
+      #     DiskStore.new('myfile', other_option: '...')
+      #     DiskStore.new( nil, other_option: '...') # use default filename
+      # @see DEFAULT_STORE_FILENAME
       # @param [String] _filename 
       # @param [Array] args - arguments passed to the super-class
-      def initialize(_filename='store.data',args={})
+      def initialize(_filename=DEFAULT_STORE_FILENAME,args={})
         @filename = _filename
         super(args)
       end
@@ -45,9 +49,18 @@ module RST
         File.unlink(store_path)
       end
 
+      # Find and update or add object to the store.
+      # @param [Object] object
+      def update(object)
+        @store.transaction do |s|
+          s[object.id] = object
+        end
+      end
+     
       private
 
       # Initialize a PStore-instance
+      # @see store_path
       def setup_backend
         @store = PStore.new(store_path)
       end
@@ -57,8 +70,13 @@ module RST
       # environment. Creates the path if not exists.
       #
       # @example
-      #     .../data/development/store.data
+      #     RST_ENV=development
+      #     RST_DATA=$HOME/.rst-data
+      #
+      #     ~/.rst-data/development/store.data
       # 
+      # if no environment-variables defined, the defaulsts will be STOREPATH and 'development'
+      # @see STOREPATH
       # @return [String] 
       def store_path
         prefix = ENV['RST_DATA'] || RST::STOREPATH
@@ -68,21 +86,12 @@ module RST
         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

data/lib/modules/persistent/memory_store.rb

@@ -13,6 +13,18 @@ module RST
         @objects || []
       end
 
+      # Find and update or add an object to the store
+      # @param [Object] object
+      def update(object)
+        @objects -= [object]
+        @objects << object
+      end
+
+      # remove all objects
+      def delete!
+        @objects = []
+      end
+
       private
 
       # Initialize an empty array as an in-memory-store
@@ -20,17 +32,17 @@ module RST
         @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
+
+      # Make sure the current state of objects is stored
+      # @abstract - Overwrite in descendants thus every object gets persistently stored.
+      def sync_store
+        #noop for MemoryStore
+      end
+
     end
   end
 end

data/lib/modules/persistent/persistent.rb

@@ -6,30 +6,66 @@ module RST
   # The Persistent-module injects Store-functions
   # to any Object including it.
   # @api persistent
+  # @see [Store]
+  # @example
+  #
+  #   store = MemoryStore.new
+  #   object= store.create { PersistentableObject.new }
+  #   ...modify object ...
+  #   object.save
+  #
+  #   object = store.find(object.id)
+  #   object.delete
+  #
   module Persistent
 
-    KEY_LENGTH=8  # Length of Store-IDs
+    KEY_LENGTH=42  # Length of Store-IDs
 
     # The interface for persistent-able objects
     module Persistentable
 
+      attr_reader :store # @see Persistent::Store
+
       # Save the object to Store
       def save
+        store.update(self)
       end
 
       # Remove the object from Store
       def delete
+        self.store -= self
       end
 
       # If the object doesn't provide an id-method
       # define one
       unless respond_to?(:id)
-        # Set and return an unique ID
+        # Return an unique ID (create one if not exists yet)
+        # @return [String]
+        # @see KEY_LENGTH
         def id
           @id ||= SecureRandom::hex(KEY_LENGTH)
         end
       end
 
+      # Setter for store-attribute
+      # @param [Store] store
+      def store=(store)
+        move_store(store)
+      end
+
+      private
+
+      # Move the object to another store
+      # @abstract - Moving is not implemented yet, though. The method sets the store-attribute if not set already.
+      def move_store store
+        if @store && @store != store
+          raise NotImplementedError.new('An object can\'t be moved to another store')
+        elsif @store == store
+          self
+        else
+          @store = store
+        end
+      end
     end
 
   end

data/lib/modules/persistent/store.rb

@@ -9,18 +9,13 @@ module RST
     # 
     # 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
+    # @abstract public API-methods should not be overwritten by descendant classes. 
+    #  But descendants must overwrite all methods marked as abstract here.
     #
     class Store
 
+      # @group PUBLIC API
+
       # Sets options-hash and calls the abstract
       # 'setup_backend'-callback
       def initialize(args={})
@@ -29,9 +24,9 @@ module RST
       end
 
       # Add an object and sync store
-      # @param [Persistentable] object - object including the Persistent-module
+      # @param [Persistentable] object - any object including the Persistent-module
       def <<(object)
-        update_or_add(object)
+        update(object)
       end
 
       # Remove an object from the store
@@ -42,46 +37,62 @@ module RST
         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
+      # @return [Object|nil] the first object in the store or nil if the store is empty.
       def first
         all.first
       end
 
-      # @param [Array] ids to search
-      # @return [nil] if nothing found
+      # @param [Array|String] ids or id 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
+      # @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 = []
+
+      # Create objects and set the object's store-attribute
+      # @example
+      #
+      #   new_object = store.create
+      #     MyClass.new(....)
+      #   end
+      #
+      # @return [Persistentable] - the newly created object
+      def create
+        obj = yield
+        obj.store = self
+        self << obj
+        obj
       end
 
-      private
+      # @group ABSTRACT METHODS TO BE OVERWRITTEN IN DESCENDANTS
 
-      # 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}")
+      # @return Enumerable
+      # @abstract Overwrite in descendants thus it returns an Enumerable of all objects in the store
+      def all
+        raise AbstractMethodCallError.new("Please, overwrite #{__callee__} in #{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" )
+      # Delete the store
+      # @abstract - override this method in descendants thus the store removes all objects.
+      def delete!
+        raise AbstractMethodCallError.new("Please, overrwrite #{__callee__} in #{self.class.to_s}")
       end
 
+      # Find and update or add an object to the store
+      # @param [Object] object
+      # @abstract - override in other StoreClasses
+      def update(object)
+        raise AbstractMethodCallError.new("Please, overrwrite #{__callee__} in #{self.class.to_s}")
+      end
+
+      # @endgroup
+      
+      private
+
+      # @group PRIVATE API
+      
       # Flatten the result of a select
       # @param [Array] result
       # @return [Array] if result contains more than one element
@@ -97,12 +108,19 @@ module RST
         end
       end
 
+      # @group ABSTRACT METHODS TO BE OVERWRITTEN IN DESCENDANTS
 
-      # 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}")
+      # callback called from initializer. Aimed to initialize the
+      # objects-array, PStore, database-connection,...
+      # @abstract - Overwrite in descendants thus they initialize the store.
+      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 - Overwrite in descendants thus every object gets persistently stored.
+      def sync_store
+        raise AbstractMethodCallError.new("Please override method :sync_store in class #{self.class.to_s}")
       end
 
       # @param [Object] object

data/rst.rb

@@ -3,7 +3,7 @@ require 'logger'
 # # Ruby Shell Tools Top-level file
 module RST
   # Gem-version
-  VERSION   = '0.0.1'
+  VERSION   = '0.0.2'
 
   # Path to the docs used by the software
   DOCS      = File.expand_path('../assets/docs', __FILE__)
@@ -11,8 +11,10 @@ module RST
   # Default DataStore-path. You can overwrite this by
   # defining `ENV[RST_DATA]`
   STOREPATH = File.expand_path('../data/', __FILE__)
-
   
+  # @see Persistent::DiskStore
+  DEFAULT_STORE_FILENAME = 'rst_data.pstore'
+
   # intialize the logger
   # @example Usage
   #   RST.logger.info('This will output to STDERR')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubyshelltools
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-16 00:00:00.000000000 Z
+date: 2013-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
@@ -69,6 +69,7 @@ extra_rdoc_files:
 - assets/docs/examples.md
 files:
 - ./rst.rb
+- lib/core_extensions/mutex.rb
 - lib/core_extensions/numeric.rb
 - lib/errors/store_errors.rb
 - lib/load.rb