git-ds 0.9.2

data/lib/git-ds/index.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::Index
+=begin rdoc
+Wrapper for Grit::Index
+
+Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'rubygems'
+require 'grit'
+require 'fileutils'
+
+require 'git-ds/shared'
+
+module GitDS
+
+# =============================================================================
+=begin rdoc
+A Git Index.
+=end
+  class Index < Grit::Index
+
+=begin rdoc
+Write index to the object db, then read the object DB into the GIT staging
+index. Returns SHA of new tree.
+=end
+    def write
+      sha = local_write_tree(self.tree, self.current_tree)
+      sha
+    end
+
+=begin rdoc
+Re-implemented from Grit. Grit adds a trailing / to directory names, which
+makes it impossible to delete Tree objects!
+=end
+    def local_write_tree(tree, now_tree=nil)
+      tree_contents = {}
+      now_tree.contents.each do |obj|
+        sha = [obj.id].pack("H*")
+        k = obj.name
+        tree_contents[k] = "%s %s\0%s" % [obj.mode.to_s, obj.name, sha]
+      end if now_tree
+
+      tree.each do |k, v|
+        case v
+          when String
+            sha = write_blob(v)
+            sha = [sha].pack("H*")
+            str = "%s %s\0%s" % ['100644', k, sha]
+            tree_contents[k] = str
+          when Hash
+            ctree = now_tree/k if now_tree
+            sha = local_write_tree(v, ctree)
+            sha = [sha].pack("H*")
+            str = "%s %s\0%s" % ['40000', k, sha]
+            tree_contents[k] = str
+          when false
+            tree_contents.delete(k)
+        end
+      end
+
+      tr = tree_contents.sort.map { |k, v| v }.join('')
+      self.repo.git.put_raw_object(tr, 'tree')
+    end
+
+=begin rdoc
+Add a DB entry at the virtual path 'path' with contents 'contents'
+=end
+    alias :add_db :add
+
+    def add(path, data, on_fs=false)
+      super(path, data)
+      add_fs_item(path, data) if on_fs
+    end
+
+=begin rdoc
+Convenience function to add an on-filesystem object.
+=end
+    def add_fs(path, data)
+      add(path, data, true)
+    end
+
+=begin rdoc
+Wrapper for Grit::Index#delete that removes the file if it exists on the
+filesystem.
+=end
+    def delete(path)
+      super
+      @repo.exec_in_git_dir {
+        ::FileUtils.remove_entry(path) if ::File.exist?(path)
+      }
+    end
+
+    private
+
+=begin rdoc
+Add a DB entry at the filesystem path 'path' with contents 'contents'
+=end
+    def add_fs_item( path, data )
+      fs_path = @repo.top_level + ::File::SEPARATOR + path
+      make_parent_dirs(fs_path)
+
+      # Create file in filesystem
+      @repo.exec_in_git_dir { ::File.open(fs_path, 'w') {|f| f.write(data)} }
+    end
+
+=begin rdoc
+Add parent directories as-needed to create 'path' on the filesystem.
+=end
+    def make_parent_dirs(path)
+      tmp_path = ''
+
+      ::File.dirname(path).split(::File::SEPARATOR).each do |dir|
+        next if dir.empty?
+        tmp_path << ::File::SEPARATOR << dir
+        Dir.mkdir(tmp_path) if not ::File.exist?(tmp_path)
+      end
+    end
+
+  end
+
+=begin rdoc
+Index object for the Git staging index.
+=end
+  class StageIndex < Index
+
+    attr_reader :sha
+    attr_reader :parent_commit
+
+=begin rdoc
+=end
+    def initialize(repo,treeish=nil)
+      super(repo)
+      @parent_commit = repo.commits(repo.current_branch, 1).first
+      treeish = (@parent_commit ? @parent_commit.tree.id : 'master') if \
+                not treeish
+      read_tree(treeish)
+      @sha = self.current_tree.id
+    end
+
+=begin rdoc
+=end
+    def commit(msg, author=nil)
+      last_tree = @parent_commit ? @parent_commit.tree.id : nil
+      parents = @parent_commit ? [@parent_commit] : []
+      # TODO : why does last_tree cause some commits to fail?
+      #          test_transaction(TC_GitDatabaseTest)
+      #          transaction commit has wrong message.
+      #          <"SUCCESS"> expected but was <"auto-commit on transaction">
+      #        Possible bug in Grit::last_tree?
+      #sha = super(msg, parents, author, last_tree, @repo.current_branch)
+      sha = super(msg, parents, author, nil, @repo.current_branch)
+      if sha
+        @parent_commit = @repo.commit(sha)
+        read_tree(@parent_commit.tree.id)
+      end
+      sha
+    end
+
+=begin rdoc
+Write tree object for index to object database.
+=end
+    def write
+      @sha = super
+    end
+
+=begin rdoc
+Write, read tree. Done when a tree is requested.
+=end
+    def build
+      return @sha if self.tree.empty?
+      self.read_tree(self.write)
+    end
+
+    def read_tree(sha)
+      super
+    end
+
+=begin rdoc
+Sync with staging index. This causes the Git index (used by command-line tools)
+to be filled with the contents of this index.
+
+This can be instead of a commit to ensure that command-line tools can access
+the index contents.
+=end
+    def sync
+      self.build
+      @repo.exec_in_git_dir { `git read-tree #{@sha}` }
+    end
+
+=begin rdoc
+Read staging index from disk and create a StagingIndex object for it.
+
+This can be used to access index contents created by command-line tools.
+=end
+    def self.read(repo)
+      sha = repo.exec_in_git_dir{`git write-tree`}.chomp
+      new(repo, sha)
+    end
+
+  end
+
+
+end
+

