pod4 0.6.2

data/lib/pod4/alert.rb

@@ -0,0 +1,87 @@
+module Pod4
+  
+
+  ##
+  # An Alert is an error, warning or note which might be raised in validation
+  # in the model. They are, however, designed to follow all the way through the
+  # controller to the view; you should use them whenever you want to display a
+  # message on the page.
+  #
+  class Alert
+
+    # Valid values for @type: :error, :warning, :info or :success
+    ALERTTYPES = [:error, :warning, :info, :success]
+
+    # The alert type
+    attr_reader :type
+
+    # The exception attached to the alert, or nil if there isn't one
+    attr_reader :exception
+
+    # The field name associated with the alert, or nil
+    attr_accessor :field
+
+    # The alert message
+    attr_accessor :message
+
+
+    ##
+    # A new alert must have a type (error warning info or success); there
+    # should be a message to display, obviously. Note that you can pass an
+    # exception in place of a message, in which case @exception will be set.
+    #
+    # You may optionally specify the name of the field to be highlighted.
+    # Models will give validation alerts a field that corresponds to the model
+    # attribute; but this is not enforced here, and your controller will have
+    # to sort things out if the model is expecting different field names.
+    #
+    def initialize(type, field=nil, message)
+      raise ArgumentError, "unknown alert type" \
+        unless ALERTTYPES.include? type.to_s.to_sym
+
+      @type      = type.to_s.to_sym
+      @field     = field ? field.to_sym : nil
+      @exception = nil
+
+      if message.kind_of?(Exception)
+        @exception = message.dup
+        @message   = @exception.message
+
+        # SwingShift validation exceptions hold the field name
+        @field ||= @exception.field if @exception.respond_to?(:field)
+
+      else
+        @message = message
+
+      end
+    end
+
+
+    ##
+    # An array of Alert is automatically sorted into descending order of
+    # seriousness
+    #
+    def <=>(other)
+      ALERTTYPES.index(self.type) <=> ALERTTYPES.index(other.type)
+    end
+
+
+    ##
+    # Write self to the log
+    #
+    def log(file='')
+      case self.type
+        when :error   then Pod4.logger.error(file) { self.message }
+        when :warning then Pod4.logger.warn(file)  { self.message }
+        else Pod4.logger.info(file) { self.message }
+      end
+
+      self
+    end
+
+
+  end
+  ##
+
+
+end

data/lib/pod4/basic_model.rb

@@ -0,0 +1,137 @@
+require 'octothorpe'
+
+require_relative 'metaxing'
+require_relative 'errors'
+require_relative 'alert'
+
+
+module Pod4
+
+
+  ##
+  # The ultimate parent of all models. It has an interface, an id, a status, 
+  # and alerts. That's pretty much it.
+  #
+  # This is useful to the user for weirder models -- for example, where the
+  # datasource records and the model instances don't map one-to-one.
+  #
+  # See Pod4::Model for documentation about Models.
+  #
+  class BasicModel
+    extend Metaxing
+
+    
+    # The value of the ID field on the record
+    attr_reader :model_id
+
+    # one of Model::STATII
+    attr_reader :model_status
+
+    # Valid values for @model_status: :error :warning :okay :deleted or :empty
+    STATII = %i|error warning okay deleted empty|
+
+
+    class << self
+
+      ##
+      # You MUST call this in your model definition to give it an instance of an
+      # interface. 
+      #
+      def set_interface(interface)
+        define_class_method(:interface) {interface}
+      end
+
+      def interface
+        raise NotImplemented, "no call to set_interface in the model"
+      end
+
+    end
+    ##
+
+
+    ##
+    # Initialize a model by passing it a unique id value.
+    # Override this to set initial values for your column attributes.
+    #
+    def initialize(id=nil)
+      @model_status = :empty
+      @model_id     = id
+      @alerts       = []
+    end
+
+
+    ##
+    # Syntactic sugar; same as self.class.interface, which returns the
+    # interface instance.
+    #
+    def interface; self.class.interface; end
+
+
+    ##
+    # Return the list of alerts. 
+    #
+    # We don't use attr_reader for this because it won't protect an array from
+    # external changes.
+    #
+    def alerts; @alerts.dup; end
+
+
+    ##
+    # Clear down the alerts.
+    #
+    # Note that set model_status to :okay. Theoretically it might need to be
+    # :empty or :deleted, but if you are calling clear_alerts before a call to
+    # `read` or after a call to `delete`, then you have more problems than I
+    # can solve.
+    #
+    def clear_alerts
+      @alerts       = []
+      @model_status = :okay
+    end
+
+
+    ##
+    # Raise a SwingShift exception for the model if any alerts are status
+    # :error; otherwise do nothing.
+    #
+    # Note the alias of or_die for this method, which means that if you have
+    # kept to the idiom of CRUD methods returning self, then you can steal a
+    # lick from Perl and say:
+    #     MyModel.new(14).read.or_die
+    #
+    def raise_exceptions
+      al = @alerts.sort.first
+      raise ValidationError.from_alert(al) if al && al.type == :error
+      self
+    end
+
+    alias :or_die :raise_exceptions
+
+
+    private
+
+    
+    ##
+    # Add a Pod4::Alert to the model instance @alerts attribute
+    #
+    # Call this from your validation method.
+    #
+    def add_alert(type, field=nil, message)
+      return if @alerts.any? do |a| 
+        a.type == type && a.field == field && a.message = message
+      end
+
+      lert = Alert.new(type, field, message).log(caller.first.split(':').first)
+      @alerts << lert
+
+      st = @alerts.sort.first.type
+      @model_status = st if %i|error warning|.include?(st)
+    end
+
+    
+  end
+  ##
+
+
+end
+

