appconf 0.0.1

data/README.md

@@ -0,0 +1,119 @@
+# AppConf
+
+**AppConf** is a ruby gem used to query values of hierarchically organized configuration items from a series of configuration YAML files in priority, via dot split item path names.
+
+
+
+## Installation
+
+```shell
+gem install appconf
+```
+
+## Description
+
+**AppConf** loads and parses a series of YAML configuration files in priority, which means if multiple configuration items with the same path name exist in different files, then the value of the item in the highest priority file will be selected as query result.
+
+**AppConf** will loads all these YAML configuration files, if exist, in priority highest to lowest:
+
+- *`/path/to/specified/deployment/dir`*/*`myapp`*.*`ruby-platform`*.yaml
+- *`/path/to/specified/deployment/dir`*/*`myapp`*.yaml
+- *`/home/username`*/*`.myapp`*/*`myapp`*.*`ruby-platform`*.yaml
+- *`/home/username`*/*`.myapp`*/*`myapp`*.yaml
+- /etc/*`myapp`*/*`myapp`*.*`ruby-platform`*.yaml
+- /etc/*`myapp`*/*`myapp`*.yaml
+- *`/path/to/myapp`*/conf/*`myapp`*.*`ruby-platform`*.yaml
+- *`/path/to/myapp`*/conf/*`myapp`*.yaml
+
+Where:
+
+- *`/path/to/specified/deployment/dir`*: The directory where you app is deployed, use AppConfig::setup to tell the gem where it is.
+
+
+- *`myapp`*: The name of the configuration file you requested via AppConfig::get_conf, or the name of your app when nil is used for configuration file name. The app name is setup via AppConfig::setup.
+- *`.myapp`*: Note that there is a **dot** before `myapp` for the name of this directory, which holds user level configuration file. While on Windows, there is **no** such dot.
+
+
+- *`ruby-platform`*: The platform of the ruby is running on. For jruby, it is `java`.
+
+
+- *`/home/username`*: The home directory of the user who is running your app. In Windows, it's `ENV['USERPROFILE']`, for POSIX, `ENV['HOME']` is used.  
+
+
+- `/etc`: In Windows, `ENV['ALLUSERSPROFILE']` is used. 
+
+
+- *`/path/to/myapp`*: The root directory where your app resides in.
+
+## Why YAML?
+
+XML is heavy and verbose, JSON has no comments, that's it.
+
+## Usage
+
+Say you have a ruby app named `awsome`, need a default configuration file located in `conf` directory under your app's root path, named `awsome.yaml` like this (in YAML):
+
+```yaml
+---
+db:
+	driver: sequel
+	conection: sqlite://awsome.db
+```
+
+While when you are testing you app on your development machine, you want to use a specific sqlite database file located at `/home/arloan/awsome-db/test-2016.db`, how can I do? It's simple, place a file named `awsome.yaml` under `/home/arloan/.awsome/`, with the contents:
+
+```yaml
+---
+db:
+	connection: sqlite:///home/arloan/awsome-db/test-2016.db
+```
+
+In addition, you want your app to be compatible with jruby, and want to use a different, jruby specific database connection method when running under jruby, then you can create a configuration file named `awsome.java.yaml`  and place it along with your default `awsome.yaml`, in  `conf` directory under your app's root path, with the contents:
+
+```yaml
+---
+db:
+	connection: jdbc:sqlite:awsome.db
+```
+
+In your app's code, you write:
+
+```ruby
+require 'appconf'
+
+# in app's initialization part
+AppConfig.setup 'Awsome', # app name, will be converted to lower case automatically
+	File.dirname(__FILE__), # app root dir path
+	'/path/to/app/deployment/directory' # app deployment path, i.e production env
+
+# default config with app name and deployment directory
+default_config = AppConfig.get_config
+
+# use another series of configuration files with new name, use 'new-name.yaml' series
+another_config = AppConfig.get_config 'new-name'
+
+# you can overwrite deployment directory when get a config serie
+overwritten_config = AppConfig.get_config nil, '/path/to/new/deployment/dir'
+
+# to query config value:
+# conn == 'sqlite://awsome.db' in default case
+# conn == 'sqlite:///home/arloan/awsome-db/test-2016.db' in development environment.
+# conn == 'jdbc:sqlite:awsome.db' in jruby
+conn = default_config['db.connection']
+
+# non exist path returns nil, no exception
+this_is_nil = default_config['non.exist.conf.item.path']
+```
+
+## License
+
+(The MIT License)
+
+Copyright © Arloan Bone (arloan@gmail.com)
+
+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/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# -*- encoding: utf-8 -*-
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+	t.libs << %w{ test }
+	t.pattern = 'test/test*.rb'
+end
+
+task :default => :test

data/lib/appconf.rb

@@ -0,0 +1,199 @@
+# -*- encoding: utf-8 -*-
+# author: Arloan Bone (arloan@gmail.com)
+
+require 'yaml'
+
+##usage:
+# AppConfig.setup('myApp', 'app/root/dir', 'deploy/config/dir')
+# 	#'app_root_dir' determines where distribute-default config resides
+#		#'myApp' will be converted to lowercase automatically.
+#		#'deploy_config_dir': config file residential dir on deployment, can be nil,
+#		#	in which case, config dir from environment MYAPP_CONFIG_DIR will be used.
+# config = AppConfig::get_config('config_name', 'config/dir')
+#		#'config_name' can be nil, in which case myapp.config.yaml is used.
+#		#'config/dir' non-nil to override deploy config dir from AppConfig::setup
+##to query config item:
+# config['some.settings.item.dotted.path']
+
+class Hash
+	def path_lookup(path)
+		return nil if path == nil || path.to_s.empty?
+		path = path.to_s
+		path_list = path.split('.')
+
+		o = self
+		path_list.each_with_index do |pe, idx|
+			o = o[pe] || o[pe.to_sym]
+			return nil if o == nil || !o.is_a?(Hash) && idx < path_list.length - 1
+		end
+		o
+	end
+end
+
+
+require 'appconf_version'
+class AppConfig
+
+	class ConfigError < RuntimeError; end
+
+	CONFIG_BASE_NAME = 'config'
+
+	def self.setup(app_name, app_root_dir, deploy_conf_dir = nil)
+		raise ArgumentError, 'app name cannot be empty' if app_name.nil? or app_name.length == 0
+		raise ArgumentError, 'app root directory not specified' if app_root_dir.nil? or app_root_dir.length == 0
+		raise ArgumentError, 'app root directory does not exist or not a directory' unless File.directory?(app_root_dir)
+
+		@@app_raw_name = app_name
+		@@app_name = app_name.downcase
+		@@app_root_dir = File.expand_path(app_root_dir)
+
+		raise ArgumentError, 'deploy config directory does not exist or not a directory' if deploy_conf_dir && !File.directory?(deploy_conf_dir)
+		@@deploy_config_dir = deploy_conf_dir or ENV[@base_name.upcase + '_CONF_DIR']
+		raise ConfigError, 'config directory `%s\' specifed by environment does not exist or not a directory' %
+			@@deploy_config_dir if @@deploy_config_dir && !File.directory?(@@deploy_config_dir)
+	end
+	def self.app_name
+		@@app_raw_name
+	end
+	def self.get_config config_name = nil, config_dir = nil
+		raise ConfigError, ('please call %s::setup() before getting a config instance' % self.name) if @@app_name.nil?
+		self.new config_dir, config_name
+	end
+
+	def [] key
+		@deploy_platform_config.path_lookup(key) ||
+			@deploy_config.path_lookup(key) ||
+			@user_platform_config.path_lookup(key) ||
+			@user_config.path_lookup(key) ||
+			@global_platform_config.path_lookup(key) ||
+			@global_config.path_lookup(key) ||
+			@dist_platform_config.path_lookup(key) ||
+			@dist_config.path_lookup(key)
+	end
+
+	def reload
+		@deploy_platform_config = deploy_platform_config || {}
+		@deploy_config = deploy_config || {}
+
+		@user_platform_config = user_platform_config || {}
+		@user_config = user_config || {}
+
+		@global_platform_config = global_platform_config || {}
+		@global_config = global_config || {}
+
+		@dist_platform_config = dist_platform_config || {}
+		@dist_config = dist_config || {}
+	end
+
+	attr_reader :config_files, :config_file_name, :platform_config_file_name,
+		:dist_config_dir, :global_config_dir, :user_config_dir, :deploy_config_dir
+
+  private
+
+	def initialize(config_name = nil, config_dir = nil)
+		raise ArgumentError, 'specified config directory `%s\' does not exist'%config_dir if config_dir && !File.exist?(config_dir)
+		
+		@base_name = config_name || @@app_name
+		@deploy_config_dir = config_dir || @@deploy_config_dir
+		@deploy_config_dir = nil if config_dir && config_dir.length == 0
+		@deploy_config_dir = File.expand_path(@deploy_config_dir) if @deploy_config_dir
+
+		@config_file_name = '%s.%s.yaml' % [@base_name, CONFIG_BASE_NAME]
+		@platform_config_file_name = '%s.%s.%s.yaml' % [@base_name, RUBY_PLATFORM, CONFIG_BASE_NAME]
+
+		@dist_config_dir = File.join @@app_root_dir, CONFIG_BASE_NAME
+		@global_config_dir = sys_config_dir
+		@user_config_dir = usr_config_dir
+
+		@config_files = []
+		reload
+	end
+
+	def dist_config
+		file_path = File.join @dist_config_dir, @config_file_name
+		if File.exist?(file_path)
+			@config_files << file_path
+			return load_yaml_file file_path
+		end
+		nil
+	end
+	def dist_platform_config
+		file_path = File.join @dist_config_dir, @platform_config_file_name
+		if File.exist?(file_path)
+			@config_files << file_path
+			return load_yaml_file file_path
+		end
+		nil
+	end
+	def global_config
+		file_path = File.join @global_config_dir, @config_file_name
+		if File.exist?(file_path)
+			@config_files << file_path
+			return load_yaml_file file_path
+		end
+		nil
+	end
+	def global_platform_config
+		file_path = File.join @global_config_dir, @platform_config_file_name
+		if File.exist?(file_path)
+			@config_files << file_path
+			return load_yaml_file file_path
+		end
+		nil
+	end
+	def user_config
+		file_path = File.join @user_config_dir, @config_file_name
+		if File.exist?(file_path)
+			@config_files << file_path
+			return load_yaml_file file_path
+		end
+		nil
+	end
+	def user_platform_config
+		file_path = File.join @user_config_dir, @platform_config_file_name
+		if File.exist?(file_path)
+			@config_files << file_path
+			return load_yaml_file file_path
+		end
+		nil
+	end
+	def deploy_config
+		return nil if @deploy_config_dir.nil?
+		file_path = File.join @deploy_config_dir, @config_file_name
+		if file_path && File.file?(file_path)
+			@config_files << file_path
+			return load_yaml_file(file_path)
+		end
+		nil
+	end
+	def deploy_platform_config
+		return nil if @deploy_config_dir.nil?
+		file_path = File.join @deploy_config_dir, @platform_config_file_name
+		if file_path && File.file?(file_path)
+			@config_files << file_path
+			return load_yaml_file(file_path)
+		end
+		nil
+	end
+
+	def load_yaml_file(file_path)
+		YAML.load(IO.read(file_path)) if File.file?(file_path)
+	end
+
+	def sys_config_dir
+		if ENV['OS'] == 'Windows_NT'
+			dir = File.join(ENV['ALLUSERSPROFILE'], 'Application Data', @@app_name)
+		else
+			dir = File.join('/etc', @@app_name)
+		end
+		return File.expand_path(dir)
+	end
+	def usr_config_dir
+		if ENV['OS'] == 'Windows_NT'
+			dir = File.join(ENV['USERPROFILE'], @@app_name)
+		else
+			dir = File.join(ENV['HOME'], '.' + @@app_name)
+		end
+		return File.expand_path(dir)
+	end
+end

data/lib/appconf_version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+class AppConfig
+	VERSION = '0.0.1'
+end

data/test/test_appconf.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+# -*- encoding: utf-8 -*-
+
+require 'minitest/autorun'
+require 'appconf' # use this with Rake
+#require_relative '../lib/appconf' # use this without Rake
+
+class AppConfigTest < MiniTest::Unit::TestCase
+	DEPLOY_VALUE			= 'deployment value'
+	DEPLOY_PLATFORM_VALUE	= 'deployment platform value'
+	USER_VALUE				= 'user value'
+	USER_PLATFORM_VALUE		= 'user platform value'
+	GLOBAL_VALUE			= 'global value'
+	GLOBAL_PLATFORM_VALUE	= 'global platform value'
+	DIST_VALUE				= 'distribution value'
+	DIST_PLATFORM_VALUE		= 'distribution platform value'
+
+	TEST_CONFIG_NAME		= 'foo.bar'
+
+	# a new TestCase object created for every test method testing
+	AppConfig.setup 'Test', File.dirname(__FILE__), ENV['TMP']
+	@@config = AppConfig.get_config
+
+	def self.clean
+		#puts 'AppConfigTest::clean called.'
+		@@config.config_files.each { |f| File.delete f if File.exist? f }
+		begin
+			Dir.rmdir @@config.dist_config_dir   if File.exist? @@config.dist_config_dir
+			Dir.rmdir @@config.user_config_dir   if File.exist? @@config.user_config_dir
+			Dir.rmdir @@config.global_config_dir if File.exist? @@config.global_config_dir
+		rescue
+			$stderr.puts $!
+		end
+	end
+
+	self.clean
+
+	def self.test_order
+		:alpha
+	end
+
+	def test_h_deploy_platform_value
+		create_deploy_platform_config_file
+		@@config.reload
+		assert_equal DEPLOY_PLATFORM_VALUE, query_config_value
+	end
+	def test_g_deploy_value
+		create_deploy_config_file
+		@@config.reload
+		assert_equal DEPLOY_VALUE, query_config_value
+	end
+	def test_f_user_platform_value
+		create_user_platform_config_file
+		@@config.reload
+		assert_equal USER_PLATFORM_VALUE, query_config_value
+	end
+	def test_e_user_value
+		create_user_config_file
+		@@config.reload
+		assert_equal USER_VALUE, query_config_value
+	end
+	def test_d_global_platform_value
+		create_global_platform_config_file
+		@@config.reload
+		assert_equal GLOBAL_PLATFORM_VALUE, query_config_value
+	end
+	def test_c_global_value
+		create_global_config_file
+		@@config.reload
+		assert_equal GLOBAL_VALUE, query_config_value
+	end
+	def test_b_dist_platform_value
+		create_dist_platform_config_file
+		@@config.reload
+		assert_equal DIST_PLATFORM_VALUE, query_config_value
+	end
+	def test_a_dist_value
+		create_dist_config_file
+		@@config.reload
+		assert_equal DIST_VALUE, query_config_value
+	end
+	def test_i_non_exist_value
+		assert_equal nil, @@config['non.exist.config.item']
+	end
+
+	def test_z_clean
+		self.class.clean
+	end
+
+	private
+
+	def query_config_value
+		@@config[TEST_CONFIG_NAME]
+	end
+
+	def create_yaml_with_value(path, v, more = nil)
+		c = { :foo => { :bar => v } }
+		c.merge! more if more and more.is_a?(Hash)
+		dir = File.dirname(path)
+		Dir.mkdir dir unless File.exist?(dir)
+		File.open(path, 'w') { |f| f.write c.to_yaml }
+		puts 'YAML created: %s' % path
+	end
+	def create_deploy_config_file
+		path = File.join @@config.deploy_config_dir, @@config.config_file_name
+		create_yaml_with_value path, DEPLOY_VALUE
+	end
+	def create_deploy_platform_config_file
+		path = File.join @@config.deploy_config_dir, @@config.platform_config_file_name
+		create_yaml_with_value path, DEPLOY_PLATFORM_VALUE
+	end
+	def create_user_config_file
+		path = File.join @@config.user_config_dir, @@config.config_file_name
+		create_yaml_with_value path, USER_VALUE
+	end
+	def create_user_platform_config_file
+		path = File.join @@config.user_config_dir, @@config.platform_config_file_name
+		create_yaml_with_value path, USER_PLATFORM_VALUE
+	end
+	def create_global_config_file
+		path = File.join @@config.global_config_dir, @@config.config_file_name
+		create_yaml_with_value path, GLOBAL_VALUE
+	end
+	def create_global_platform_config_file
+		path = File.join @@config.global_config_dir, @@config.platform_config_file_name
+		create_yaml_with_value path, GLOBAL_PLATFORM_VALUE
+	end
+	def create_dist_config_file
+		path = File.join @@config.dist_config_dir, @@config.config_file_name
+		create_yaml_with_value path, DIST_VALUE
+	end
+	def create_dist_platform_config_file
+		path = File.join @@config.dist_config_dir, @@config.platform_config_file_name
+		create_yaml_with_value path, DIST_PLATFORM_VALUE
+	end
+
+end
+
+# this line does not work
+# MiniTest::Unit.after_tests { AppConfigTest.clean }

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: appconf
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Arloan Bone
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-07 00:00:00.000000000 Z
+dependencies: []
+description: Application configuration file loader & querier
+email: arloan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/appconf.rb
+- lib/appconf_version.rb
+- test/test_appconf.rb
+- Rakefile
+- README.md
+homepage: https://github.com/arloan/appconf
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: AppConf
+test_files: []