symboltable 0.1

data/README

@@ -0,0 +1,81 @@
++++ SymbolTable +++
+
+SymbolTable is a handy little Ruby class that was conceived from the union of
+Hash and Symbol. SymbolTable directly extends Hash, but it stores all keys
+internally as symbols. Any key that cannot be converted to a Symbol is not
+valid.
+
+While this may seem restrictive, it does have the nice side effect of making
+all keys slightly more memorable and usable. For example, values may be set
+and retrieved using any key that resolves to the same symbol.
+
+    h = Hash.new
+    h[:a] = 1
+    h[:a]       # => 1
+    h['a']      # => nil
+    h.a         # => NoMethodError: undefined method `a' for {}:Hash
+
+    require 'symboltable'
+
+    t = SymbolTable.new
+    t[:a] = 1
+    t[:a]       # => 1
+    t['a']      # => 1
+    t.a         # => 1
+    t.b = 2     # => 2
+
+Also, because SymbolTable subclasses Hash, you get all the nice methods of Hash
+for free.
+
+    t.keys      # => [:a, :b]
+    t.values    # => [1, 2]
+
+    t.merge!('c' => 3, :d => 4)
+    t.keys      # => [:a, :b, :c, :d]
+    t.values    # => [1, 2, 3, 4]
+
+    t.each do |k, v|
+      puts "#{k} = #{v}"
+    end
+
+You get the idea. This kind of data structure is mainly useful for large
+configuration objects and the like, where you want to store a bunch of data and
+you don't want to have to remember later how you stored it.
+
+== Why?
+
+Mainly just for fun, and because I sometimes miss the automatic and ubiquitous
+type conversion you get in PHP.
+
+== Installation
+
+Using RubyGems:
+
+    $ sudo gem install symboltable
+
+From a local copy:
+
+    $ git clone git://github.com/mjijackson/symboltable.git
+    $ rake package && sudo rake install
+
+== License
+
+Copyright 2010 Michael J. I. Jackson
+
+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,67 @@
+require 'rake/clean'
+require 'rake/testtask'
+
+task :default => :test
+
+CLEAN.include %w< doc >
+CLOBBER.include %w< dist >
+
+# TESTS #######################################################################
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/symboltable.rb']
+end
+
+# DOCS ########################################################################
+
+desc "Generate API documentation (in doc)"
+task :doc => FileList['lib/**/*.rb'] do |t|
+  rm_rf 'doc'
+  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  hanna
+    --op doc
+    --promiscuous
+    --charset utf8
+    --fmt html
+    --inline-source
+    --line-numbers
+    --accessor option_accessor=RW
+    --main SymbolTable
+    --title 'SymbolTable API Documentation'
+    #{t.prerequisites.join(' ')}
+  SH
+end
+
+# PACKAGING & INSTALLATION ####################################################
+
+if defined?(Gem)
+  $spec = eval("#{File.read('symboltable.gemspec')}")
+
+  directory 'dist'
+
+  def package(ext='')
+    "dist/#{$spec.name}-#{$spec.version}" + ext
+  end
+
+  file package('.gem') => %w< dist > + $spec.files do |f|
+    sh "gem build symboltable.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w< dist > + $spec.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
+  desc "Build packages"
+  task :package => %w< .gem .tar.gz >.map {|e| package(e) }
+
+  desc "Build and install as local gem"
+  task :install => package('.gem') do |t|
+    sh "gem install #{package('.gem')}"
+  end
+
+  desc "Upload gem to rubygems.org"
+  task :release => package('.gem') do |t|
+    sh "gem push #{package('.gem')}"
+  end
+end

data/lib/symboltable.rb

@@ -0,0 +1,54 @@
+# A Hash that forces all keys to be symbols.
+#
+# See http://github.com/mjijackson/symboltable for more information.
+class SymbolTable < Hash
+
+  def initialize(hash=nil)
+    super()
+    merge!(hash) unless hash.nil?
+  end
+
+  # Returns +true+ if the given key may be used in this table.
+  def valid_key?(key)
+    key.respond_to?(:to_sym)
+  end
+
+  def key?(key)
+    super(key) || (valid_key?(key) && super(key.to_sym))
+  end
+
+  def [](key)
+    super(key.to_sym) if valid_key?(key)
+  end
+
+  def store(key, val)
+    if valid_key?(key)
+      val = SymbolTable.new(val) if Hash === val && !(SymbolTable === val)
+      super(key.to_sym, val)
+    end
+  end
+  alias :[]= :store
+
+  def merge!(other_hash)
+    raise ArgumentError unless Hash === other_hash
+    other_hash.each do |k, v|
+      if block_given? && key?(k)
+        self[k] = yield(k, self[k], v)
+      else
+        self[k] = v
+      end
+    end
+  end
+  alias :update :merge!
+
+  def method_missing(sym, *args)
+    if sym.to_s =~ /(.+)=$/
+      self[$1] = args[0]
+    elsif args.empty?
+      self[sym]
+    else
+      super(sym, *args)
+    end
+  end
+
+end