data/lib/pod4/errors.rb

@@ -0,0 +1,80 @@
+module Pod4
+
+
+  ## 
+  # Raised in abstract methods when treated as concrete
+  #
+  class NotImplemented < Exception
+    
+    def initialize(msg=nil)
+      super(msg || $! && $!.message)
+    end
+
+  end
+
+
+  ##
+  # Base error class for Swingshift
+  #
+  # Also used for any configuration errors where ArgumentError is not
+  # appropriate.
+  #
+  class Pod4Error < StandardError
+
+    def initialize(msg=nil)
+      super(msg || $! && $!.message)
+    end
+
+  end
+  ##
+
+
+  ##
+  # Raised if something goes wrong on the database
+  #
+  class DatabaseError < Pod4Error
+
+    def initialize(msg=nil)
+      super(msg || $! && $!.message)
+    end
+
+  end
+  ##
+
+
+  ##
+  # Raised if a Pod4 method runs into problems
+  #
+  # Note, invalid parameters get a Ruby ArgumentError. This is for, eg, an
+  # interface finding that the ID it was given to read does not exist.
+  #
+  class CantContinue < Pod4Error
+
+    def initialize(msg=nil)
+      super(msg || $! && $!.message)
+    end
+
+  end
+  ##
+
+
+  ##
+  # Raised if validation fails (and you wanted an exception...)
+  #
+  class ValidationError < Pod4Error
+    attr_reader :field
+
+    def self.from_alert(alert)
+      self.new(alert.message, alert.field)
+    end
+
+    def initialize(message=nil, field=nil)
+      super(message || $! && $!.message)
+      @field = field.to_s.to_sym
+    end
+
+  end
+
+
+end
+

data/lib/pod4/interface.rb