data/lib/git-ds/model.rb

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::Model
+=begin rdoc
+
+Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'git-ds/shared'
+require 'git-ds/config'
+require 'git-ds/model/property'
+require 'git-ds/model/item'
+require 'git-ds/model/db_item'
+require 'git-ds/model/fs_item'
+require 'git-ds/model/item_list'
+require 'git-ds/model/item_proxy'
+require 'git-ds/model/root'
+
+# TODO: REFACTOR to act as delegate for database
+
+# TODO: register ModelItemClass name, e.g. 'user', with model.
+#       then to instantiate, get item name from path, e.g.
+#       system/1/user/1 would be 'user'
+#       ...and use that to determine class to instantiate.
+# TODO: query/find/grep (search of object contents or paths)
+
+module GitDS
+
+=begin rdoc
+A data model.
+=end
+  class Model
+
+=begin rdoc
+The Root item for the Model. 
+=end
+    attr_reader :root
+
+=begin rdoc
+The database connection for the model. This is expected to be a GitDS::Database
+object.
+=end
+    attr_reader :db
+
+=begin rdoc
+The name of the model. This is only used for storing configuration variables.
+=end
+    attr_reader :name
+
+    def initialize(db, name='generic', root=nil)
+      @db = db
+      @root = root ? root : RootItem.new(self)
+      @name = name
+    end
+
+=begin rdoc
+Provides access to the Hash of Model-specific config variables.
+=end
+    def config
+      @git_config ||= RepoConfig.new(@db, 'model-' + @name)
+    end
+
+=begin rdoc
+Returns true if Model contains path.
+=end
+    def include?(path)
+      @db.include? path
+    end
+
+    alias :exist? :include?
+
+=begin rdoc
+List children (filenames) of path. Returns [] if path is not a directory.
+=end
+    def list_children(path=root.path)
+      @db.list(path).keys.sort
+    end
+
+=begin rdoc
+Add an item to the object DB.
+=end
+    # Might be better as add child?
+    def add_item(path, data)
+      # note: @db.add uses exec {} so there is no need to here.
+      @db.add(path, data)
+    end
+
+=begin rdoc
+Add an item to the object DB and the filesystem.
+=end
+    def add_fs_item(path, data)
+      # note: @db.add uses exec {} so there is no need to here.
+      @db.add(path, data, true)
+    end
+
+=begin rdoc
+Return the contents of the BLOB at path.
+=end
+    def get_item(path)
+      @db.object_data(path)
+    end
+
+=begin rdoc
+Delete an item from the object DB (and the filesystem, if it exists).
+=end
+    def delete_item(path)
+      # note: @db.delete uses exec {} so there is no need to here.
+      @db.delete(path)
+    end
+
+=begin rdoc
+Execute block as a database ExecCmd.
+=end
+    def exec(&block)
+      @db.exec(&block)
+    end
+
+=begin rdoc
+Execute block as a database transaction.
+=end
+    def transaction(&block)
+      @db.transaction(&block)
+    end
+
+=begin rdoc
+Execute a transaction in a branch, then merge if it was successful.
+
+See Database#branch_and_merge.
+=end
+    def branched_transaction(name=@db.next_branch_tag(), &block)
+      raise 'Branched transactions cannot be nested' if @db.staging?
+      @db.branch_and_merge(name, &block)
+    end 
+
+  end
+
+end

