kangaroo 0.0.1.pre

data/.gitignore

@@ -0,0 +1 @@
+.yardoc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.yardopts

@@ -0,0 +1,6 @@
+--no-private
+-
+docs/Installation.md
+docs/Usage.md
+LICENSE
+README.md

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    kangaroo (0.0.1)
+      activerecord (>= 3.0.0)
+      activesupport (>= 3.0.0)
+      rapuncel (~> 0.0.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.3)
+    arel (2.0.7)
+    builder (2.1.2)
+    columnize (0.3.2)
+    cucumber (0.10.0)
+      builder (>= 2.1.2)
+      diff-lcs (~> 1.1.2)
+      gherkin (~> 2.3.2)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
+    diff-lcs (1.1.2)
+    gherkin (2.3.3)
+      json (~> 1.4.6)
+    i18n (0.5.0)
+    json (1.4.6)
+    linecache (0.43)
+    nokogiri (1.4.4)
+    rapuncel (0.0.2)
+      activesupport (>= 3.0.0)
+      nokogiri
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    term-ansicolor (1.0.5)
+    tzinfo (0.3.24)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cucumber
+  kangaroo!
+  rspec
+  ruby-debug
+  yard

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010-2011 ['Marian Theisen', 'Michael Eickenberg']
+
+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/README.md

@@ -0,0 +1,65 @@
+Kangaroo
+========
+
+Overview
+--------
+
+Kangaroo is an OpenObject client/wrapper for Rails 3, based on ActiveModel. It provides CRUD access to OpenERP objects via XMLRPC.
+It's fast and provides default data for new objects.
+
+Installation
+------------
+
+If you're on Rails 3, just add Kangaroo to your Gemfile:
+
+    gem 'kangaroo'
+
+And create a **kangaroo.yml** configuration file in **[RAILS\_ROOT]/config**, containing these options:
+
+    host: 127.0.0.1
+    port: 8069
+
+    database:
+      name: my_openerp
+      user: admin
+      password: admin
+
+      models:
+        - account.*
+        - product.*
+        - res.company
+
+Adjust your connection and database settings and specify the models you need.
+
+Usage
+-----
+
+OpenObject models are mapped to ruby classes:
+
+    Oo::Res::Country
+    # represents 'res.country'
+    
+    Oo::Product::Product
+    # represents 'product.product'
+    
+    Oo::Sale::Order::Line
+    # represents 'sale.order.line
+    
+You can use this models like ActiveRecord models:
+
+    country = Oo::Res::Country.find 1
+    country = Oo::Res::Country.where(:code => 'DE').first
+    
+    country.name = "Schland"
+    country.save
+    
+    country.reload
+    
+    countries = Oo::Res::Country.limit(100).all
+    countries = Oo::Res::Country.limit(100).order('code').all
+    
+    Oo::Res::Country.create :code => 'DE', :name => 'Germany'
+    
+etc.
+Please refer to {file:docs/Usage.md Usage} to learn about limitations/features not yet
+implemented.

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+#TODO: sdoc
+desc 'Generate KangARoo rdoc.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'KangARoo'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rspec/core/rake_task'
+  desc 'Run RSpec suite.'
+  RSpec::Core::RakeTask.new('spec')
+rescue LoadError
+  puts "RSpec is not available. In order to run specs, you must: gem install rspec"
+end
+
+begin
+  require 'cucumber/rake/task'
+  desc "Run Cucumber features."
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts "Cucumber is not available. In order to run features, you must: gem install cucumber"
+end
+
+
+
+# If you want to make this the default task
+task :default => :spec

data/config/kangaroo.yml.sample

@@ -0,0 +1,12 @@
+host: 127.0.0.1
+port: 8069
+
+database:
+  name: my_openerp
+  user: admin
+  password: admin
+  
+  models:
+    - account.*
+    - product.*
+    - res.company

data/docs/AdditionalServices.md

@@ -0,0 +1,3 @@
+Additional Services
+===================
+

data/docs/Architecture.md

