pod4 0.6.2

data/lib/pod4.rb

@@ -0,0 +1,54 @@
+require 'logger'
+require 'devnull'
+
+require_relative 'pod4/param'
+require_relative 'pod4/basic_model'
+require_relative 'pod4/model'
+require_relative 'pod4/alert'
+
+
+
+##
+# Pod4, which:
+#
+# * will gather data from absolutely anything. Nebulous, Sequel, Pg,
+#   TinyTds, whatever. Add your own on the fly.
+#
+# * will allow you to define models which are genuinely represent the data
+#   your way, not the way the data source sees it.
+#
+# * is hopefully simple and clean; just a very light helper layer with the
+#   absolute minimum of magic or surprises for the developer. 
+#
+# For more information:
+# 
+# * There is a short tutorial in the readme.
+#
+# * you should look at the contract Pod4 makes with its
+#   callers -- you should find all that you need in the classes Pod4::Interface
+#   and Pod4::Model. 
+#
+# * Or, read the tests, of course.
+#
+module Pod4
+
+
+  ##
+  # If you have a logger instance, set it here to have Pod4 models and
+  # interfaces write to it.
+  #
+  def self.set_logger(instance)
+    Param.set(:logger, instance)
+  end
+
+
+  ##
+  # Return a logger instance if you set one using set_logger.
+  # Otherwise, return a logger instance that points to a DevNull IO object.
+  #
+  def self.logger
+    Param.get(:logger) || Logger.new( DevNull.new )
+  end
+
+
+end

data/md/fixme.md

@@ -0,0 +1,32 @@
+Things I Wish I Could Do
+========================
+
+* TinyTds gem fails to cast date fields as date. Nothing we can do about that,
+  AFAICS.
+
+* PG gem raises lots of "please cast this type explicitly" warnings for money,
+  numeric types. There is no documentation for how to do this, and apparently
+  no-one knows how /O\
+
+
+Things To Do
+============
+
+* I had a note here on how SequelInterface does not support the table and
+  quoted_table variables. Well, these definitely aren't part of the contract:
+  how would NebulousInterface support them? But there might be an issue with
+  passing selection parameters to SequelInterface.list if the schema is set. We
+  need to tie down a test for that and fix it if it exists.
+
+* PgInterface works pretty well for the PG gem, but not the pg_jruby gem. We
+  need to take a rather more paranoid approach to the thing; how we go about
+  adding test coverage for this I have literally no idea...
+
+* TinyTDS just updated to 1.0 and ... fell over.  We need to work out what's
+  going on there.
+
+* Ideally interfaces should support parameterised insertion. Ideally in a
+  manner consistent for all interfaces...
+
+* We should have a test suite for jRuby.
+

data/md/roadmap.md

@@ -0,0 +1,69 @@
+Connection Object
+=================
+
+PgInterface and TdsInterface both take a connection Hash, which is all very
+well, but it means that we are running one database connection per model.
+Presumably this is a bad idea. :-)
+
+This actually hasn't come up in my own use of Pod4 -- for complex reasons I'm
+either using SequelInterface or running transient jobs which start up a couple
+of models, do some work, and then stop entirely -- but it _is_ rather silly.
+
+Connection is baked into those interfaces, and interface dependant. So I'm
+thinking in terms of a memoising object that stores the connection hash and
+then gets passed to the interface. When the interface wants a connection, then
+it asks the connection object. If the connection object doesn't have one, then
+the interface connects, and gives the connection to the connection object.
+
+
+Transactions
+============
+
+We really need this, because without it we can't even pretend to be doing
+proper pessimistic locking.
+
+I've got a pretty solid idea for a nice, simple way to make this happen. It
+will be in place soon.
+
+
+Migrations
+==========
+
+This will almost certainly be something crude -- since we don't really control
+the database connection in the same way as, say, ActiveRecord -- but I honestly
+think it's a worthwhile feature.  Just having something that you can version
+control and run to update a data model is enough, really.
+
+I'm not yet sure of the least useless way to implement it.  Again, I favour SQL
+as the DSL.
+
+
+JDBC-SQL interface
+==================
+
+For the jdbc-msssqlserver gem.  Doable ... I *think*.
+
+    driver = Java::com.microsoft.sqlserver.jdbc.SQLServerDriver.new
+    props = java.util.Properties.new
+    props.setProperty("user", "username")
+    props.setProperty("password", "password")
+    url = 'jdbc:sqlserver://servername;instanceName=instance;databaseName=DbName;'
+
+    conn = driver.connect(url, props)
+    #or maybe conn = driver.get_connection(url, "username", "password")
+
+    stmt = conn.create_statement
+    sql = %Q|blah;|
+
+    rsS = stmt.execute_query(sql)
+
+    while (rsS.next) do
+      veg = Hash.new
+      veg["vegName"] = rsS.getObject("name")
+      # etc
+    end
+
+    stmt.close
+    conn.close
+
+    see https://github.com/jruby/jruby/wiki/JDBC

