pod4 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dc0ac6c69b4368ab5869b6ce236e1929d83fb743
+  data.tar.gz: 2e7a203ae10b29cc7aaac3fd743851673d494a31
+SHA512:
+  metadata.gz: aecfa93561a918dffe716767f8fd2d60c08e64107ec5d3ddfce165af22efa9c3177e44812d58fb7ab0815febcea2a3bdb642a58167f0b1838554d70fc66ef0f9
+  data.tar.gz: 5be87522d0cd6726bbb2f3427c6923c19b69f0f2f35fd782511cdead8216f86e9e9ddb359fff9cb43b2c7bd38aabf2bdf18eafce19653162edf8eff64bf5a884

data/.hgignore

@@ -0,0 +1,18 @@
+syntax: regexp
+
+^\.bundle/
+^Gemfile.lock
+^doc/
+^pkg/
+^spec/reports/
+^tmp/
+
+syntax: glob
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-gemset
+.rbenv-gemsets
+.Project

data/.hgtags

@@ -0,0 +1,19 @@
+04cffd78b3e0930c939f44a989269064d7d03215 0.0.1
+287d2bb72137613beb6d823121665c7a1ced7bb1 0.0.02
+8addfcadc2235aa7af8038c704fac2c17f73116a 0.1.1
+33b88651c62b76862573eb4293b4e70db81a4b0c 0.1.2
+e9204609efd7d401bdaa7f8a968f8584d70e0b48 0.1.3
+24c3a9549ca5df4d6600ff68fec425d6ad1260b6 0.2.0
+24c3a9549ca5df4d6600ff68fec425d6ad1260b6 0.2.0
+c57a3e107c858f0e24d0c9ba11d411d405605b73 0.2.0
+eecb1a60c825da7d4ff939dc1f170a1d37c0b32b 0.2.1
+cd5e8689ef022710507836f94b3813bacba6a142 0.2.2
+06be9d910c37970a239a192676aab6324d0d6657 0.2.3
+e738477c1e40988c0a6b6b38443a1981f00612a3 0.3.0
+c6b6c49f3ab363771da53cb3cdbd31e284332721 0.3.1
+885291d30186092f87c62fd0225dec6fcdab2dd2 0.4.0
+cea39858d97318fd8a7e32b41de7f259e367b920 0.4.1
+c2743ca54c4b48c6ebe60b948d251b8d2978c90d 0.5.3
+26738ea02d5384967320ef41fc743a009faf70b8 0.6.0
+dc22541876279b47dd366ddb44d262775ccdb933 0.6.1
+4a0e392be3499d9edc9cde66dd3b8d37136a0816 0.6.2

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--require doc_no_pending
+-I .

data/.ruby-version

