sack 1.0.0

data/lib/sack/database/data.rb

@@ -0,0 +1,141 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'aromat'
+
+# Internal Includes
+require 'sack/database/ftypes'
+require 'sack/database/statement'
+require 'sack/database/generator'
+require 'sack/database/sanitizer'
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Data Class:
+		# Internal Class presented as Data Access Layer when yielding in Database.open.
+		class Data
+
+			# Construct:
+			# Builds a *Data* object around a _db_ instance, set to operate on _schema_.
+			# @param [SQLite3::Database] db Database instance obtained by opening an SQLite3 file
+			# @param [Hash] schema Schema definition - see README
+			def initialize db, schema
+				@db = db
+				@schema = schema
+			end
+
+			# Create Table:
+			# Creates a table _name_ defined by the _fields_ hash.
+			# @param [Symbol] name Table name
+			# @param [Hash] fields A hash mapping of field names to type definition arrays (from _FTYPES_)
+			def create_table name, fields
+				fq = fields.collect { |fname, ftype| "#{Sanitizer.field_name fname} #{ftype.respond_to?(:each) ? ftype.collect { |e| FTYPES[Sanitizer.ftype e] }.join(' ') : FTYPES[Sanitizer.ftype ftype]}" }.join ', '
+				@db.execute "create table #{Sanitizer.table @schema, name} (#{fq});"
+			end
+
+			# Count:
+			# Counts the number of rows for a given table.
+			# @param [Symbol] table Table name
+			# @return [Fixnum] The number of rows present in the given _table_
+			def count table
+				@db.execute("select count(*) from #{Sanitizer.table @schema, table};")[0][0]
+			end
+
+			# Find:
+			# Fetches the first matching row from a given _table_ by _id_.
+			def find table, id
+				fetch(table, id).try :first
+			end
+
+			# Fetch:
+			# Fetches rows from a given _table_ by _id_.
+			# @param [Symbol] table Table name
+			# @param [Object] id ID on which to filter
+			# @return [Array] An array of Hashes, each representing one row
+			def fetch table, id
+				hash_res(table.to_sym, @db.execute(Statement.prep("select * from #{Sanitizer.table @schema, table} where id = ?;", [id])))
+			end
+
+			# Fetch By Field:
+			# Fetches rows from a given _table_ where _field_ matches _val_.
+			# @param [Symbol] table Table name
+			# @param [Symbol] field Field name
+			# @param [Object] val Field value
+			# @return [Array] An array of Hashes, each representing one row
+			def fetch_by table, field, val
+				hash_res(table.to_sym, @db.execute(Statement.prep("select * from #{Sanitizer.table @schema, table} where #{Sanitizer.field @schema, table, field} = ?;", [val])))
+			end
+
+			# Fetch All:
+			# Fetches all rows from a given _table_.
+			# @param [Symbol] table Table name
+			# @return [Array] An array of Hashes, each representing one row
+			def fetch_all table
+				hash_res(table.to_sym, @db.execute("select * from #{Sanitizer.table @schema, table};"))
+			end
+
+			# Create:
+			# Inserts _fields_ as a row into a given _table_.
+			# @param [Symbol] table Table name
+			# @param [Hash] fields Fields to be inserted
+			def create table, fields
+				@db.execute Statement.prep("insert into #{Sanitizer.table @schema, table} (#{Generator.fields @schema, table, fields}) values (#{Generator.marks fields});", Generator.values(fields.values))
+			end
+
+			# Update:
+			# Updates _fields_ in rows identified by _id_ in a given _table_.
+			# @param [Symbol] table Table name
+			# @param [Object] id ID on which to filter
+			# @param [Hash] fields Fields to be updated
+			def update table, id, fields
+				@db.execute Statement.prep("update #{Sanitizer.table @schema, table} set #{Generator.update_marks @schema, table, fields} where id = ?;", [Generator.values(fields.values), id].flatten)
+			end
+
+			# Save:
+			# Creates or updates _fields_ in a given _table_, depending on the presence of an _id_.
+			# @param [Symbol] table Table name
+			# @param [Hash] fields Fields to be inserted / updated
+			def save table, fields
+				if fields[:id]
+					update table, fields.clone.delete(:id), fields
+				else
+					create table, fields
+				end
+			end
+
+			# Destroy:
+			# Removes rows identified by _id_ from a given _table_.
+			# @param [Symbol] table Table name
+			# @param [Object] id ID of rows to be removed
+			def delete table, id
+				@db.execute Statement.prep("delete from #{Sanitizer.table @schema, table} where id = ?;", [id])
+			end
+
+			# Execute statement:
+			# Generic method to execute any SQL statement.
+			# @param [String] q Statement to be executed
+			# @param [Array] params Statement parameters
+			# @return [Object] Whatever the statement returned
+			def exec q, params = []
+				@db.execute Statement.prep(q, params)
+			end
+
+			# Pull Results into Hash:
+			# Converts rows returned by SQLite3 into Hashes matching the provided schema.
+			# @param [Symbol] table Table name
+			# @param [Array] x Results returned by SQLite3
+			# @return [Array] An array of Hashes, each representing a single row
+			def hash_res table, x
+				x
+					.collect { |r| @schema[table].keys.each_with_index.inject([]) { |a, e| a + [e[0], r[e[1]]] } }
+					.collect { |r| Hash[*r] }
+					.sym_keys rescue nil
+			end
+		end
+	end
+end