data/pod4.gemspec

@@ -0,0 +1,49 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pod4/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "pod4"
+  spec.version       = Pod4::VERSION
+  spec.authors       = ["Andy Jones"]
+  spec.email         = ["andy.jones@twosticksconsulting.co.uk"]
+  spec.summary       = %q|Totally not an ORM|
+  spec.description   = <<~DESC
+    Provides a simple, common framework to talk to a bunch of data sources,
+    using model classes which consist of a bare minimum of DSL plus vanilla Ruby
+    inheritance.
+  DESC
+
+  spec.homepage      = "https://bitbucket.org/andy-twosticks/pod4"
+  spec.license       = "MIT"
+
+  spec.files         = `hg status -macn0`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.extra_rdoc_files = spec.files.grep(%r{^md/})
+
+  spec.add_runtime_dependency "devnull",    '~>0.1'
+  spec.add_runtime_dependency "octothorpe", '~>0.1'
+
+  # for bundler, management, etc etc
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake",    "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rdoc"
+  
+  # For testing
+  spec.add_development_dependency "sequel"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "tiny_tds"
+  spec.add_development_dependency "pg"
+  spec.add_development_dependency "nebulous"
+
+  # Development tools
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-doc"
+  spec.add_development_dependency "ripper-tags"
+  spec.add_development_dependency "geminabox"
+
+end

data/spec/README.md

@@ -0,0 +1,19 @@
+Some Notes On Testing
+=====================
+
+Some of the interface tests require an actual database to run.  
+
+If you want to run the whole test suite you will have to configure
+spec/fixtures/database.yaml so that you can connect to both an SQL Server
+database and a Postgres database.  
+
+In each case the database name you need to use is hardcoded: pod4_test. (Pod4
+assumes that the schema names can be hardcoded, and since we create and wipe
+tables in these tests, you should really have a seperate database for them
+anyway.)
+
+Sequel
+------
+Note that the Sequel ORM adapter does **not** require a database -- we
+currently use an in-memory sqlite database instead.
+

data/spec/alert_spec.rb