@@ -0,0 +1,50 @@
+Architecture
+============
+
+#### Index
+{file:README.md Readme}
+{file:docs/Installation.md Installation}
+{file:docs/Usage.md Usage}
+{file:docs/Architecture.md Architecture}
+{file:docs/AdditionalServices.md Additional Services}
+
+
+Components
+----------
+Kangaroo mainly consists of 3 parts:
+
+  * **Util** contains everything needed to establish and use a connection to an OpenERP server.
+    Use {Kangaroo::Util::Configuration} to configure a connection to a database, and
+    {Kangaroo::Util::Loader} to load the models you need.
+  * **RubyAdapyer** is a mini-framework to convert OpenObject models to ruby. It's responsible 
+    of creating the neccessary modules and classes to use i.e. the "product.product" model
+    via Oo::Product::Product
+  * **Model** is the base class for all OpenObject models, and is responsible for all runtime
+    behavior.
+    
+
+
+Communication
+-------------
+
+### Proxies
+The lowest level of communication happens over {Kangaroo::Util::Proxy} and its subclasses. They
+proxy method calls to the XML-RPC services the OpenERP server provides.
+
+### OpenObject ORM
+Suppose you have a Ruby model for an OpenObject model **Oo::Res::Country** (either via directly subclassing {Kangaroo::Model::Base},
+or via {Kangaroo::Util::Loader}), you can access the OpenObject ORM API directly:
+
+    Oo::Res::Country.search(...)
+    Oo::Res::Country.read(...)
+    Oo::Res::Country.fields_get(...)
+    Oo::Res::Country.default_get(...)
+    Oo::Res::Country.unlink(...)
+    
+The **create** and **write** are named **create\_record** and **write\_record**
+
+    Oo::Res::Country.create_record(...)
+    Oo::Res::Country.write_record(...)
+    
+### ActiveRecord-ish ORM
+see {file:docs/Usage.md Usage}

data/docs/Installation.md

@@ -0,0 +1,73 @@
+Installation
+============
+
+#### Index
+{file:README.md Readme}
+{file:docs/Installation.md Installation}
+{file:docs/Usage.md Usage}
+{file:docs/Architecture.md Architecture}
+{file:docs/AdditionalServices.md Additional Services}
+
+Rails 3
+-------
+If you're on Rails 3, just add Kangaroo to your Gemfile:
+
+    gem 'kangaroo'
+    
+And run
+    
+    bundle install
+
+Create a **kangaroo.yml** configuration file in **[RAILS\_ROOT]/config**, containing these options:
+
+    host: 127.0.0.1
+    port: 8069
+
+    database:
+      name: my_openerp
+      user: admin
+      password: admin
+
+      models:
+        - account.*
+        - product.*
+        - res.company
+
+Adjust your connection and database settings, specify the models you wish to get loaded, and you're good to go!
+Checkout the usage doc {file:docs/Usage.md Usage}
+
+General Ruby
+------------
+Install the gem via
+
+    gem install kangaroo
+    
+Now you need to configure Kangaroo. You can either use a YAML configuration file (see **Rails 3**) or
+pass a Hash with configuration options.  
+  
+via file
+
+    config = Kangaroo::Util::Configuration.new 'some_config_file.yml'
+    config.load_models
+    
+    
+via Hash
+
+    config_hash = {
+      :host => 'localhost',
+      :port => 8069,
+      
+      :database => {
+        :name => 'my_openerp',
+        :user => 'admin',
+        :password => 'admin',
+        
+        :models => %w(account.* product.* res.company)
+      }
+    }
+    
+    config = Kangaroo::Util::Configuration.new config_hash
+    config.load_models
+
+The connection should be setup now, and the models ready to use.
+

data/docs/Usage.md