data/lib/sack/database/ftypes.rb

@@ -0,0 +1,31 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Field Types:
+		# Available field types to be used when defining schemas.
+		FTYPES = {
+			str: 'VARCHAR(255)',
+			txt: 'TEXT',
+			int: 'INTEGER',
+			flo: 'REAL',
+			uniq: 'UNIQUE',
+			pk: 'PRIMARY KEY',
+			ai: 'AUTOINCREMENT'
+		}
+
+		# Ruby Type Conversions:
+		# Maps Field Types to Ruby Classes.
+		FTYPES_CLASSES = {
+			str: String,
+		    txt: String,
+		    int: Fixnum,
+		    flo: Float
+		}
+	end
+end

data/lib/sack/database/generator.rb

@@ -0,0 +1,54 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# Internal Includes
+require 'sack/database/sanitizer'
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Generator Module:
+		# Provides SQL generator methods for building queries.
+		module Generator
+
+			# Generate Field Name List:
+			# Builds a list of field names present in _field_hash_, separated by commas.
+			# @param [Hash] schema Database schema
+			# @param [Symbol] table Table name
+			# @param [Hash] field_hash Hash containing field names as keys
+			# @return [String] A comma-separated list of field names
+			def self.fields schema, table, field_hash
+				field_hash.keys.collect { |k| Sanitizer.field schema, table, k }.join ', '
+			end
+
+			# Value Marks:
+			# Builds a list of field markers ('?') for fields present in _field_hash_, separated by commas.
+			# @param [Hash] field_hash Hash containing fields
+			# @return [String] A comma-separated list of field markers ('?')
+			def self.marks field_hash
+				(['?'] * field_hash.size).join ', '
+			end
+
+			# Update Marks:
+			# Builds a list of field value markers ('field = ?') for fields present in _field_hash_, separated by commas.
+			# @param [Hash] schema Database schema
+			# @param [Symbol] table Table name
+			# @param [Hash] field_hash Hash containing field names as keys
+			# @return [String] A comma-separated list of field value markers ('field = ?')
+			def self.update_marks schema, table, field_hash
+				field_hash.keys.collect { |k| "#{Sanitizer.field schema, table, k} = ?" }.join ', '
+			end
+
+			# Values:
+			# Replaces all symbols in _vals_ by their stringified values.
+			# @param [Array] vals Array of value objects
+			# @return [Array] A copy of _vals_ where every symbol has been replaced by its string representation
+			def self.values vals
+				vals.collect { |v| v.is_a?(Symbol) ? v.to_s : v }
+			end
+		end
+	end
+end

data/lib/sack/database/model.rb

@@ -0,0 +1,108 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'aromat'
+
+# Internal Includes
+require 'sack/database/ftypes'
+require 'sack/database/sanitizer'
+require 'sack/database/model/data'
+require 'sack/database/model/validation'
+require 'sack/database/model/relationships'
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Model Module:
+		# Provides abstractions for defining database models.
+		module Model
+
+			# Included:
+			# Inject stuff when included.
+			# @param [Object] base Whatever we've been included into
+			def self.included base
+
+				# Set Model
+				base.instance_variable_set '@model', base
+
+				# Link to parent Data Model Root
+				base.instance_variable_set '@model_root', base.mod_parent
+
+				# Set Model Name
+				base.instance_variable_set '@model_name', base.mod_name
+
+				# Extend Class Methods
+				base.extend ClassMethods
+
+				# Extend with Data Access Methods
+				base.extend Data
+
+				# Include Validation
+				base.include Validation
+
+				# Include Relationships
+				base.include Relationships
+			end
+
+			# Class Methods:
+			# Collection of methods to be injected into anything that includes this module.
+			module ClassMethods
+
+				# Get / Set Table Name:
+				# Determines the default table name through introspection, or overrides the default table name (if _name_ is provided).
+				# @param [Symbol] name Override table name with this
+				# @return [Symbol] The table name
+				def table_name name = nil
+
+					# Introspect Default Name
+					@table_name ||= self.mod_name.snakecase
+
+					# Override with custom name
+					@table_name = name if name
+
+					@table_name.to_sym
+				end
+
+				# Set Field:
+				# Configures a field on the current Model.
+				# @param [Hash] options Options defining the field - see README
+				def field options
+
+					# Internalise Options (so we can mess it up)
+					options = options.clone
+
+					# Pull Name
+					name, ftype = options.first
+					options.delete name
+
+					# Check Primary Type
+					raise "Invalid Field Primary Type [#{ftype.first}] for [#{name}] in #{mod_name}" unless FTYPES_CLASSES.include? ftype.first
+
+					# Collect Validation Rules
+					@fields ||= {}
+					@fields[name] ||= {}
+					@fields[name][:ftype] = ftype
+					@fields[name][:rules] = options
+				end
+
+				# Get Fields:
+				# Simply returns the model's field map.
+				# @return [Hash] The field map for the current model
+				def fields
+					@fields
+				end
+
+				# Get Field Schema:
+				# Builds a schema for the current model.
+				# @return [Hash] The current model's schema
+				def field_schema
+					Hash[*(@fields.inject([]) { |a, e| a << e[0] << e[1][:ftype] })]
+				end
+			end
+		end
+	end
+end