@@ -0,0 +1 @@
+2.3.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Andrew Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,556 @@
+Introduction
+============
+
+Pod4 is not an ORM. No, really it isn't. Because that would be ridiculous.
+
+...okay, it kind of acts a _bit_ like an ORM...
+
+Ah, well. Judge for yourself. Here's a model:
+
+    class CustomerModel < Pod4::Model
+
+      class CustomerInterface < Pod4::PgInterface
+        set_table  :customer
+        set_id_fld :id
+      end
+
+      set_interface CustomerInterface.new(CONN_STRING)
+
+      attr_columns :cust_code, :name, :group
+    end
+
+And here's a method that uses the model:
+
+    def change_customer_group(id, group)
+      customer = Customer.new(id).read.or_die
+      customer.group = group
+      customer.update.or_die
+    end
+
+
+Seriously now
+-------------
+    
+Pod4 is a very simple set of classes that sits on top of some other library
+which gives access to data -- for example, pg, tds, or Sequel (which _is_ an
+ORM...) It's relatively easy to get it to talk to a new sort of data access
+library, and you're not limited to databases.
+
+It provides a simple, common framework to talk to all these data sources, using
+model classes which (to my mind at least) are clean, easy to understand and
+maintain, using a bare minimum of DSL and vanilla Ruby inheritance.
+
+This is the central motivation behind the project -- to provide a mechanism
+that allows for model classes which actually represent your data to the rest of
+your code in a way that you are fully in control of. Because it's your model
+classes, not the database, which are the canonical representation of the data.
+
+I don't want the people who maintain my code to have to know the differences
+between ActiveRecord's `update` and `update_all`, or Sequel's `dataset[]` and
+`dataset.where()`.  Pod4::Model has a dozen or so methods you need to worry
+about, and six of those are pretty much self-explanatory. Or, you can inherit
+from Pod4::BasicModel instead, and do without even that.
+
+I honestly don't think of it as an Object Relational Manager.  I think of it as
+a Way To Have Nice Models.
+
+If you are looking for something with all the features of, say, ActiveRecord,
+then this isn't for you. I provide basic access to and maintenance of records,
+with validation. For anything more, you need to be willing to use a very well
+established existing DSL within your model code -- SQL.
+
+
+Thanks
+======
+
+This code was developed, by me, during working hours at [James Hall & Co.
+Ltd](https://www.jameshall.co.uk/). I'm incredibly greatful that they have 
+permitted me to open-source it.
+
+
+Installation
+============
+
+    gem install pod4
+
+Of course you will also need to install whatever other gems you need in order
+to access the data you want Pod4 to see.  Currently there are interfaces for:
+
+* Sequel (which itself of course talks to all manner of databases)
+* Tiny_tds
+* Pg
+* Nebulous (my own STOMP wrapper/protocol/what-have-you)
+
+(But, you can add your own interfaces. It's not hard.)
+
+
+A Short Tutorial
+================
+
+Pod4 uses my Octothorpe gem to pass information around. An Octothorpe is
+basically a Hash, except the keys are always symbols, and it's read only. 
+
+But you don't really need to know that here. If you mentally substitute "Hash"
+every time I say "Octothorpe", you'll be fine.
+
+
+Model and Interface
+-------------------
+
+Note well that we distinguish between 'models' and 'interfaces':
+
+The model represents the data to your application, in the format that makes
+most sense to your application: that might be the same format that it is stored
+in on the database, or it might not. The model doesn't care about where the
+data comes from. Models are all subclasses of Pod4::Model (or Pod4::BasicModel,
+but we'll leave that alone for now).
+
+An interface encapsulates the connection to whatever is providing the data. It
+might be a wrapper for calls to the Sequel ORM, for example. Or it could be a
+making a series of calls to a set of Nebulous verbs. It only cares about
+dealing with the data source, and it is only called by the model.
+
+An interface is a seperate class, which is defined for each model. There are
+parent classes for a number of the sources you will need, but failing that,
+you can always create one from the ultimate parent, Pod4::Interface.
+
+
+Simple Model Usage
+------------------
+
+    # find record 14; raise error otherwise. Update and save.
+    x = ExampleModel.new(14).read.or_die
+    x.two = "new value"
+    x.update
+
+    # create a new record from the params hash -- unless validation fails.
+    y = ExampleModel.new
+    y.set(params)
+    y.create unless y.model_status == :error
+
+A model is a class, each instance of which represents a single record. on that
+instance you can call the following for basic operation:
+
+* `create` -- tells the data source to store this new "record"
+* `read`   -- obtains the "record" from the data source
+* `update` -- updates the "record" on the data source
+* `delete` -- deletes the "record" on the data source.
+* `set`    -- set the column attributes of the object with a hash or Octothorpe
+* `to_ot`  -- output an Octothorpe of the object's column attributes
+* `alerts` -- return an array of Alerts (which I'll explain later)
+
+(Note that we say "record" not record. The data source might not be a database.
+Your model instance might be represented on the data source as several records,
+or something else entirely.)
+
+There is one more operation - `list`. Call this on the model class itself,
+and it will return an array of model instances that match the criteria you
+pass. What you can pass to list depends on your model class (of course); by
+default it also depends on the interface the model uses. But normally it should
+except a hash, like so:
+
+    ExampleModel.list(:one => "a")  #-> Array of ExampleModel where one = "a"
+
+Additionally, you can chain `or_die` onto any model method to get it to raise
+exceptions if something is wrong on the model. If you don't want exceptions,
+you can check the model's model_status attribute, or just look at the alerts.
+
+Those eight (nine) methods are _all_ the methods given by Pod4::Model that you
+are normally going to want to use, outside of the code actually inside your
+model.
+
+
+A Simple Model
+--------------
+
+Here is the model and interface definition that goes with the above example:
+
+    require 'pod4'
+    require 'pod4/pg_interface'
+    
+    class ExampleModel < Pod4::Model
+
+      class ExampleInterface < Pod4::PgInterface
+        set_table :example
+        set_id_fld :id
+      end
+
+      set_interface ExampleInterface.new($pg_conn)
+      attr_columns :one, :two, :three
+    end
+
+In this example we have a model that relies on the Pg gem to talk to a
+table 'example'. The table has a primary key field 'id' and columns which
+correspond to our three attributes one, two and three.  There is no validation
+or error control.
+
+Note that we have to require pg_interface seperately. I won't bother to show
+this in any more model examples.
+
+### Interface ###
+
+Let's start with the interface definition.  Remember, the interface class is
+only there to represent the data source to the model. Yours will most likely be
+no more complex than the one above. Since they are only accessed by the model,
+my preference is to define them in an internal class, but if that makes you
+back away slowly waving your hands placatingly, put it in another file. Pod4 is
+fine with that.
+
+Inside your interface class you must call some DSLish methods to tell the
+interface how to talk to the data. What they are depends on the interface, but
+the ones for PgInterface are pretty common:
+
+* `set_schema` -- optional -- the name of the schema to find the table in
+* `set_table`  -- mandatory -- the name of the database table to use
+* `set_id_fld` -- mandatory -- the name of the column that makes the record unique
+
+Actually, _every_ interface defines `set_id_fld`. Instances of a model _must_ be
+represented by a single ID field that provides a unique identifier. Pod4 does
+not care what it's called or what data type it is -- if you say that's what
+makes it unique, that's good enough.
+
+Internally, Interfaces talk the same basic language of list / create / read /
+update / delete that models do. But I'm not finding the need to subclass these
+much. So that's probably going to be it for your Interface definition.
+
+### Model ###
+
+Models have two of their own DSLish methods:
+
+* `set_interface` -- here is where you instantiate your Interface class
+* `attr_columns`  -- like `attr_accessor`, but letting the model know to care.
+
+You can see that interfaces are instantiated when the model is required.
+Exactly what you need to pass to the interface to instantiate it depends on the
+interface. SequelInterface wants the Sequel DB object (which means you have to
+require sequel, connect, and *then* require your models); the other interfaces
+only want connection hashes.  
+
+Any attributes you define using `attr_columns` are treated specially by
+Pod4::Model. You get all the effect of the standard Ruby `attr_accessor` call,
+but in addition, the attribute will be passed to and from the interface, and to
+and from your external code, by the standard model methods.
+
+In addition to the ones above, we have:
+
+* `validate`         -- override this to provide validation
+* `map_to_model`     -- controls how the interface sets attributes on the model
+* `map_to_interface` -- controls how the model sends data to the interface
+* `add_alert`        -- adds an alert to the model
+
+A model also has some built-in attributes of its own:
+
+* `model_id`     -- this is the value of the ID column you set in the interface.
+* `model_status` -- one of :error :warning :okay :deleted :empty 
+
+We'll deal with all these below.
+
+
+Adding Validation
+-----------------
+
+Built into the model is an array of alerts (Pod4::Alert) which are messages
+that have been raised against the instance of the model class. Each alert can
+have a status of :error, :warning, :info or :success. If any alert has a status
+of :error :warning or :success then that is reflected in the model's
+`model_status` attribute. 
+
+(As to those other two possible statuses -- models are :empty when first created
+and :deleted after a call to delete.)
+
+You can raise alerts yourself, and you normally do so by overriding `validate`.
+This method is called after a read, and before an update create or delete, so
+that every model instance should have a model_status reflecting its
+"correctness" regardless of whether it came from the data source or your
+application.
+
+Here's a model with some validation:
+
+    class Customer < Pod4::Model
+
+      class CustomerInterface < Pod4::PgInterface
+        set_schema :pod4example
+        set_table  :customer
+        set_id_fld :id
+      end
+
+      set_interface CustomerInterface.new($pg_conn)
+      attr_columns :cust_code, :name, :group
+
+      def validate
+        super
+
+        add_alert(:error, :name, "Name cannot be empty") \
+          unless @name && @name =~ \^\s*$\
+
+        add_alert(:error, :cust_code, "invalid customer code") \
+          unless @cust_code && @cust_code.length == 6
+
+      end
+
+    end
+
+(Note: as a general principal, you should always call super when overriding a
+method in Pod4 model, unless you have good reason not to.)
+
+If the model has a status of :error, then an update or create will fail. A
+delete, however, will succeed -- if you want to create validation that aborts a
+delete operation, you should override the `delete` method and only call super
+if the validation passes.
+
+Also, because validation is not called on `set`, it's entirely possible to set
+a model to an invalid state and not raise any alerts against it until you go to
+commit to the database.  If you want to change the state of the model and then
+validate it before that, you must call `validate` by hand.
+
+
+Changing How a Model Represents Data
+------------------------------------
+
+Pod4 will do the basic work for you when it comes to data types. integers,
+decimals, dates and datatimes should all end up as the right type in the model.
+(It depends on the Interface. You're going to get tired of me saying that,
+aren't you?) But maybe you want more than that.
+
+Let's imagine you have a database table in PostreSQL with a column called cost
+that uses the money type. And you want it to be a `BigDecimal` in the model.
+Well, Pod4 won't do that for you -- for all I know someone might have a problem
+with my requiring BigDecimal -- but it's not hard to do yourself.
+
+    class Product < Pod4::Model
+
+      class ProductInterface < Pod4::PgInterface
+        set_schema :pod4example
+        set_table  :product
+        set_id_fld :product_id
+      end
+
+      set_interface ProductInterface.new($pg_conn)
+      attr_columns :description, :cost
+
+      def map_to_model(ot)
+        super
+        @cost = Bigdecimal.new(@cost)
+      end
+
+      def map_to_interface
+        super.merge(cost: @cost.to_f)
+      end
+
+    end
+
+`map_to_model` gets called when the model wants to write data from the interface
+on the model; it takes an Octothorpe from the interface as a parameter. By
+default it behaves as `set` does.
+
+`map_to_interface` is the opposite: it gets called when the model wants to write
+data on the interface from the model. It _returns_ an Octothorpe to the
+interface. By default it behaves as `to_ot` does. (Since OTs are read only, you
+must modify it using merge.)
+
+By the way: sometimes I need to validate on the data before I convert it. It's
+fine to put a call to `add_alert` in `map_to_model`.
+
+
+Relations
+---------
+
+Pod4 does not provide relations. But, I'm not sure that it needs to. Look:
+
+    class BlogPost < Pod4::Model
+
+      class BlogPostInterface < Pod4::PgInterface
+        set_table  :blogpost
+        set_id_fld :id
+      end
+
+      set_interface BlogPostInterface.new($conn)
+      attr_columns :text
+
+      def comments; Comment.list(post: @id); end
+    end
+
+
+    class Comment < Pod4::Model
+
+      class COmmentInterface < Pod4::PgInterface
+        set_table  :comment
+        set_id_fld :id
+      end
+
+      set_interface CommentInterface.new($conn)
+      attr_columns :post_id, :text
+
+      def blog_post; BlogPost.new(@post_id).read.or_die; end
+    end
+
+So the BlogPost model has a comments method that returns an array of Comments,
+and the Comments model has a blog_post method that returns the BlogPost. (You
+would probably want to add validation to enforce relational integrity.)
+
+Is this approach inefficient?  Possibly. But if you don't like it, you can
+always try:
+
+
+Beyond CRUD (& List)
+--------------------
+
+Sooner or later you will want to do something more than Pod4::Model will give
+you automatically. There is a perfectly well documented, very popular DSL with
+lots of examples to solve this problem. It's called SQL. 
+
+If your interface is connected to a SQL database, it should provide two more
+methods: `execute` and `select`.  
+
+    class BlogPost < Pod4::Model
+
+      class BlogPostInterface < Pod4::PgInterface
+        set_table  :blogpost
+        set_id_fld :id
+      end
+
+      set_interface BlogPostInterface.new($conn)
+      attr_columns :text
+
+
+      ##
+      # return an array of hashes where each comment has the post joined to it
+      #
+      def post_and_comments
+        interface.select( %Q|select *
+                               from blogpost b
+                               join comments c on(c.post_id = b.id);| )
+
+      end
+
+                              
+      ##
+      # delete all comments on this post
+      #
+      def delete_comments
+        interface.execute( 
+            %Q|delete from comments where post_id = #{@model_id};| )
+
+      end
+
+    end
+
+Neither `execute` nor `select` care about the table or ID field you passed to the
+interface. They only run pure SQL. The only difference between them is that
+select expects to return an array of results.
+
+To my way of thinking, there is absolutely nothing wrong about using SQL in a
+model. It will certainly need revisiting if you change database. But how often
+does that happen, really?  And if it ever does, you are likely to need to
+revisit the effected models anyway...
+
+
+BasicModel
+----------
+
+Sometimes your model needs to represent data in a way which is so radically
+different from the data source that the whole list, create, read, update,
+delete thing that Pod4::Model gives you is no use. Enter Pod4::BasicModel.
+
+A real world example: at James Hall my intranet system has a User model, where
+each attribute is a parameter that controls how the system behaves for that user
+-- email address, security settings, etc.  Having one object to represent the
+user is the most sensible thing.
+
+But I don't want to have to add a column to the database each time I change the
+intranet system and add a user parameter. The logical place to change the
+parameter is in the User model, not in the database, and certainly not both. So
+on the database, I have a settings table where the key runs: userid, setting
+name.
+
+Pod4::BasicModel gives you:
+
+* `set_interface`
+* the `model_id`, `model_status` and `alerts` attributes
+* `add_alert`
+
+...and nothing else. But that's enough to make a model, your way, using the
+methods on the interface. These are the same CRUDL methods that Pod4::Model
+provides -- except that the CRUD methods take a record id as a key.
+
+Here's a simplified version of my User model. This one is read only, but it's
+hopefully enough to get the idea:
+
+    class User < Pod4::BasicModel
+
+      class UserInterface < ::Pod4::SequelInterface
+        set_table :settings
+        set_id_fld :id
+      end
+
+
+      # Here we set what settings always exist for a user
+      Setting = Struct.new(:setName, :default)
+
+      DefaultSettings = [ Setting.new( :depot, nil ),
+                          Setting.new( :store, nil ),
+                          Setting.new( :menu,  nil ),
+                          Setting.new( :roles, ''  ),
+                          Setting.new( :name,  ''  ),
+                          Setting.new( :nick,  ''  ),
+                          Setting.new( :mail,  nil ) ]
+
+      set_interface UserInterface.new($db)
+      attr_reader :userid, :depot, :store, :menu, :roles, :name, :nick, :mail
+
+
+      class << self
+
+        def keys; DefaultSettings.map{|x| x.setName }; end
+
+        def list
+          array = interface.select(%Q|select distinct userid from settings;|)
+          array.map {|r| self.new( r[:userid] ).read }
+        end
+
+      end
+      ##
+      
+
+      def initialize(userid=nil)
+        super(userid)
+
+        self.class.keys.each do |key|
+          instance_variable_set( "@#{key}".to_sym, nil )
+        end
+      end
+
+
+      def read
+        lst = interface.list(userid: @model_id)
+
+        data = lst.each_with_object({}) do |ot,h| 
+          h[ot.>>.setname] = ot.>>.setvalue
+        end
+
+        @userid = @model_id
+        set_merge( Octothorpe.new(data) )
+        validate; @model_status = :okay unless @model_status != :empty
+
+        self
+      end
+
+
+      def to_ot
+        hash = self.class.keys.each_with_object({}) do |k,m| 
+          m[k] = instance_variable_get("@#{k}".to_sym)
+        end
+
+        Octothorpe.new(hash)
+      end
+
+
+      def set_merge(hash)
+        self.class.keys.each do |key|
+          value = hash[key]
+          instance_variable_set( "@#{key}".to_sym, value ) if value
+        end
+      end
+
+    end
+

data/Rakefile

@@ -0,0 +1,30 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'rdoc/task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :rdoc do
+  RDoc::Task.new do |rdoc|
+    rdoc.main = "README.md"
+    rdoc.rdoc_files.include("*.md", "lib/*", "md/*")
+    rdoc.rdoc_dir = "doc"
+  end
+
+  desc "Push doc to HARS"
+  task :hars do
+    sh "rsync -aP --delete doc/ /home/hars/hars/public/pod4"
+  end
+
+end
+
+desc "Start Guard"
+task :guard do
+  sh "bundle exec guard"
+end
+
+desc "Update vim tag data"
+task :retag do
+  sh "ripper-tags -R"
+end
+