xamplr 1.2.0

data/CHANGES.txt

@@ -0,0 +1,13 @@
+
+2009-04-16 (version 1.0.2)
+
+  -- if tag starts with a number, prefix it with an 'x' (e.g. 0abc --> x0abc).
+     The problem arose if a tag like <0abc> was used in an xml file
+     used to generate xampl code. In that case, the 'attribute
+     names' associated with the tag would be based on '_abc'. The
+     change makes the attribute names be based on x0abc. The choice
+     of 'x' is arbitrary, but we can't have a leading digit, and
+     the '_' could fail to distinguish certain elements (e.g. 0abc
+     and 1abc would both be based on '_abc').
+
+

data/LICENSE

@@ -0,0 +1,3 @@
+Copyright (c) 2009 Bob Hutchison
+
+see COPYING

data/README.rdoc

@@ -0,0 +1,26 @@
+= xamplr
+
+xamplr is a set of software tools that supports development of ruby applications.
+
+Features:
+  - supports Domain Driven Design in Ruby
+  - persistence ignornace
+  - clusters, entities, 'regular' objects, and repositories (corresponding approximately to DDD's aggregates, entities, value objects, and repositories)
+  - different peristence techniques including filesystem (XML format) and Tokyo Cabinet
+  - transaction support
+  - querying 
+  - fast development, fast execution
+  - has been in use in commercial software since 2004, a Java version has been in use since 1998.
+
+Anti-Features:
+  - absymal lack of documentation. If you are brave and willing to wade through (old) blog entries, you might try looking at: 
+
+    http://recursive.ca/hutch/category/software/tools-i-use/xampl/
+
+License: For the moment it is AGPLv3 (see COPYING). An alternative license
+may be negotiated, contact me. In the near future this license will be
+relaxed.
+
+== Copyright
+
+Copyright (c) 2009 Bob Hutchison. See LICENSE and COPYING for details.

data/README.rdoc.orig

@@ -0,0 +1,118 @@
+= xamplr
+
+xamplr is a tool for developing Ruby programs, the ruby implementation
+of xampl. It facilitates the 'M' part of an MVC architecture. It
+is meant to be very easy to use, supportive of idiomatic Ruby usage,
+and mostly invisible.
+
+With it's current lack of documentation it will be hard to get going
+with xampl. I am working on documentation that will be appearing
+over the next little while, in the meantime if you are willing to
+wade through a blog, you might try looking at:
+
+http://recursive.ca/hutch/category/software/tools-i-use/xampl/
+
+Features:
+  - pure Ruby, no libraries required except those shipped with Ruby 1.8.2
+  - uses XML to declaratively describe a class structure
+    - uses a collection of example XML documents, no schema are required
+    - supports arbitrary object graphs, not just XML-like trees
+    - Ruby idiomatic facilities to navigate the object structures (e.g. named
+      arrays, hash, iterator support, uses blocks, etc.)
+    - support empty, simple (text content only), data (no or limited text
+      content, but with arbitrary element content), and mixed content (where
+      text and element content can be intermingled)
+    - maintains 'document order' of objects
+    - keeps track of parents
+    - can compare two clusters for equality (limited, but will be improved)
+    - maps XML namespaces to Ruby modules (with handy defaults) and you can
+      suggest preferred namespace prefixes for XML output
+    - converts XML element and attributes names to valid (and predictable)
+      Ruby names
+    - includes an XML pull parser (very fast)
+    - code generation is template driven, so the adventurous can change what
+      is generated
+    - includes a simple but powerful and fast templating engine
+    - includes a simple-minded but effective hash-like class that maintains
+      insertion order (fast insertion, lookup, and iteration, but at the
+      expense of delete)
+    - naming conventions are used when generating code (but these conventions
+      can be changed)
+    - additions to the XML will very rarely break existing code, and so
+      incremental development of functionality is supported
+    - generated code is readable and debuggable
+    - a command line tool to generate the code, or you can generate at runtime
+  - XML binding to the classes (i.e. parsing an XML file will produce an
+    object graph)
+  - can augment existing classes
+  - programmer adds functionality by opening the class or module, no worries
+    about the code generator overwriting your changes
+  - object structures can generate XML output (and there is an XML pretty
+    printer used for emphasising human readable XML output)
+  - easy to use persistence mechanism
+    - persistence is in terms of clusters of objects, the cluster is updated
+      all at once
+    - lazy loading of persisted clusters
+    - LRU cache (of clusters)
+    - the changed clusters are available for inspection
+    - XML, Ruby, and YAML persistence mechanism (purposely no Marshal support)
+    - persist to memory, or hard drive (optional persistence to an FSDB)
+    - sync and rollback (even with memory persistence); this is a weak form
+      of transaction support
+    - 'automatic' and 'manual' modes of persistence ('automatic' means that
+      any xampl cluster created while a persister is active will be
+      automatically managed by that persister, manual means that you have
+      to introduce the xampl cluster to the persister)
+    - fast alternative to persistence that does not support rollback
+    - xampl objects can hold arbitrary attribute values through the
+      persistence 'cycle' if using Ruby or YAML persistence (even xampl
+      object); with XML you won't loose anything but all attributes will
+      be strings after restoration.
+    - multiple persisters, possibly with differing persistence mechanisms,
+      are supported
+    - dead easy single user applications (e.g. desktop apps, CGI), almost as
+      easy for multiple user applications and webapps
+    - you can add your own persister types (and formats for that matter)
+  - general purpose Visitor pattern facility, with pre and post visit methods,
+    cycle and revisit detection and handling
+  - lots of hooks
+  - many unit tests, all execute without warning when run with the -w Ruby flag
+  - there are some examples, and the beginnings of a tutorial in the form of
+    a series of examples that lead you through the core parts of xampl
+
+Features that are coming soon:
+  - many more hooks
+  - more sophisticated augmentation of existing classes
+  - indexing and querying of the persisted object structures
+  - more persisters (e.g. sqlite)
+  - real transactions
+  - a better comparison function (that deals with cyclic structures at all, and
+    better with non-tree acyclic structures)
+
+Known Bugs or Potential Problems or Suspected Problems
+  - generated attribute names may conflict with Ruby keywords and this is not
+    a nice thing to witness (this is easy to fix, but I don't want to do this
+    until the next release at the earliest)
+  - I don't know if this will work on Windows -- I tried, but I don't have a
+    windows machine to test this with -- there might be some pathname stuff
+    assuming unix (but I hope not)
+  - some of the code is unnecessarily ugly (e.g. some of the visitor internals)
+  - there are no Ruby docs (but I promise... really)
+  - comparison of cyclic structures will crash
+
+License: AGPLv3 (see COPYING). An alternative license may be negotiated, contact me.
+
+While the Ruby version of xampl is brand new it is based on a Java
+tool that I've been developing since 1998 and in its fifth generation.
+There are many features in the Java version that are not available in
+this library, but that is either just a matter of time, or they will
+never be needed because Ruby programs don't need the help.
+
+The Java version of the tool has been used to write a number of large
+webapps, and a few smaller desktop applications, and even an applet.
+
+There is a Common Lisp/CLOS version coming.
+
+== Copyright
+
+Copyright (c) 2009 Bob Hutchison. See LICENSE and COPYING for details.

data/Rakefile

@@ -0,0 +1,85 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "xamplr"
+    gem.summary = %Q{xamplr is the ruby version of xampl}
+    gem.email = "hutch@recursive.ca"
+    gem.homepage = "http://github.com/hutch/xamplr"
+    gem.authors = ["Bob Hutchison"]
+    gem.rubyforge_project = 'xampl'
+
+    gem.add_dependency('hutch-xamplr-pp')
+    gem.add_dependency('libxml-ruby', ">=1.1.3")
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "xamplr #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/xampl"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 1
+:minor: 2

data/examples/random-people-shared-addresses/Makefile

@@ -0,0 +1,16 @@
+
+nope:
+
+raw:
+	rm -rf repo
+	time ruby rawtc.rb
+	#time ruby rawtc.rb
+	#time ruby rawtc.rb
+	#time ruby rawtc.rb
+	#time ruby rawtc.rb
+	#time ruby rawtc.rb
+
+batch:
+	rm -rf repo
+	time ruby batch-load-users.rb
+

data/examples/random-people-shared-addresses/batch-load-users.rb

@@ -0,0 +1,83 @@
+require 'fastercsv'
+require 'xampl_generated_code/RandomPeople'
+require 'people'
+require 'settings'
+
+module RandomPeople
+
+  start_at = Time.now
+
+  arr_of_arrs = FasterCSV.read("random-names.csv")
+
+  parsed_at = Time.now
+
+  #GivenName,Surname,StreetAddress,City,State,ZipCode,EmailAddress,TelephoneNumber
+
+  #<people pid=''
+  #        xmlns="http://xampl.com/people">
+  #    <person pid=''
+  #            given-name=''
+  #            surname=''
+  #            email=''
+  #            phone=''>
+  #        <address pid=''
+  #                 street-address=''
+  #                 city=''
+  #                 state=''
+  #                 postal-code=''/>
+  #    </person>
+  #</people>
+
+  base = 0
+
+  created_addresses = 0
+  shared_addresses = 0
+
+  10.times do | iter |
+    inner_start = Time.now
+
+    Xampl.transaction("random-people") do
+
+      base += arr_of_arrs.size
+
+      arr_of_arrs.each_with_index do | row, i |
+        person_pid = "person-#{ base + i }"
+        person = Person.new(person_pid)
+
+        person.given_name = row[0]
+        person.surname = row[1]
+        person.email = row[6]
+        person.phone = row[7]
+
+        addresses = Xampl.find_xampl do | q |
+          q.add_condition('class', :equals, Address.name)
+
+          q.add_condition('street-address', :equals, row[2])
+          q.add_condition('postal-code',    :equals, row[5])
+        end
+
+        address = addresses.first
+        if address then
+          person << address
+          shared_addresses += 1
+        else
+          address = person.new_address("address-#{ person_pid }")
+          address.street_address = row[2]
+          address.city = row[3]
+          address.state = row[4]
+          address.postal_code = row[5]
+          created_addresses += 1
+        end
+
+      end
+      puts "transaction ending..."
+    end
+    puts "iter: #{ iter } in #{ Time.now - inner_start }"
+  end
+
+  processed_at = Time.now
+
+  p "parsed in #{ parsed_at - start_at }, processed in: #{ processed_at - parsed_at }"
+  puts "   created addresses: #{ created_addresses }, shared: #{ shared_addresses }"
+
+end

data/examples/random-people-shared-addresses/find-mentions.rb

@@ -0,0 +1,47 @@
+
+require 'xampl_generated_code/RandomPeople'
+require 'people'
+require 'settings'
+
+module RandomPeople
+
+  #<people pid=''
+  #        xmlns="http://xampl.com/people">
+  #    <person pid=''
+  #            given-name=''
+  #            surname=''
+  #            email=''
+  #            phone=''>
+  #        <address pid=''
+  #                 street-address=''
+  #                 city=''
+  #                 state=''
+  #                 postal-code=''/>
+  #    </person>
+  #</people>
+
+  10.times do
+
+    people = Xampl.transaction("random-people") do
+      Person.find_by_query do | q |
+        q.add_condition('city', :equals, 'TORONTO')
+        q.add_condition('email', :ends_with, 'dodgit.com')
+
+        q.order_by('surname', :strasc)
+      end
+    end
+
+    first_person = people.first
+    address = first_person.address.first
+
+    start_at = Time.now
+
+    people_at_address = Xampl.transaction("random-people") do
+      Xampl.find_mentions_of(address)
+    end
+
+    done = Time.now
+    puts "found #{ people_at_address.size } people at that address in: #{ done - start_at }, #{ people_at_address.size / (done - start_at) }/s"
+#    people_at_address.each { | person | puts person.pp_xml }
+  end
+end

data/examples/random-people-shared-addresses/find-people-by-address.rb

@@ -0,0 +1,104 @@
+
+require 'xampl_generated_code/RandomPeople'
+require 'people'
+require 'settings'
+
+module RandomPeople
+
+  #<people pid=''
+  #        xmlns="http://xampl.com/people">
+  #    <person pid=''
+  #            given-name=''
+  #            surname=''
+  #            email=''
+  #            phone=''>
+  #        <address pid=''
+  #                 street-address=''
+  #                 city=''
+  #                 state=''
+  #                 postal-code=''/>
+  #    </person>
+  #</people>
+
+  times = [0, 0]
+  counts = [0, 0]
+
+  10.times do | trial |
+    found1 = []
+    found2 = []
+    found3 = []
+
+    #<p:person email='Edelmira.K.Abshire@dodgit.com'
+    #          given-name='Edelmira'
+    #          phone='416-279-8804'
+    #          pid='person-29944'
+    #          surname='Abshire'
+    #          xmlns:p='http://xampl.com/people'>
+    #  <p:address city='TORONTO'
+    #             pid='person-19944'
+    #             postal_code='M1P 4W2'
+    #             state='ON'
+    #             street_address='4194 Borough Drive'/></p:person>
+
+
+    all_people = nil
+    people_inspected = 0
+    start_at = Time.now
+
+    people = Xampl.transaction("random-people") do
+      addresses = Address.find_by_query do | q |
+        q.add_condition('street-address', :equals, '4194 Borough Drive')
+        q.add_condition('postal-code',    :equals, 'M1P 4W2')
+      end
+
+      all_people = Set.new
+      people_inspected = 0
+
+      addresses.each do | address |
+        people = Person.find_by_query do | q |
+          # TODO -- want to be able to find people by the address directly, e.g. address.find_by_citation/find_by_mention & find_by_reference
+          q.add_condition('city',  :equals, address.city)
+          q.add_condition('state', :equals, address.state)
+        end
+
+        people_inspected += people.size
+
+        people.each do | person |
+          all_people << person if person.address.first == address
+        end
+      end
+    end
+
+    done_at = Time.now
+    puts "done in: #{ done_at - start_at }, #{ people_inspected } people inspected, #{ all_people.size } identified"
+    times[0] += (done_at - start_at) if 0 < trial
+    counts[0] += 1 if 0 < trial
+
+    start_at = Time.now
+
+    people = Xampl.transaction("random-people") do
+      addresses = Address.find_by_query do | q |
+        q.add_condition('street-address', :equals, '4194 Borough Drive')
+        q.add_condition('postal-code',    :equals, 'M1P 4W2')
+      end
+
+      all_people = Set.new
+      people_inspected = 0
+
+      addresses.each do | address |
+        people = Xampl.find_mentions_of(address)
+
+        people_inspected += people.size
+        all_people.merge(people)
+      end
+    end
+
+    done_at = Time.now
+    puts "done in: #{ done_at - start_at }, #{ people_inspected } people inspected, #{ all_people.size } identified"
+    times[1] += (done_at - start_at) if 0 < trial
+    counts[1] += 1 if 0 < trial
+  end
+
+  puts "0) total time: #{ times[0] }, count: #{ counts[0] }, average/s: #{ counts[0]/times[0]}"
+  puts "1) total time: #{ times[1] }, count: #{ counts[1] }, average/s: #{ counts[1]/times[1]}"
+end