data/lib/sack/database/model/data.rb

@@ -0,0 +1,66 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'aromat'
+
+# Internal Includes
+require 'sack/database'
+require 'sack/database/model/validation'
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Model Module
+		module Model
+
+			# Data Module:
+			# Provides a simple data access layer through models.
+			module Data
+
+				# Actions requiring Validation
+				VALIDATED_ACTIONS = [
+					:create,
+				    :update,
+				    :save
+				]
+
+				# Method Missing:
+				# Catches and routes model actions through database.
+				def method_missing name, *args
+
+					# Check action allowed
+					super name, *args unless ACTIONS.include? name
+
+					# Acquire Database
+					db = args.slice! 0
+
+					# Check Validation Required
+					if VALIDATED_ACTIONS.include? name
+
+						# Acquire Entity
+						data = args.last
+
+						# Pre-load for updates
+						data = data.clone.merge find(db, args.slice(0)) if name == :update
+
+						# Validate
+						errors = []
+						raise Validation::ValidationException.new "Invalid Entity [#{data}] for Model #{@model}", errors unless is_valid? db, data, errors
+					end
+
+					# Forward to Database
+					result = db.send name, table_name, *args
+
+					# Inject Model Proxy into Entity/ies
+					(result.is_a?(Array) ? result : [result]).each { |e| e.instance_variable_set('@model_mod', self); e.define_singleton_method(:method_missing) { |n, *a| @model_mod.send n, *a, self } }
+
+					result
+				end
+			end
+		end
+	end
+end

data/lib/sack/database/model/relationships.rb

@@ -0,0 +1,35 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# Internal Includes
+require 'sack/database/model/relationships/has_many'
+require 'sack/database/model/relationships/belongs_to'
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Model Module
+		module Model
+
+			# Relationships Module:
+			# Provides Model Relationships.
+			module Relationships
+
+				# Included:
+				# Inject Relationship Methods when included.
+				# @param [Object] base Whatever we've been included into
+				def self.included base
+					base.extend ClassMethods
+				end
+
+				# Class Methods:
+				# Collection of methods to be injected into anything that includes this module.
+				module ClassMethods
+				end
+			end
+		end
+	end
+end

data/lib/sack/database/model/relationships/belongs_to.rb

@@ -0,0 +1,62 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# Sack Module
+module Sack
+
+	# Database Class
+	class Database
+
+		# Model Module
+		module Model
+
+			# Relationships Module
+			module Relationships
+
+				# Class Methods
+				module ClassMethods
+
+					# Belongs To:
+					# Defines the 'slave' end of any relationship (the one that holds the other entity's ID).
+					# @param [Object] options Either a Symbol indicating both the name of the relationship and the target model, or an option Hash defining the relationship - see README
+					def belongs_to options
+
+						# Check Options
+						if options.is_a? Hash
+
+							# Internalise Options (so we can mess it up)
+							options = options.clone
+
+							# Pull Relationship Name & Target Model
+							name, target_model_name = options.first
+							options.delete name
+						else
+
+							# Acquire everything from just a Symbol
+							name = options
+							target_model_name = name
+						end
+
+						# Construct Proxy Method Module
+						proxy = Module.new do
+
+							# Proxy Method for Relationship:
+							# Allows fetching entities for a given belongs-to relationship.
+							define_method name do |db, data|
+
+								# Find Target Model
+								target_model = @model_root.const_get target_model_name.to_s.camelcase
+
+								# Fetch Relationship Entity
+								target_model.find db, data[name]
+							end
+						end
+
+						# Extend Model with Proxy
+						@model.extend proxy
+					end
+				end
+			end
+		end
+	end
+end