@@ -0,0 +1,110 @@
+require_relative 'metaxing'
+require_relative 'errors'
+
+
+module Pod4
+
+
+  ##
+  # Abstract class, The parent of all interfaces.
+  #
+  # An interface encapsulates whatever method we are using up connect to the
+  # data. Its state is therefore that of the connection, not the DB table or
+  # whatever entity that the data source uses to group data. It raises only
+  # SwingShift errors (wrapping the error it gets inside a SwingShift error).
+  #
+  # We would expect a child of Interface for each data access type
+  # (sequelInterface, NebulousInterface, etc). These children *will not change*
+  # the signatures of the methods below.
+  #
+  # The methods below are the required ones. Interfaces will likely implement
+  # other, interface-specific, ways of accessing data.
+  #
+  # In Normal use, the interface classes will in turn be subclassed as inner
+  # classes within each model, in order to customise them for the specific
+  # entity that they are drawing data from. 
+  #
+  # Note that your Interface subclass probably returns an Octothorpe rather
+  # than a Hash, q.v..  (But you should be able to treat the former as if it
+  # were the latter in most cases.)
+  #
+  class Interface
+    extend Metaxing
+
+
+    ACTIONS = [ :list, :create, :read, :update, :delete ]
+
+    ##
+    # A field name in the data source, the name of the unique ID field.
+    #
+    def id_fld
+      raise NotImplemented, "Interface needs to define an 'id_fld' method"
+    end
+
+
+    ##
+    # Individual implementations are likely to have very different initialize
+    # methods, which will accept whatever SwingShift object is needed to
+    # contact the data store, eg. the Sequel DB object. 
+    #
+    def initialize
+      raise NotImplemented, "Interface needs to define an 'initialize' method"
+    end
+
+
+    ##
+    # List accepts a parameter as selection criteria, and returns an array of
+    # Octothorpes. Exactly what the selection criteria look like will vary from
+    # interface to interface. So will the contents of the return OT, although
+    # it must include the ID field. (Ideally each element of the return array
+    # should follow the same format as the return value for read(). )
+    #
+    # Note that list should ALWAYS return an array; never nil.
+    #
+    def list(selection=nil)
+      raise NotImplemented, "Interface needs to define 'list' method"
+    end
+
+
+    ##
+    # Create accepts a record parameter (Hash or OT, but again, the format of
+    # this will vary) representing a record, and creates the record.  Should
+    # return the ID for the new record.
+    #
+    def create(record)
+      raise NotImplemented, "Interface needs to define 'create' method"
+    end
+
+
+    ##
+    # Read accepts an ID, and returns an Octothorpe representing the unique
+    # record for that ID. If there is no record matching the ID then it returns
+    # an empty Octothorpe.
+    #
+    def read(id)
+      raise NotImplemented, "Interface needs to define 'read' method"
+    end
+
+
+    ##
+    # Update accepts an ID and a record parameter. It updates the record on the
+    # data source that matches the ID using the record parameter.  It returns
+    # self.
+    #
+    def update(id, record)
+      raise NotImplemented, "Interface needs to define 'update' method"
+    end
+
+
+    ##
+    # delete removes the record with the given ID. returns self.
+    #
+    def delete(id)
+      raise NotImplemented, "Interface needs to define 'delete' method"
+    end
+
+
+  end
+
+
+end

data/lib/pod4/metaxing.rb

@@ -0,0 +1,66 @@
+module Pod4
+
+
+  ##
+  # A little mixin for metaprogramming
+  #
+  module Metaxing
+
+    ##
+    # Return the metaclass (eigenclass) of self.
+    #
+    def metaclass
+      class << self; self; end
+    end
+
+
+    ##
+    # Define (or re-define) a class method.
+    #
+    # Example:
+    #     
+    #     class Foo
+    #       extend Metaxing
+    #
+    #       class << self
+    #         def set_bar(x); define_class_method(:bar) {x}; end
+    #       end
+    #     end
+    #
+    #     class MyFoo < Foo; end
+    #
+    #     Foo.set_bar(23)
+    #     puts Foo.bar   # -> 23
+    #     puts MyFoo.bar # -> 23
+    #
+    #     MyFoo.set_bar(42) 
+    #     puts Foo.bar   # -> 23
+    #     puts MyFoo.bar # -> 42
+    # 
+    # This example gives us something different from a class attribute @@bar --
+    # the value of which would be shared between Foo and MyFoo.  And different
+    # again from an attribute @bar on class Foo, which wouldn't turn up in
+    # MyFoo at all. This is a value that has inheritance.
+    #
+    # And this example shows pretty much the only metaprogramming trick you
+    # will find me pulling.  It's enough to do a hell of a lot.
+    #
+    # Note that you need to be very careful what parameters you pass in order
+    # to preserve this inheritance: if you pass a reference to something on
+    # Foo, you will be sharing it with MyFoo, not just inheriting it. Best to
+    # use local variables or dups.
+    #
+    # ...Well, actually, you aren't getting a method on the class -- these are
+    # defined in the class' immediate ancestor, eg, Object. You're getting a
+    # method on the eigenclass, which Ruby inserts between the class' ancestor
+    # and the class. For all of me I can't see a practical difference when it
+    # comes to defining class methods.
+    #
+    def define_class_method(method, *args, &blk)
+      metaclass.send(:define_method, method, *args, &blk)
+    end
+
+  end
+
+
+end