data/symboltable.gemspec

@@ -0,0 +1,27 @@
+Gem::Specification.new do |s|
+  s.name = 'symboltable'
+  s.version = '0.1'
+  s.date = '2010-04-08'
+
+  s.summary = 'A Symbols-only Hash for Ruby'
+  s.description = 'A Symbols-only Hash for Ruby'
+
+  s.author = 'Michael J. I. Jackson'
+  s.email = 'mjijackson@gmail.com'
+
+  s.require_paths = %w< lib >
+
+  s.files = Dir['lib/**/*.rb'] +
+    Dir['test/*.rb'] +
+    %w< symboltable.gemspec Rakefile README >
+
+  s.test_files = s.files.select {|path| path =~ /^test\/.*.rb/ }
+
+  s.add_development_dependency('rake')
+
+  s.has_rdoc = true
+  s.rdoc_options = %w< --line-numbers --inline-source --title SymbolTable --main SymbolTable >
+  s.extra_rdoc_files = %w< README >
+
+  s.homepage = 'http://github.com/mjijackson/symboltable'
+end

data/test/symboltable.rb

@@ -0,0 +1,126 @@
+libdir = File.dirname(File.dirname(__FILE__)) + '/lib'
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require 'test/unit'
+require 'symboltable'
+
+class SymbolTableTest < Test::Unit::TestCase
+
+  def test_empty
+    t = SymbolTable.new
+
+    assert_equal(nil, t[:a])
+    assert_equal(nil, t['a'])
+  end
+
+  def test_bracket
+    t = SymbolTable.new
+
+    t[:a] = 1
+    assert_equal(1, t[:a])
+    assert_equal(1, t['a'])
+
+    t['b'] = 1
+    assert_equal(1, t[:b])
+    assert_equal(1, t['b'])
+
+    assert_equal([:a, :b], t.keys)
+    assert_equal([1, 1], t.values)
+  end
+
+  def test_store
+    t = SymbolTable.new
+
+    t.store(:a, 1)
+    assert_equal(1, t[:a])
+    assert_equal(1, t['a'])
+
+    t.store('b', 1)
+    assert_equal(1, t[:b])
+    assert_equal(1, t['b'])
+
+    assert_equal([:a, :b], t.keys)
+    assert_equal([1, 1], t.values)
+  end
+
+  def test_update
+    t = SymbolTable.new
+
+    t.update(:a => 1)
+    assert_equal(1, t[:a])
+    assert_equal(1, t['a'])
+
+    t.update('b' => 1)
+    assert_equal(1, t[:b])
+    assert_equal(1, t['b'])
+
+    assert_equal([:a, :b], t.keys)
+    assert_equal([1, 1], t.values)
+  end
+
+  def test_merge!
+    t = SymbolTable.new
+
+    t.merge!(:a => 1)
+    assert_equal(1, t[:a])
+    assert_equal(1, t['a'])
+
+    t.merge!('b' => 1)
+    assert_equal(1, t[:b])
+    assert_equal(1, t['b'])
+
+    assert_equal([:a, :b], t.keys)
+    assert_equal([1, 1], t.values)
+  end
+
+  def test_method_missing
+    t = SymbolTable.new
+
+    t.a = 1
+    assert_equal(1, t[:a])
+    assert_equal(1, t['a'])
+    assert_equal(1, t.a)
+
+    assert_equal([:a], t.keys)
+    assert_equal([1], t.values)
+  end
+
+  def test_nested_tables
+    t = SymbolTable.new
+
+    t[:a] = {:a => 1}
+    assert_equal(1, t.a[:a])
+    assert_equal(1, t.a['a'])
+
+    t[:a] = {'a' => 1}
+    assert_equal(1, t.a[:a])
+    assert_equal(1, t.a['a'])
+  end
+
+  def test_key?
+    t = SymbolTable.new
+
+    t[:a] = 1
+    assert(t.key?(:a))
+    assert(t.key?('a'))
+  end
+
+  def test_new
+    t = SymbolTable[:a, 1]
+
+    assert_equal(1, t[:a])
+    assert_equal(1, t['a'])
+  end
+
+  def test_merge
+    t = SymbolTable.new
+    t[:a] = 1
+    b = t.merge(:a => 2)
+
+    assert_equal([:a], t.keys)
+    assert_equal([1],  t.values)
+    assert_equal([:a], b.keys)
+    assert_equal([2],  b.values)
+  end
+
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: symboltable
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Michael J. I. Jackson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-08 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: A Symbols-only Hash for Ruby
+email: mjijackson@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/symboltable.rb
+- test/symboltable.rb
+- symboltable.gemspec
+- Rakefile
+- README
+has_rdoc: true
+homepage: http://github.com/mjijackson/symboltable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- SymbolTable
+- --main
+- SymbolTable
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A Symbols-only Hash for Ruby
+test_files: 
+- test/symboltable.rb