@@ -0,0 +1,173 @@
+require 'pod4/alert'
+
+
+describe Alert do
+
+  let(:err) { StandardError.new('whoa') }
+
+
+  describe '#new' do
+
+    it 'requires a type of error, warning, info or success; and a message' do
+      expect{ Alert.new        }.to raise_exception ArgumentError
+      expect{ Alert.new(nil)   }.to raise_exception ArgumentError
+      expect{ Alert.new('foo') }.to raise_exception ArgumentError
+      
+      [:baz, :werning, nil, :note, :debug].each do |badType|
+        expect{ Alert.new(badType, 'foo') }.
+          to raise_exception(ArgumentError), "Alert.new(#{badType.inspect}...)"
+
+      end
+
+      [:error, :warning, :info, 'success', 'error'].each do |type|
+        expect{ Alert.new(type, 'foo') }.
+          not_to raise_exception, "Alert.new(#{type.inspect}...)"
+
+      end
+
+    end
+
+    it 'allows the message to be a string' do
+      expect{ Alert.new(:warning, 'foo') }.not_to raise_exception
+    end
+
+    it 'allows the message to be an exception' do
+      expect{ Alert.new(:error, err) }.not_to raise_exception
+    end
+
+    it 'allows entry of a field name' do
+      expect{ Alert.new(:success, 'foo', 'bar') }.not_to raise_exception
+    end
+
+  end
+  ##
+
+  
+  describe '#type' do
+
+    it 'reflects the type passed to #new' do
+      expect( Alert.new(:info, 'foo').type  ).to eq :info
+      expect( Alert.new('info', 'foo').type ).to eq :info
+    end
+
+  end
+  ##
+
+
+  describe '#message' do
+
+    let(:al1) { Alert.new(:info, 'foo') }
+    let(:al2) { Alert.new(:info, err)   }
+
+    it 'reflects the message passed to #new' do
+      expect( al1.message ).to eq 'foo'
+      expect( al2.message ).to eq 'whoa'
+    end
+
+    it 'allows you to change it' do
+      al1.message = "one"; al2.message = "two"
+
+      expect( al1.message ).to eq 'one'
+      expect( al2.message ).to eq 'two'
+    end
+
+  end
+  ##
+
+
+  describe '#field' do
+
+    it 'defaults to nil' do
+      expect( Alert.new(:error, 'baz').field ).to be_nil
+    end
+
+    it 'reflects the field passed to #new' do
+      expect( Alert.new(:info, 'fld1', 'foo').field ).to eq :fld1
+    end
+
+    it 'allows you to change it' do
+      al = Alert.new(:success, :boris, 'foo')
+      al.field = :yuri
+
+      expect( al.field ).to eq :yuri
+    end
+
+  end
+  ##
+
+
+  describe '#exception' do
+
+    it 'defaults to nil' do
+      expect( Alert.new('warning', 'one').exception ).to be_nil
+    end
+
+    it 'reflects the exception passed to #new' do
+      expect( Alert.new(:info, err).exception ).to eq err
+    end
+
+  end
+  ##
+
+
+  describe '#log' do
+
+    after do
+      Pod4::Param.reset
+    end
+
+    let(:alert_error)   { Alert.new(:error, 'error')     }
+    let(:alert_warning) { Alert.new(:warning, 'warning') }
+    let(:alert_info)    { Alert.new(:info, 'info')       }
+    let(:alert_success) { Alert.new(:success, 'success') }
+
+    it 'accepts a context field' do
+      expect{ alert_warning.log           }.not_to raise_exception
+      expect{ alert_warning.log('foo')    }.not_to raise_exception
+      expect{ alert_warning.log('foo', 2) }.to  raise_exception ArgumentError
+    end
+
+    it 'outputs itself to the log, at the right level' do
+      lugger = double(Logger)
+      Pod4.set_logger lugger
+
+      expect(lugger).to receive(:error)
+      alert_error.log
+
+      expect(lugger).to receive(:warn)
+      alert_warning.log
+
+      expect(lugger).to receive(:info)
+      alert_info.log
+
+      expect(lugger).to receive(:info)
+      alert_success.log
+    end
+
+    it 'returns self' do
+      expect( alert_error.log ).to eq alert_error
+    end
+
+  end
+  ##
+
+
+  context 'when collected in an array' do
+
+    it 'orders itself by severity of type' do
+      arr = []
+      arr << Alert.new(:warning, 'one')
+      arr << Alert.new(:error,   'two')
+      arr << Alert.new(:info,    'three')
+      arr << Alert.new(:success, 'four')
+
+      expect( arr.sort.map{|a| a.type } ).
+        to eq([:error,:warning,:info,:success])
+
+    end
+
+  end
+  ##
+
+end
+

