og 0.5.0

data/lib/glue/string.rb

@@ -0,0 +1,224 @@
+# code: 
+# * George Moschovitis  <gm@navel.gr>
+# * Anastasios Koutoumanos  <ak@navel.gr>
+# * Elias Karakoulakis  <ekarak@ktismata.com>
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: string.rb 165 2004-11-18 12:04:04Z gmosx $
+
+require "uri"
+
+module G;
+
+# = StringUtils
+#
+# General string utilities collection.
+#
+# === Design:
+#
+# Implement as a module to avoid class polution. You can
+# still Ruby's advanced features to include the module in your
+# class. Passing the object to act upon allows to check for nil,
+# which isn't possible if you use self.
+#
+# === TODO:
+#
+# - implement a method that returns easy to remember
+#   pseudo-random strings
+# - add aliases for those methods in Kernel.
+#
+module StringUtils
+
+	@@map_to_greeklish = {
+		"�" => "a", "�" => "A", "�" => "a", "�" => "A",
+		"�" => "b", "�" => "B",
+		"�" => "g", "�" => "G",
+		"�" => "d", "�" => "D",
+		"�" => "e", "�" => "E", "�" => "e", "�" => "E",
+		"�" => "z", "�" => "Z",
+		"�" => "h", "�" => "H", "�" => "h", "�" => "H",
+		"�" => "8", "�" => "8",
+		"�" => "i", "�" => "I", "�" => "i", "�" => "I",
+		"�" => "k", "�" => "K",
+		"�" => "l", "�" => "L",
+		"�" => "m", "�" => "M",
+		"�" => "n", "�" => "N",
+		"�" => "3", "�" => "3",
+		"�" => "o", "�" => "O", "�" => "o", "�" => "O",
+		"�" => "p", "�" => "P",
+		"�" => "r", "�" => "R",
+		"�" => "s", "�" => "s", "�" => "S",
+		"�" => "t", "�" => "T",
+		"�" => "y", "�" => "Y", "�" => "y", "�" => "Y",
+		"�" => "f", "�" => "F",
+		"�" => "x", "�" => "X",
+		"�" => "ps","�" => "PS",
+		"�" => "w", "�" => "W", "�" => "w", "�"=>"W"
+	}
+
+	# Convert the input string to greeklish.
+	#--
+	# gmosx, TODO: remove from public distribution
+	#++
+	#
+	def self.to_greeklish(input)
+		return nil unless input
+		output = ""
+		# gmosx: also parse new lines
+		input.scan(/./m) { |w|
+			c = @@map_to_greeklish[w]
+			output << (c.nil?? w: c)
+		}
+		return output
+	end
+
+	# Move this in String class?
+	#
+	# Tests a string for a valid value (non nil, not empty)
+	#
+	def self.valid?(string)
+		return (not ((nil == string) or (string.empty?)))
+	end
+
+	# returns short abstract of long strings (first 'count'
+	# characters, chopped at the nearest word, appended by '...')
+	# force_cutoff: break forcibly at 'count' chars. Does not accept
+	# count < 2.
+	#
+	def self.head(string, count = 128, force_cutoff = false, ellipsis="...")
+		return nil unless string
+		return nil if count < 2
+
+		if string.size > count
+			cut_at = force_cutoff ? count : (string.index(' ', count-1) || count)
+			xstring = string.slice(0, cut_at)
+			return xstring.chomp(" ") + ellipsis
+		else
+			return string
+		end
+	end
+
+	# Apply a set of rules (regular expression matches) to the
+	# string
+	#
+	# === Requirements:
+	# - the rules must be applied in order! So we cannot use a
+	#   hash because the ordering is not guaranteed! we use an
+	#	array instead.
+	#
+	# === Input:
+	# the string to rewrite
+	# the array containing rule-pairs (match, rewrite)
+	#
+	# === Output:
+	# the rewritten string
+
+	MATCH = 0
+	REWRITE = 1
+
+	def self.rewrite(string, rules)
+		return nil unless string
+
+		# gmosx: helps to find bugs
+		raise ArgumentError.new("the rules parameter is nil") unless rules
+
+		rewritten_string = string.dup
+
+		for rule in rules
+			rewritten_string.gsub!(rule[MATCH], rule[REWRITE])
+		end
+
+		return (rewritten_string or string)
+	end
+
+	# Enforces a maximum width of a string inside an
+	# html container. If the string exceeds this maximum width
+	# the string gets wraped.
+	#
+	# Not really useful, better use the CSS overflow: hidden
+	# functionality.
+	#
+	# === Input:
+	# the string to be wrapped
+	# the enforced width
+	# the separator used for wrapping
+	#
+	# === Output:
+	# the wrapped string
+	#
+	# === Example:
+	#  text = "1111111111111111111111111111111111111111111"
+	#  text = wrap(text, 10, " ")
+	#  p text # => "1111111111 1111111111 1111111111"
+	#
+	# See the test cases to better understand the behaviour!
+	#
+	def self.wrap(string, width = 20, separator = " ")
+		return nil unless string
+
+		re = /([^#{separator}]{1,#{width}})/
+		wrapped_string = string.scan(re).join(separator)
+
+		return wrapped_string
+	end
+
+	# Replace dangerours chars in filenames
+	#
+	def self.rationalize_filename(filename)
+		return nil unless filename
+		# gmosx: rationalize a copy!!! (add unit test)
+		xfilename = filename.dup()
+		# gmosx: replace some dangerous chars!
+		xfilename.gsub!(/ /, "-")
+		xfilename.gsub!(/!/, "")
+		xfilename.gsub!(/'/, "")
+		xfilename.gsub!(/\(/, "")
+		xfilename.gsub!(/\)/, "")
+		xfilename = self.to_greeklish(xfilename)
+		return xfilename
+	end
+
+	# Returns a random string. one possible use is
+	# password initialization.
+	#
+	# === Input:
+	# the maximum length of the string
+	#
+	# === Output:
+	# the random string
+	#
+	def self.random(max_length = 8, char_re = /[\w\d]/)
+    # gmosx: this is a nice example of input parameter checking.
+		# this is NOT a real time called method so we can add this
+		# check. Congrats to the author.
+		raise ArgumentError.new("char_re must be a regular expression!") unless char_re.is_a?(Regexp)
+		
+		string = ""
+
+		while string.length < max_length
+				ch = rand(255).chr
+				string << ch if ch =~ char_re
+		end
+
+		return string
+	end
+
+	# Screen an IP address
+	#--
+	# gmosx: copied this method from n1, check how it works!
+	# probably deprecate?
+	#++
+	def self.screen_ip_address(address)
+		if address
+			return address.split(',').collect { |hostip|
+				hostip.gsub(/\.[^\.]*$/, ".*")
+			}.join(', ')
+		else
+			return "*.*.*.*"
+		end
+	end
+	
+end
+
+end # module
+

data/lib/glue/time.rb

@@ -0,0 +1,93 @@
+# code: 
+# * George Moschovitis  <gm@navel.gr>
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: time.rb 167 2004-11-23 14:03:10Z gmosx $
+
+require "time.rb"
+
+module G;
+
+# = Time
+#
+# General time utilities collection
+#
+# === Design:
+#
+# Implement as a module to avoid class polution. You can
+# still Ruby's advanced features to include the module in your
+# class. Passing the object to act upon allows to check for nil,
+# which isn't possible if you use self.
+#
+# === TODO:
+#
+# - SOS: add test units.
+# - add aliases for those methods in Kernel ?
+#
+module TimeUtils
+
+	NOW = Time.now
+	NEVER = Time.mktime(2038)
+	ZERO = Time.mktime(1972)
+
+	# Convert the time to a nice String representation. 
+	#	
+	def self.date_time(time)
+		return nil unless time 
+		return time.strftime("%d-%m-%Y %H:%M")
+	end
+	
+	# this method calculates the days extrema given two time objects.
+	# start time is the given time1 at 00:00:00
+	# end time is the given time2 at 23:59:59:999
+	#
+	# Input:
+	# - the two times (if only time1 is provided then you get an extrema
+	#   of exactly one day extrema.
+	#
+	# Output
+	# - the time range. you can get the start/end times using
+	#   range methods.
+	#
+	def self.days_extrema(time1, time2=nil)
+		time2 = time1 if (not time2.valid? Time)
+		time2 = NEVER if (time2 <= time1)
+		start_time = Time.self.start_of_day(time1)
+		end_time = self.end_of_day(time2)
+		return (start_time..end_time)
+	end
+
+	#
+	# set time to start of day
+	#
+	def self.start_of_day(time)
+		return Time.mktime(time.year, time.month, time.day, 0, 0, 0, 0)
+	end
+
+	#
+	# set time to end of day
+	#
+	def self.end_of_day(time)
+		return Time.mktime(time.year, time.month, time.day, 23, 59, 59, 999)
+	end
+
+
+	# returns true only if day of time is included in the
+	# range (stime..etime). Only year days are checked.
+	#
+	def self.time_in_day_range(time, stime=ZERO, etime=NEVER)
+		if (etime <= stime)
+			$log.debug "Invalid end time (#{etime} < #{stime})" if $DBG
+			etime = NEVER
+		end
+
+		stime = start_of_day(stime)
+		etime = end_of_day(etime)
+
+		return (stime..etime).include?(time)
+	end
+
+end
+
+end # module
+

data/lib/og.rb

@@ -0,0 +1,411 @@
+# code:
+# * George Moschovitis  <gm@navel.gr>
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: og.rb 167 2004-11-23 14:03:10Z gmosx $
+
+require "glue/property"
+require "glue/array"
+require "glue/hash"
+require "glue/time"
+require "glue/pool"
+
+require "og/meta"
+
+# = Og
+#
+# Og (ObjectGraph) is an efficient, yet simple Object-Relational 
+# mapping library. 
+#
+# == Features
+#
+# The library provides the following features:
+#
+# + Object-Relational mapping.
+# + Absolutely no configuration files.
+# + Multiple backends (PostgreSQL, MySQL).
+# + ActiveRecord-style meta language and db aware methods.
+# + Deserialize to Ruby Objects or ResultSets.
+# + Deserialize sql join queries to Ruby Objects.
+# + Serialize arbitrary ruby object graphs through YAML.
+# + Connection pooling.
+# + Thread safety.
+# + SQL transactions.
+# + Lifecycle callbacks.
+# + Transparent support for cascading deletes for all backends.
+# + Hierarchical structures (preorder traversal, materialized paths)
+# + Works safely as part of distributed application.
+# + Simple implementation < 2k lines of code.
+#
+# === Meta language
+#
+# primary_key :pid
+# prop_accessor Fixnum, :pid, :sql => "smallint DEFAULT 1"
+# has_many Child, :children
+# many_to_many Role, :roles
+# sql_index :pid
+#
+# === Design
+#
+# Keep the main classes backend agnostic. 
+#
+# Try to make the methods work with oids. Do NOT implement descendants 
+# use a root id (rid).
+#
+# For class ids we use the name instead of a hash. Class ids are
+# typically not used in querys, they are stored for completeness.
+# If we store a hash we cannot reclaim the class thus invalidating
+# the point. Instead of .name(), to_s() is used so the methods
+# are more flexible (they accept class names too!!)
+#
+# Og allows the serialization of arbitrary Ruby objects. Just
+# mark them as Object (or Array or Hash) in the prop_accessor
+# and the engine will serialize a YAML dump of the object.
+# Arbitrary object graphs are supported too.
+#
+# This is NOT a singleton, an application may access multiple
+# databases.
+#
+# The $og.xxx methods are more flexible and allow you to use
+# multiple databases for example.
+# 
+# === Managed Objects Lifecycle Callbacks
+#
+# * og_pre_insert
+# * og_post_insert
+#	* og_pre_update
+# * og_post_update
+# * og_pre_insert_update
+# * og_post_insert_update
+# * self.og_pre_delete
+# * validate
+#
+# A class level callback is used for delete because typically you call
+# delete with an oid and not an object to avoid a deserialization.
+#
+# === Future 
+# 
+# * Support prepared statements (pgsql)
+# * Support stored procedures (pgsql)
+# * Support caching.
+# * Deserialize to OpenStruct.
+# * Better documentation.
+#
+module Og
+
+# If true, only allow reading from the database. Usefull
+# for maintainance.
+#
+$og_read_only_mode = false
+
+# If true, the library automatically 'enchants' managed classes.
+# In enchant mode, special db aware methods are added to 
+# managed classes and instances.
+#
+$og_enchant_managed_classes = true
+
+# If true, use Ruby's advanced introspection capabilities to 
+# automatically manage classes tha define properties.
+$og_auto_manage_classes = true
+
+# = Unmanageable
+#
+# Marker module. If included this in a class, the Og automanager
+# ignores this class.
+#
+module Unmanageable; end
+
+# = Database
+#
+# Encapsulates an Og Database.
+#
+class Database
+
+	# Managed class metadata
+	#
+	class ManagedClassMeta
+		# The managed class.
+		attr_accessor :klass
+		
+		# A mapping of the database fields to the object properties.
+		attr_accessor :field_index
+		
+		def initialize(klass = nil)
+			@klass = klass
+			@field_index = {}
+		end
+	end
+
+	# hash of configuration options.
+	attr_accessor :config
+
+	# Pool of connections to the backend.
+	attr_accessor :connection_pool
+
+	# Managed classes.
+	attr_accessor :managed_classes
+
+	# Initialize the database interface.
+	#
+	def initialize(config)
+		@config = config
+
+		# populate with default options if needed.
+		@config[:connection_count] ||= 1
+		
+		# require the backend.		
+		backend = @config[:backend] || "psql"
+		require "og/backends/#{backend}"
+		eval %{	@config[:backend] = #{backend.capitalize}Backend }
+		
+		@connection_pool = G::Pool.new
+		@managed_classes = G::SafeHash.new
+		
+		$log.info "Connecting to database '#{@config[:database]}' using backend '#{backend}'."
+		
+		@config[:connection_count].times do
+			@connection_pool << Og::Connection.new(self)
+		end
+		
+		if $og_auto_manage_classes
+			# automatically manage classes with properties and metadata.
+			# gmosx: Any idea how to optimize this?
+			classes_to_manage = []
+			ObjectSpace.each_object(Class) do |c|
+				if c.respond_to?(:__props) and c.__props
+					classes_to_manage << c
+				end
+			end
+			$log.info "Og auto manages the following classes:"
+			$log.info "#{classes_to_manage.inspect}"
+			manage_classes(*classes_to_manage)
+		end
+	end
+		
+	# Shutdown the database interface.
+	#
+	def shutdown
+		for con in @connection_pool
+			con.close()
+		end
+	end
+	alias_method :close, :shutdown
+
+	# Get a connection from the pool to access the database.
+	# Stores the connection in a thread-local variable.
+	#
+	def get_connection
+		$log.debug "Get Og connection" if $DBG
+		
+		thread = Thread.current
+		
+		unless conn = thread[:og_conn]
+			conn = @connection_pool.pop()
+			thread[:og_conn] = conn
+		end
+		
+		return conn
+	end
+	
+	# Restore an unused connection to the pool.
+	#
+	def put_connection
+		$log.debug "Put Og connection" if $DBG
+
+		thread = Thread.current
+		
+		if conn = thread[:og_conn]
+			thread[:og_conn] = nil
+			return @connection_pool.push(conn)
+		end
+	end	
+	
+	# Utility method, automatically restores a connection to the pool.
+	#
+	def connect(deserialize = nil, &block)
+		result = nil
+		
+		begin
+			conn = get_connection()
+			conn.deserialize = deserialize unless deserialize.nil?
+			
+			result = yield(conn)
+			
+			conn.deserialize = true
+		ensure
+			put_connection()
+		end
+
+		return result
+	end
+	alias_method :open, :connect
+	
+	
+	# Register a standard Ruby class as managed.
+	#
+	def manage(klass)
+		return if managed?(klass) or klass.ancestors.include?(Og::Unmanageable)
+		
+		@managed_classes[klass] = ManagedClassMeta.new(klass)
+		
+		# Add standard og methods to the class.
+		convert(klass)
+		
+		# Add helper methods to the class.
+		enchant(klass) if $og_enchant_managed_classes 
+	end
+	
+	# Helper method to set multiple managed classes.
+	#
+	def manage_classes(*klasses)
+		for klass in klasses
+			manage(klass)
+		end
+	end
+	
+	# Stop managing a Ruby class
+	#
+	def unmanage(klass)
+		@managed_classes.delete(klass)
+	end
+	
+	# Is this class managed?
+	#	
+	def managed?(klass)
+		return @managed_classes.include?(klass)
+	end
+	
+	# Add standard og functionality to the class
+	#
+	def convert(klass)
+		# gmosx: this check is needed to allow the developer to customize
+		# the sql generated for oid
+		Og::Utils.eval_og_oid(klass) unless klass.instance_methods.include?(:oid)
+		
+		klass.class_eval %{
+			inherit_meta(superclass) if superclass
+			
+			DBTABLE = "#{Og::Utils.table(klass)}"
+			DBSEQ = "#{Og::Utils.table(klass)}_oids_seq" 
+			
+			def to_i()
+				@oid
+			end			
+		}
+
+		# Create the schema for this class if not available.
+		create_table(klass)				
+
+		# Precompile some code that gets executed all the time.
+		# Deletion code is not precompiled, because it is not used
+		# as frequently.
+		Og::Utils.eval_og_insert(klass)
+		Og::Utils.eval_og_update(klass)
+		Og::Utils.eval_og_deserialize(klass, self)
+	end
+	
+	# Enchant a managed class. Add useful DB related methods to the 
+	# class and its instances. 
+	#
+	def enchant(klass)
+		klass.class_eval %{
+			def self.save(obj)
+				$og << obj
+			end
+			
+			def self.load(oid_or_name)
+				$og.load(oid_or_name, #{klass})
+			end
+
+			def self.[](oid_or_name)
+				$og.load(oid_or_name, #{klass})
+			end
+			
+			def self.load_all(extra_sql = nil)
+				$og.load_all(#{klass}, extra_sql)
+			end
+			
+			def self.all(extra_sql = nil)
+				$og.load_all(#{klass}, extra_sql)
+			end
+			
+			def self.select(sql)
+				$og.select(sql, #{klass})
+			end
+
+			def self.select_one(sql)
+				$og.select_one(sql, #{klass})
+			end
+			
+			def self.delete(obj_or_oid)
+				$og.delete(obj_or_oid, #{klass})
+			end
+			
+			def save
+				$og << self
+			end
+			alias_method :save!, :save
+			
+			def update_properties(updatesql)
+				$og.pupdate(updatesql, self.oid, #{klass})
+			end
+			alias_method :pupdate!, :update_properties
+			
+			def delete!
+				$og.delete(@oid, #{klass})
+			end
+		}
+	end
+	
+	# Automatically wrap connection methods.
+	#
+	def self.wrap_method(method, args)
+		args = args.split(/,/)
+		class_eval %{
+			def #{method}(#{args.join(", ")})
+				thread = Thread.current
+				
+				unless conn = thread[:og_conn]
+					conn = @connection_pool.pop()
+					thread[:og_conn] = conn
+				end
+			
+				return conn.#{method}(#{args.collect {|a| a.split(/=/)[0]}.join(", ")})
+			end
+		}
+	end
+		
+	wrap_method :create_table, "klass"
+	wrap_method :drop_table, "klass"
+	wrap_method :save, "obj";	alias_method :<<, :save; alias_method :put, :save
+	wrap_method :insert, "obj"
+	wrap_method :update, "obj"
+	wrap_method :update_properties, "update_sql, obj_or_oid, klass = nil"
+	wrap_method :pupdate, "update_sql, obj_or_oid, klass = nil"
+	wrap_method :load, "oid, klass"; alias_method :get, :load	
+	wrap_method :load_by_oid, "oid, klass"
+	wrap_method :load_by_name, "name, klass"	
+	wrap_method :load_all, "klass, extrasql = nil"
+	wrap_method :select, "sql, klass"
+	wrap_method :select_one, "sql, klass"
+	wrap_method :count, "sql, klass = nil"
+	wrap_method :delete, "obj_or_oid, klass = nil"	
+	wrap_method :query, "sql"
+	wrap_method :exec, "sql"
+
+	def self.create_db!(config)
+		get_connection().db.create_db(config[:database], config[:user], 
+				config[:password])
+	end
+
+	def self.drop_db!(config)
+		backend = config[:backend] || "psql"
+		require "og/backends/#{backend}"
+		eval %{
+			#{backend.capitalize}Backend.drop_db(config[:database], config[:user], 
+					config[:password])
+		}
+	end
+end
+
+end # module