@@ -0,0 +1,161 @@
+Usage
+=====
+
+#### Index
+{file:README.md Readme}
+{file:docs/Installation.md Installation}
+{file:docs/Usage.md Usage}
+{file:docs/Architecture.md Architecture}
+{file:docs/AdditionalServices.md Additional Services}
+
+Basics
+------
+Kangaroo-wrapped OpenObject models provides an ActiveRecord-ish API to find, create and update records.
+But please keep in mind, that due to the fundamental differences between a SQL database and the OpenObject
+ORM / XML-RPC service. And some things we're saving up for upcoming versions.
+
+### Querying
+#### Find
+The most basic query method, as in ActiveRecord is {Kangaroo::Model::Finder#find find}, wich reads record(s)
+by id(s):
+
+    Oo::Res::Country.find 1
+    # => <Oo::Res::Country id: 1 ....>
+    
+    Oo::Res::Country.find [1, 2]
+    # => [<Oo::Res::Country id: 1 ....>, <Oo::Res::Country id: 2 ....>]
+    
+Additionally the classic keywords for *find* can be used:
+
+    Oo::Res::Country.find :first
+    Oo::Res::Country.find :last
+    Oo::Res::Country.find :all
+    
+#### First / All / Last
+Shorter than *find(keyword)* are definitely {Kangaroo::Model::Finder#first first}, {Kangaroo::Model::Finder#all all}, {Kangaroo::Model::Finder#last last}:
+
+    Oo::Res::Country.first
+    Oo::Res::Country.last
+    Oo::Res::Country.all
+
+#### Relation-like querying
+Kangaroo somewhat tries to emulate ActiveRecords great ARel query interface, so you can specify
+conditions via **where**:
+
+    Oo::Res::Country.where(:code => 'DE').first
+    # => <Oo::Res::Country id: 42, code: 'DE', name: 'Germany'>
+    
+**limit** and **offset**:
+
+    Oo::Res::Country.offset(10).limit(2).all
+    # => [<Oo::Res::Country id: 11 ....>, <Oo::Res::Country id: 12 ....>]
+    
+**context**:
+
+    Oo::Res::Country.context(:lang => 'de_DE').first
+    # => <Oo::Res::Country id: 42, code: 'DE', name: 'Deutschland'>
+    
+read only some fields with **select**:
+
+    Oo::Res::Country.select('code').first
+    # => <Oo::Res::Country id: 42, code: 'DE', name: nil>
+    
+order the results with **order**:
+
+    Oo::Res::Country.order(:name).all
+    
+    # Or if you wish descending order
+    Oo::Res::Country.order(:name, true).all
+    
+additionally, there is **reverse**, which reverses all prior **order** clauses 
+(or adds an **order('id', true)**)
+
+    Oo::Res::Country.reverse.all
+    # => [<Oo::Res::Country id: 245 ....>, <Oo::Res::Country id: 244 ....>]
+
+#### A note about "*where*"
+The OpenObject ORM expects conditions as an Array like this:
+
+    Oo::Res::Country.where(['code', '=', 'DE']).first
+    
+As this can be quite cumbersome to use, Kangaroo accepts conditions as Strings, which will simply be
+splitted in an Array
+
+    Oo::Res::Country.where('a = one').first
+    
+This implies that you can't specify complex conditions via Strings, this is only to simplify simple conditions.
+As shown before, also Hash conditions work:
+
+    Oo::Res::Country.where(:code => 'DE').first
+    
+    # Or if you use an Array Kangaroo will switch to the **in** operator
+    Oo::Res::Country.where(:code => ['DE', 'EN']).all 
+    
+    
+### Working with records
+#### Attributes
+All OpenObject fields are accessible via getters and setters:
+
+    record = Oo::Res::Country.where(:code => 'DE').first
+    record.name
+    # => "Germany"
+
+    record.name = "Dschoermany"
+    record.name
+    # => "Dschoermany"
+    
+Of course those attributes can be persisted
+
+    record.save
+    record.reload
+    record.name
+    # => "Dschoermany"
+    
+#### Dirty
+Kangaroo includes ActiveModel::Dirty to keep track of changes:
+
+    record = Oo::Res::Country.where(:code => 'DE').first
+    record.name
+    # => "Germany"
+
+    record.name = "Dschoermany"
+    record.changed?
+    # => true
+    
+    record.name_was
+    # => "Germany"
+    
+#### Creating records
+If you initialize a new record, Kangaroo fetches the default values for this model
+
+    record = Oo::Res::User.new
+    record.context_lang
+    # => 'en_US'
+    record.context_lang_changed?
+    # => true
+
+#### Destroying records
+
+    Oo::Res::User.first.destroy
+    
+    
+#### Misc
+Kangaroo also supports
+
+##### new\_record? / persisted?
+
+    record = Oo::Res::User.new
+    record.new_record?
+    # => true
+    
+    record.persisted?
+    # => false
+    
+##### destroyed?
+
+    record = Oo::Res::Country.first
+    record.destroy
+    record.destroyed?
+    # => true
+
+