data/spec/basic_model_spec.rb

@@ -0,0 +1,220 @@
+require 'octothorpe'
+
+require 'pod4/basic_model'
+require 'pod4/null_interface'
+
+
+##
+# We define a model class to test, since in normal operation we would never use
+# Model directly, and since it needs an inner Interface.
+#
+# We can't use a mock for the interface -- class definitions fall outside the
+# RSpec DSL as far as I can tell, so I can neither create a mock here or inject
+# it. Which means we can't mock the interface in the rest of the test either;
+# any mock we created would not get called.
+#
+# But: we want to test that Model calls Interface correctly.
+#
+# We do have what appears to be a perfectly sane way of testing. We can define
+# an inner class based on the genuinely existing, non-mock NullInterface class;
+# and then define expectations on it. When we do this, Rspec fails to pass the
+# call on to the object, unless we specifically say `.and_call_original`
+# instead of `.and_return`. 
+#
+# This is actually quite nice, but more than a little confusing when you see it
+# for the first time. Its use isn't spelled out in the RSpec docs AFAICS. 
+#
+class WeirdModel < Pod4::BasicModel
+  set_interface NullInterface.new(:id, :name, :price, :groups, [])
+
+  def fake_an_alert(*args)
+    add_alert(*args) #protected method
+  end
+
+  def reset_alerts; @alerts = []; end
+end
+
+
+
+describe 'WeirdModel' do
+  let(:model) { WeirdModel.new(20) }
+
+
+  describe 'Model.set_interface' do
+    it 'requires an Interface object' do
+      expect( WeirdModel ).to respond_to(:set_interface).with(1).argument
+    end
+
+    # it 'sets interface' - covered by the interface test
+  end
+  ##
+
+  
+  describe 'Model.interface' do
+    it 'is the interface object' do
+      expect( WeirdModel.interface ).to be_a_kind_of NullInterface
+      expect( WeirdModel.interface.id_fld ).to eq :id
+    end
+  end
+  ##
+
+
+  describe '#new' do
+
+    it 'takes an optional ID' do
+      expect{ WeirdModel.new    }.not_to raise_exception
+      expect{ WeirdModel.new(1) }.not_to raise_exception
+    end
+
+    it 'sets the ID attribute' do
+      expect( WeirdModel.new(23).model_id ).to eq 23
+    end
+
+    it 'sets the status to empty' do
+      expect( WeirdModel.new.model_status ).to eq :empty
+    end
+
+    it 'initializes the alerts attribute' do
+      expect( WeirdModel.new.alerts ).to eq([])
+    end
+
+  end
+  ##
+
+
+  describe '#interface' do
+    it 'returns the interface set in the class definition, again' do
+      expect( WeirdModel.new.interface ).to be_a_kind_of NullInterface
+      expect( WeirdModel.new.interface.id_fld ).to eq :id
+    end
+  end
+  ##
+
+
+  describe '#alerts' do
+    it 'returns the list of alerts against the model' do
+      cm = WeirdModel.new
+      cm.fake_an_alert(:warning, :foo, 'one')
+      cm.fake_an_alert(:error,   :bar, 'two')
+
+      expect( cm.alerts.size ).to eq 2
+      expect( cm.alerts.map{|a| a.message} ).to match_array(%w|one two|)
+    end
+  end
+  ##
+
+
+  describe '#add_alert' do
+    # add_alert is a protected method, which is only supposed to be called
+    # within the validate method of a subclass of Method. So we test it by
+    # calling our alert faking method
+
+    it 'requires type, message or type, field, message' do
+      expect{ model.fake_an_alert        }.to raise_exception ArgumentError
+      expect{ model.fake_an_alert(nil)   }.to raise_exception ArgumentError
+      expect{ model.fake_an_alert('foo') }.to raise_exception ArgumentError
+
+      expect{ model.fake_an_alert(:error, 'foo') }.not_to raise_exception
+      expect{ model.fake_an_alert(:warning, :name, 'bar') }.
+        not_to raise_exception
+
+    end
+
+    it 'only allows valid types' do
+      [:brian, :werning, nil, :alert, :danger].each do |l|
+        expect{ model.fake_an_alert(l, 'foo') }.to raise_exception ArgumentError
+      end
+
+      [:warning, :error, :success, :info].each do |l|
+        expect{ model.fake_an_alert(l, 'foo') }.not_to raise_exception
+      end
+
+    end
+
+    it 'creates an Alert and adds it to @alerts' do
+      lurch = 'Dnhhhhhh'
+      model.fake_an_alert(:error, :price, lurch)
+
+      expect( model.alerts.size ).to eq 1
+      expect( model.alerts.first ).to be_a_kind_of Pod4::Alert
+      expect( model.alerts.first.message ).to eq lurch
+    end
+
+    it 'sets @model_status if the type is worse than @model_status' do
+      model.fake_an_alert(:warning, :price, 'xoo')
+      expect( model.model_status ).to eq :warning
+
+      model.fake_an_alert(:success, :price, 'flom')
+      expect( model.model_status ).to eq :warning
+
+      model.fake_an_alert(:info, :price, 'flom')
+      expect( model.model_status ).to eq :warning
+
+      model.fake_an_alert(:error, :price, 'qar')
+      expect( model.model_status ).to eq :error
+
+      model.fake_an_alert(:warning, :price, 'drazq')
+      expect( model.model_status ).to eq :error
+    end
+
+    it 'ignores a new alert if identical to an existing one' do
+      lurch = 'Dnhhhhhh'
+      2.times { model.fake_an_alert(:error, :price, lurch) }
+
+      expect( model.alerts.size ).to eq 1
+    end
+
+  end
+  ##
+
+
+  describe '#clear_alerts' do
+    before do
+      model.fake_an_alert(:error, "bad stuff")
+      model.clear_alerts
+    end
+
+    it 'resets the @alerts array' do
+      expect( model.alerts ).to eq([])
+    end
+
+    it 'sets model_status to :okay' do
+      expect( model.model_status ).to eq :okay
+    end
+
+
+  end
+  ##
+
+
+  describe '#raise_exceptions' do
+
+    it 'is also known as .or_die' do
+      cm = WeirdModel.new
+      expect( cm.method(:raise_exceptions) ).to eq( cm.method(:or_die) )
+    end
+
+    it 'raises ValidationError if model status is :error' do
+      model.fake_an_alert(:error, :price, 'qar')
+      expect{ model.raise_exceptions }.to raise_exception Pod4::ValidationError
+    end
+
+    it 'does nothing if model status is not :error' do
+      expect{ model.raise_exceptions }.not_to raise_exception
+
+      model.fake_an_alert(:info, :price, 'qar')
+      expect{ model.raise_exceptions }.not_to raise_exception
+
+      model.fake_an_alert(:success, :price, 'qar')
+      expect{ model.raise_exceptions }.not_to raise_exception
+
+      model.fake_an_alert(:warning, :price, 'qar')
+      expect{ model.raise_exceptions }.not_to raise_exception
+    end
+
+  end
+  ##
+
+
+end
+

data/spec/doc_no_pending.rb

@@ -0,0 +1,5 @@
+class DocNoPending < RSpec::Core::Formatters::DocumentationFormatter
+  RSpec::Core::Formatters.register self, :example_pending
+
+  def example_pending(notifications); end
+end

data/spec/fixtures/database.rb

@@ -0,0 +1,13 @@
+DB = {} 
+
+DB[:tds] =
+  { dataserver: 'SQLDEV',
+    username:   'pod4test',
+    password:   'pod4test' }
+
+DB[:pg] = 
+  { host:     'centos7andy',
+    dbname:   'pod4_test',
+    user:     'pod4test',
+    password: 'pod4test' }
+