data/lib/git-ds/model/db_item.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::DbModelItem
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'git-ds/shared'
+require 'git-ds/model/item'
+
+module GitDS
+
+# ----------------------------------------------------------------------
+=begin rdoc
+An in-DB ModelItem mixin. DbModelItems exist only in the database.
+
+Note: this is an instance-method module. It should be included, not extended.
+=end
+  module DbModelItemObject
+    include ModelItemObject
+  end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Note: this is a class-method module. It should be extended in a class, not 
+included.
+=end
+  module DbModelItemClass
+    include ModelItemClass
+
+  end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Base class for DB-only ModelItem objects. These do not appear in the filesystem.
+=end
+  class ModelItem
+    extend DbModelItemClass
+    include DbModelItemObject
+  end
+
+end

data/lib/git-ds/model/fs_item.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::FsModelItem
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'git-ds/shared'
+require 'git-ds/model/item'
+
+module GitDS
+
+# ----------------------------------------------------------------------
+=begin rdoc
+A filesystem ModelItem mixin. FsModelItems exist both on the filesystem and 
+in the database.
+
+Note: this is an instance-method module. It should be included, not extended.
+=end
+  module FsModelItemObject
+    include ModelItemObject
+  end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Note: this is a class-method module. It should be extended in a class, not 
+included.
+=end
+  module FsModelItemClass
+    include ModelItemClass
+
+=begin rdoc
+Define a property for this ModelItem class. The property will exist in the
+DB and on the filesystem.
+=end
+    def property(name, default=0, &block)
+      define_fs_property(name, default, &block)
+    end
+
+  end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Base class for filesystem ModelItem objects.
+=end
+  class FsModelItem
+    extend FsModelItemClass
+    include FsModelItemObject
+  end
+
+end

data/lib/git-ds/model/item.rb

