o 1.0.2 → 2.0.0

data/README.md

@@ -7,71 +7,229 @@ O, a configuration libraray for Ruby
 **Documentation**: [http://rubydoc.info/gems/o/frames](http://rubydoc.info/gems/o/frames) <br/>
 **Issue Tracker**: [https://github.com/GutenYe/o/issues](https://github.com/GutenYe/o/issues) <br/>
 
+Features
+--------
+
+* support variable, computed attribute
+* DSL syntax in pure ruby
+* tree way to do configration.
+* hash compatibility
+
 Introduction
 -------------
 
-	option = O.new
+do configuration at three levels: system, user, cmdline
+
+	lib/guten/rc.rb   # system level
+	~/.gutenrc        # user level
+	$ guten --list    # cmdline level
+		
+	module Guten
+		Rc = O.require("guten/rc") + O.require("~/.gutenrc")
+		Rc.list = true
+	end
+
+
+### a completed example ###
+
+	Rc = O do
+		host "localhost"
+		port 8080
+		mail.stmp.address "stmp.gmail.com"
+
+		my.development do  # namespace
+			adapter "mysql2"
+			database "hello"
+			username "guten"
+		end
+
+		time proc{|offset| Time.now} # computed attribute
+	end
+
+alternative syntax
+
+	Rc = O do |c|
+		c.host = "localhost"
+		c.port = 8080
+		c.mail.stmp.address "stmp.gmail.com"
+
+		my.development do |c|
+			c.adapter = "mysql2"
+			c.database = "hello"
+			c.username = "guten"
+		end
+
+		c.time = proc{|offset| Time.now}
+	end
+
+### initialize ###
+
+either way is fine
+
+	Rc = O.new
+	Rc = O.require "guten/rc"  # from file
+	Rc = O do 
+		a 1 
+	end
+	Rc = O[a:1]  # from hash   
+	Rc._merge! O_or_Hash  
+
+file: "guten/rc.rb"
+
+	a 1
 
-	# assigment
-	option["a"] = 1
-	option[:a] = 1
-	option.a = 1
 
-	# access
-	option["a"] 
-	option[:a] 
-	option.a 
-	option.a? #=> true
+### assignment & access ###
 
-	#access Hash methods.
-	option._keys #=> [:a]
+either way is fine
 
-assign default value
+	Rc.age 1
+	Rc.age = 1
+	Rc[:age] = 1
+	Rc["age"] = 1
+	---
+	Rc.age    #=> 1
+	Rc.age?   #=> true
+	Rc[:age]  #=> 1
+	Rc["age"] #=> 1
+	--- 
+	O do |c|
+		age 2
+		c.age = 2
+		c[:age] = 2
+	end
 
-	option = O.new
-	option.a #=> nil
+### node ###
 
-	option = O.new 0
-	option.a #=> 0
+	Rc.a.b.c 1
+	p Rc.a.b.c #=> <#Fixnum 1>
+	p Rc.a.b   #=> <#O>
+	p Rc.a     #=> <#O>
+	p Rc.i.dont.exists #=> <#O> #check use #_empty?
 
-another syntax
+### variable & path ###
 
-	option = O do
-	  base = 1
-	  @a = base
-	  @b = base + 1
+	O do
+		age 1
+		p age  #=> 1
+		my do
+			age 2
+			friend do
+				age 3
+				p age     #=> 3
+				p __.age  #=> 2  relative
+				p ___.age #=> 1
+				p _.age   #=> 1  root
+			end
+		end
 	end
-	option.a #=> 1 
-	option.b #=> 2
 
+### namespace ###
 
-read option from a file
+either way is fine
 
-	# ~/.gutenrc
-	@a = 1
-	@path = Pathname('/home')
+	O do
+		mail.stmp.address "stmp.gmail.com"
+		mail.stmp do
+			address "stmp.gmail.com"
+		end
+	end
 
-	# a.rb
-	require "pathname"
-	option = O.load("~/.gutenrc")
-	option.a #=> 1
+another example
 
-configuration file
-------------------
+	O do
+		age 1 
 
- use instance variable to export field.
+		my do
+			age 2 
+		end
 
-	base = 1
-	@a = base 
-	@b = O do
-	  p @a #=> nil   # instance variable can't pass into block
-	  p base #=>  1  # local variable can pass into block
-	  @a = base + 1
+		my.friend do
+			age 3 
+		end
 	end
-	
-	# after O.load(file)
-	option.a #=> 1
-	option.b.a #=> 2
+
+
+### group ###
+
+use namespace or use some seperate files like rails.
+
+	config/
+		applications.rb
+		environments/
+			development.rb
+			test.rb
+			production.rb
+
+### computed attribute ###
+
+	Rc = O do
+		time proc{|n| Time.now}
+	end
+	p Rc.time # print current time. no need Rc.time.call()
+	p Rc.time(2) # call time
+	Rc.time = 2 # assign new value
+	p Rc[:time] #=> <#Proc>
+
+### semantic ###
+
+	O do
+		is_started no # yes ...
+	end
+
+for a list of semantic methods, see O::Semantics
+
+### hash compatibility ###
+
+	Rc._keys # access hash method via `_method`
+
+### temporarily change ###
+
+	Rc.a = 1
+	Rc._temp do
+		Rc.a = 2
+	end
+	p Rc.a #=> 1
+
+
+### access builtin method inside block ###
+
+	Rc = O do
+		sleep 10     # is a data. Rc.sleep #=> 10
+		O.sleep 10   # call builtin 'sleep' method
+	end
+
+a list of blocked methods is in O::BUILTIN_METHODS
+
+### another sugar syntax ###
+
+it likes yaml-style.  this way is experiment. used in file syntax only
+
+	# file: guten/rc.rb
+	a:
+		b 1
+		c:
+			d 1
+
+	#=>
+
+	a do
+		b 1
+		c do
+			d 1
+		end
+	end
+
+**WARNNING**:  must use \t to indent
+
+### some other examples ###
+
+	name do
+		first "Guten"
+		last  "Ye"
+		is    "#{first} #{last}"
+	end
+
 
 Contributing
 -------------
@@ -90,7 +248,10 @@ Install
 Resources
 ---------
 
-[configuration](https://github.com/ahoward/configuration)
+* [konfigurator](https://github.com/nu7hatch/konfigurator) Small and flexible configuration toolkit inspired i.a. by Sinatra settings
+* [configatron](https://github.com/markbates/configatron) A super cool, simple, and feature rich configuration system for Ruby apps 
+* [simpleconfig](https://github.com/lukeredpath/simpleconfig) make application-wide configuration settings easy to set and access in an object-oriented fashion
+* [configuration](https://github.com/ahoward/configuration) pure ruby scoped configuration files 
 
 Copyright
 ---------

data/lib/o.rb

@@ -1,40 +1,55 @@
-#
-# internal: store data in a Hash, the key of the Hash is always converted to symbol.
-#
-#
-#
-class O < Hash
-	# PATH for O.load
-	PATH = []
-	Error = Exception.new 
-	LoadError = Exception.new(Error)
-
-	class O_Eval
-		def _data
-			_data = {}
-			self.instance_variables.each do |k|
-				key = k[1..-1].to_sym
-				value = self.instance_variable_get(k)
-				_data[key] = value 
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+%w(semantics hash_method_fix parser).each{|n| require "o/#{n}"}
+
+class O
+	autoload :VERSION, "o/version"
+
+	Error 		= Class.new Exception 
+	LoadError = Class.new Error
+
+	BUILTIN_METHODS = [ :p, :pd, :raise, :sleep, :rand, :srand, :exit, :require, :at_exit, :autoload, :open]
+
+	class << self
+		public *BUILTIN_METHODS 
+
+		# @params [String] content
+		def eval content=nil, &blk
+			o = O.new nil
+			content ? o.instance_eval(Parser.compile(content)) : o.instance_eval(&blk)
+			o._root
+		end
+
+		# convert hash, O to O
+		# @param [O,Hash] data
+		def [] data
+			case data
+			when O
+				data
+			when Hash
+				o = O.new
+				o._child = data
+				o
 			end
-			_data
 		end
-	end
 
-	class << self
-		# convert <#Hash> to <#O>
+		# get hash data from obj
+		#
+		# @param [O, Hash] obj
 		#
-		# @param [hash] hash
-		# @return O
-		def from_hash hash
-			o = O.new
-			o._replace hash
+		# @return [Hash] 
+		def get obj
+			case obj
+			when Hash
+				obj
+			when O
+				obj._child
+			end
 		end
 
 		# load a configuration file,
-		# support PATH, and '~/.gutenrc'
-		#
-		# first try name.rb, then use name
+		# use $: and support '~/.gutenrc'
 		#
 		# @example
 		#   option = O.load("~/.gutenrc")
@@ -42,21 +57,27 @@ class O < Hash
 		#   option = O.load("/absolute/path/a.rb")
 		#   
 		#   O::Path << "/home"
-		#   option = O.load("guten")  #=> try guten.rb; then try guten
+		#   option = O.load("guten")  #=> try "guten.rb"; then try "guten"
 		#   option = O.load("guten.rb")
 		#
 		# @param [String] name
 		# @return [O]
-		def load name
+		def require name
 			path = nil
+
+			# ~/.gutenrc
 			if name =~ /^~/
 				file = File.expand_path(name)
 				path = file if File.exists?(file)
+
+			# /absolute/path/to/rc
 			elsif File.absolute_path(name) == name
 				path = name if File.exists?(name)
+
+			# relative/rc
 			else
 				catch :break do
-					PATH.each  do |p|
+					$:.each do |p|
 						['.rb', ''].each {|ext|
 							file = File.join(p, name+ext)
 							if File.exists? file
@@ -70,118 +91,183 @@ class O < Hash
 
 			raise LoadError, "can't find file -- #{name}" unless path
 
-			eval_file path
+			O.eval File.read(path)
 		end
+	end
 
-		# relative load a configuration file
-		# @see load
-		#
-		# @param [String] name
-		# @return [O] option
-		def relative_load name
-			pd caller if $TEST
-			a,file, line, method = caller[0].match(/^(.*):(\d+):.*`(.*)'$/).to_a
-			raise LoadError, "#{type} is called in #{file}" if file=~/\(.*\)/ # eval, etc.
+	undef_method *BUILTIN_METHODS
+	include Semantics
+	include HashMethodFix
 
-			file = File.readlink(file) if File.symlink?(file)
+	attr_accessor :_parent, :_child, :_root
 
-			path = nil
-			[".rb", ""].each do |ext|
-				f = File.absolute_path(File.join(File.dirname(file), name+ext))
-				if File.exists?(f)
-					path = f
-					break
-				end
-			end
+	def initialize default=nil, options={}, &blk
+		@_root = options[:_root]
+		@_child = Hash.new(default)
 
-			raise LoadError, "can't find file -- #{name}" unless path
-
-			eval_file path
+		if blk
+			method = _blk2method(&blk)
+			if blk.arity == 0
+				method.call
+			else
+				method.call self
+			end
 		end
+	end
 
-		private
-		def eval_file path
-			content = File.open(path){|f| f.read}
-			o_eval = O_Eval.new
-			o_eval.instance_eval(content)
-			O.from_hash(o_eval._data)
-		end
+	def _temp &blk
+		data = _child.dup
+		blk.call
+		self._child = data
+	end
 
+	def _parent
+		@_parent || nil
 	end
 
-	attr_reader :_data
+	def _root
+		@_root || self
+	end
 
-	def initialize default=nil, &blk
-		@_data = Hash.new(default)
-		if blk
-			o_eval = O_Eval.new
-			o_eval.instance_eval &blk
-			@_data.merge!(o_eval._data)
-		end
+	def _child= obj
+		@_child = O.get(obj)
 	end
 
 	def []= key, value
-		@_data[key.to_sym] = value
+		key = key.respond_to?(:to_sym) ? key.to_sym : key
+		@_child[key] = value
 	end
 
 	def [] key
-		@_data[key.to_sym]
+		key = key.respond_to?(:to_sym) ? key.to_sym : key
+		@_child[key]
 	end
 
-	def + other
-		O.new(@_data, other._data)
+	def == other
+		_child == other._child
 	end
 
-	def _replace data
-		case data
-		when Hash
-			@_data = data
-		when O
-			@_data = data._data
-		end
+	def _dup
+		o = O.new
+		o._child = _child.dup
+		o
+	end
+
+	def _replace obj
+		self._child = O.get(obj)
 		self
 	end
 
-	def _merge! data
+	def + other
+		raise Error, "not support type for + -- #{other.inspect}" unless O === other
+		O.new(_child, other._child)
+	end
+
+	# convert block to method.
+	#
+	#   you can call a block with arguments
+	#
+	# @example USAGE
+	#   instance_eval(&blk)
+	#   blk2method(&blk).call *args
+	#
+	def _blk2method &blk
+		self.class.class_eval do
+			define_method(:__blk2method, &blk)
+		end
+		method(:__blk2method)
 	end
 
 
 	#
-	# _method goes to @_data.send(_method, ..)
-	# method? #=> !! @_data[:method]
-	# method #=> @_data[:method]
-	# method=value #=> @_data[:method]=value
+	# .name? 
+	# .name= value 
+	# .name value 
+	# ._name
 	#
-	def method_missing method, *args, &blk
-		if method =~ /(.*)=$/
-			@_data[$1.to_sym] = args[0]
-		elsif method =~ /(.*)\?$/
-			!! @_data[$1.to_sym]
-		elsif method =~ /^_(.*)/
-			method = $1.to_sym
-			args.map!{|arg| O===arg ? arg._data : arg} 
-			rst = @_data.send(method, *args, &blk)
-
-			if [:merge!].include method
-				self
-			elsif [:merge].include method
-				O.new(rst)
+	# .c 
+	# .a.b.c
+	#
+	def method_missing name, *args, &blk
+		#O.pd 'missing', name, args, blk
+
+		# path: root
+		if name == :_
+			return _root
+
+		# relative path.
+		elsif name =~ /^__+$/
+			num = name.to_s.count('_') - 1
+			node = self
+			num.times {
+				return unless node
+				node = node._parent
+			}
+			return node
+
+		# .name=
+		elsif name =~ /(.*)=$/
+			return @_child[$1.to_sym] = args[0]
+
+		# .name?
+		elsif name =~ /(.*)\?$/
+			return !! @_child[$1.to_sym]
+
+		# ._name
+		elsif name =~ /^_(.*)/
+			name = $1.to_sym
+			args.map!{|arg| O===arg ? arg._child : arg} 
+			return @_child.send(name, *args, &blk)
+
+		elsif Proc === @_child[name]
+			return @_child[name].call *args
+
+		# a.c  # return data if has :c
+		# a.c  # create new <#O> if no :c 
+		#
+		elsif args.empty?
+
+			# a.b.c 1
+			# a.b do
+			#   c 2
+			# end
+			if @_child.has_key?(name)
+				o = @_child[name]
+				o.instance_eval(&blk) if blk
+				return o
+
+			else
+				next_o = O.new(nil, {_root: _root})
+				next_o._parent = self
+				self._child[name] = next_o
+				next_o.instance_eval(&blk) if blk
+				return next_o
 			end
+
+		# .name value
 		else
-			@_data[method]
+			@_child[name] = args[0]
+			return args[0]
 		end
 	end
 
-	def inspect 
-		rst = "<#O "
-		@_data.each do |k,v|
-			rst << "#{k}:#{v.inspect} "
+	#
+	# <#O 
+	#   :b => 1
+	#   :c => 2
+	#   :d => <#O
+	#     :c => 2>> 
+	def inspect(indent="  ")
+		o={rst: ""}
+		o[:rst] << "<#O\n"
+		_child.each do |k,v|
+			o[:rst] << "#{indent}#{k.inspect} => "
+			o[:rst] << (O === v ? "#{v.inspect(indent+"  ")}\n" : "#{v.inspect}\n")
 		end
-		rst << " >" 
+		o[:rst].rstrip! << ">"
 	end
 
 	alias to_s inspect
-
 end
 
 module Kernel