@@ -0,0 +1,428 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::ModelItem
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+
+Notes:
+The children of an item will be one of the following:
+  * A Property (a named BLOB containing a value)
+  * A ModelItem (a subdirectory that defines a ModelItem instance)
+  * A ModelItem link (a named BLOB containing a path to a ModelItem instance)
+Note that ModelItems and ModelItemLinks will be in a subdirectory named for
+the ModelItem, even if there is only a single entry.
+=end
+
+require 'time'  # for timestamp proprties
+require 'git-ds/shared'
+require 'git-ds/model/property'
+
+module GitDS
+
+  class InvalidModelItemError < RuntimeError
+  end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+ModelItem class methods.
+
+Note: this is a class-method module. It should be extended in a class, not 
+included.
+=end
+  module ModelItemClass
+
+=begin rdoc
+The name of the ModelItemClass in the database.
+
+To be overridden by a modelitem class.
+=end
+    def name(name=nil)
+      @name ||= nil
+      raise 'ModelItemClass has no name defined' if (not name) && (not @name)
+      name ? @name = name : @name
+    end
+
+=begin rdoc
+Return the path to the ModelItem class owned by the specified parent.
+
+For example, given the following database:
+
+  ClassA/a1/ClassB/b1
+  ClassA/a1/ClassB/b2
+  ClassA/a2/ClassB/b3
+
+ClassA.path(@model.root) will return 'ClassA', ClassB.path(a1) will return 
+'ClassA/a1/ClassB', and ClassB.path(a2) will return 'ClassA/a2/ClassB'.
+=end
+    def path(parent)
+      return name if not parent
+      build_path(parent.path)
+    end
+
+=begin rdoc
+Return the path to the ModelItem class inside the specified directory.
+=end
+    def build_path(parent_path)
+      return name if (not parent_path) || parent_path.empty?
+      parent_path + ::File::SEPARATOR + name
+    end
+
+=begin rdoc
+Return the path to an instance of the object under parent_path.
+=end
+    def instance_path(parent_path, ident)
+      path = build_path(parent_path)
+      path += ::File::SEPARATOR if not path.empty?
+      path += ident.to_s
+    end
+
+=begin rdoc
+List all children of this ModelItem class.
+
+This will list all instances of the class owned by the specified parent.
+For example, given the following database:
+
+  ClassA/a1/ClassB/b1
+  ClassA/a1/ClassB/b2
+  ClassA/a2/ClassB/b3
+
+ClassA.list(@model.root) will return [a1, a2], ClassB.list(a1) will return 
+[b1, b2], and ClassB.list(a2) will return [b3].
+=end
+    def list(parent)
+      list_in_path parent.model, parent.path
+    end
+
+=begin rdoc
+List all children of the ModelItem class inside parent_path.
+=end
+    def list_in_path(model, parent_path)
+      model.list_children build_path(parent_path)
+    end
+
+=begin rdoc
+Generate an ident from a Hash of arguments.
+
+To be overridden by a modelitem class.
+=end
+    def ident(args)
+      args[ident_key()].to_s
+    end
+
+=begin rdoc
+The key containing the object ident in the args Hash passed to create.
+
+This can be used to change the name of the ident key in the hash without
+having to override the ident method.
+=end
+    def ident_key
+      :ident
+    end
+
+=begin rdoc
+Create a new instance of the ModelItemClass owned by the specified parent.
+
+This will create a subdirectory under ModelItemClass.path(parent); the name
+of the directory is determined by ModelItemClass.ident.
+
+For example, given the following database:
+
+  ClassA/a1/ClassB/b1
+  ClassA/a1/ClassB/b2
+  ClassA/a2/ClassB/b3
+
+ModelItemClass.create(a2, { :ident => 'b4' } ) will create the directory
+'ClassA/a2/ClassB/b4'.
+
+The directory will then be filled by calling ModelItemClass.fill.
+
+Note that this returns the path to the created item, not an instance.
+=end
+    def create(parent, args={})
+      raise "Use Database.root instead of nil for parent" if not parent
+      raise "parent is not a ModelItem" if not parent.respond_to? :model
+
+      model = parent.model
+      create_in_path(parent.model, parent.path, args)
+    end
+
+=begin rdoc
+Create a new instance of the ModelItemClass in the specified directory.
+
+This will create a subdirectory under parent_path; the name of the directory 
+is determined by ModelItemClass.ident.
+
+For example, given the following database:
+
+  ClassA/a1/ClassB/b1
+  ClassA/a1/ClassB/b2
+  ClassA/a2/ClassB/b3
+
+ModelItemClass.create(a2, { :ident => 'b4' } ) will create the directory
+'ClassA/a2/ClassB/b4'.
+
+The directory will then be filled by calling ModelItemClass.fill.
+
+The creation of the objects in the model takes place within a DB transaction.
+If this is called from within a transaction, it will use the existing staging
+index; otherwise, it will create a new index and auto-commit on success.
+
+Note that this returns the ident of the created item, not an instance.
+=end
+    def create_in_path(model, parent_path, args)
+      id = ident(args)
+      item_path = build_path(parent_path) + ::File::SEPARATOR + id
+
+      # Ensure that nested calls (e.g. to create children) share index#write
+      cls = self
+      model.transaction {
+        propagate
+        cls.fill(model, item_path, args)
+      }
+
+      item_path
+    end
+
+=begin rdoc
+Create all subdirectories and files needed to represent a ModelItemClass
+instance in the object repository.
+
+item_path is the full path to the item in the model.
+args is a hash of arguments used to construct the item.
+
+Can be overridden by ModelItem classes and invoked via super.
+=end
+    def fill(model, item_path, args)
+      fill_properties(model, item_path, args)
+    end
+
+=begin rdoc
+Fill all properties either with their value in 'args' or their default value.
+
+Foreach key in properties,
+  if args.include?(key) && property.valid?(key, args[key])
+     set property to key
+  elsif properties[key].default
+     set property to default
+  else ignore
+=end
+    def fill_properties(model, item_path, args)
+      hash = properties
+      hash.keys.each do |key|
+        prop = hash[key]
+        if args.include?(key)
+          prop.set(model, item_path, args[key])
+        elsif hash[key].default
+          prop.set(model, item_path, prop.default)
+        end
+      end
+    end
+
+=begin rdoc
+Define a property for this ModelItem class.
+=end
+    def define_db_property(name, default=0, &block)
+      add_property PropertyDefinition.new(name, default, false, &block)
+    end
+
+=begin rdoc
+Define an on-filesystem property for this ModelItem class.
+=end
+    def define_fs_property(name, default=0, &block)
+      add_property PropertyDefinition.new(name, default, true, &block)
+    end
+
+=begin rdoc
+Define a Property for this ModelItem class. The property will be DB-only.
+
+This can be overridden to change how properties are stored.
+=end
+    def property(name, default=0, &block)
+      define_db_property(name, default, &block)
+    end
+
+=begin rdoc
+Define a property that is a link to a ModelItem object.
+
+Note: this is a link to a single ModelItem class. For a list of links to
+ModelItems, use a ModelItem List of ProxyModelItemClass objects.
+=end
+    def link_property(name, cls, &block)
+      add_property ProxyProperty.new(name, cls, false, &block)
+    end
+      
+
+=begin rdoc
+Hash of properties associated with this MOdelItem class.
+=end
+    def properties
+      @properties ||= {}
+    end
+
+    private
+
+=begin rdoc
+Add a property to the properties Hash. This throws GitDS::DuplicatePropertyError
+if a property with the same name already exists in the class.
+=end
+    def add_property(p)
+      hash = properties
+      raise DuplicatePropertyError.new(p.name) if hash.include? p.name
+      hash[p.name] = p
+    end
+  end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Instance methods used by repo-backed objects.
+
+Note: this is an instance-method module. It should be included, not extended.
+=end
+  module ModelItemObject
+
+=begin rdoc
+The GitDS::Model that contains the object.
+=end
+    attr_reader :model
+
+    def initialize(model, path)
+      @model = model
+      @path = path
+      @ident = ::File.basename(path)
+    end
+
+=begin rdoc
+Full path to this item in the repo.
+=end
+    def path
+      ensure_valid
+      @path
+    end
+
+=begin rdoc
+Primary key (ident) for instance.
+=end
+    def ident
+      ensure_valid
+      @ident
+    end
+
+=begin rdoc
+Return list of property names.
+=end
+    def properties
+      self.class.properties.keys.sort
+    end
+
+=begin rdoc
+Return Hash of cached property values.
+=end
+    def property_cache
+      ensure_valid
+      @property_cache ||= {}
+    end
+
+=begin rdoc
+Return the value of a specific property. If the proprty has not been set,
+nil is returned.
+
+ModelItem classes will generally write property accessors that wrap the
+call to this method.
+=end
+    def property(name)
+      ensure_valid
+      return property_cache[name] if property_cache.include? name
+      prop = self.class.properties[name]
+      raise "No such property #{name}" if not prop
+      property_cache[name] = prop.get(@model, @path)
+    end
+
+=begin rdoc
+Convenience method for reading Integer properties.
+=end
+    def integer_property(name)
+      val = property(name)
+      val ? property_cache[name] = val.to_i : nil
+    end
+
+=begin rdoc
+Convenience method for reading Float properties.
+=end
+    def float_property(name)
+      val = property(name)
+      val ? property_cache[name] = val.to_f : nil
+    end
+
+=begin rdoc
+Convenience method for reading Time (aka timestamp) properties.
+=end
+    def ts_property(name)
+      val = property(name)
+      val && (! val.empty?) ? property_cache[name] = Time.parse(val) : nil
+    end
+
+=begin rdoc
+Convenience method for reading Boolean properties.
+=end
+    def bool_property(name)
+      val = property(name)
+      (val && val == 'true')
+    end
+
+=begin rdoc
+Convenience method for reading Array properties.
+
+Note that this returns an Array of Strings.
+
+Note: the default delimiter is what Property uses to encode Array objects.
+Classes which perform their own encoding can choose a different delimiter.
+=end
+    def array_property(name, delim="\n")
+      val = property(name)
+      val ? (property_cache[name] = val.split(delim)) : nil
+    end
+
+=begin rdoc
+Set the value of a specific property.
+
+ModelItem classes will generally write property accessors that wrap the
+call to this method.
+=end
+    def set_property(name, data)
+      ensure_valid
+      prop = self.class.properties[name]
+      raise "No such property #{name}" if not prop
+      property_cache[name] = prop.set(@model, @path, data)
+    end
+
+=begin rdoc
+=end
+    def delete
+      ensure_valid
+      @model.delete_item(@path)
+      # invalidate object
+      @path = nil
+    end
+
+=begin rdoc
+Return true if item is valid, false otherwise.
+=end
+    def valid?
+      @path   # an invalid item has a nil path
+    end
+
+    protected
+
+=begin rdoc
+Raises an InvalidModelItemError if item is not valid.
+
+Note: accessors for non-property children should invoke this before 
+touching the object.
+=end
+    def ensure_valid
+      raise InvalidModelItemError if not valid?
+    end
+
+  end
+
+end