git-ds 0.9.2

data/doc/examples/user_group/model.rb

@@ -0,0 +1,265 @@
+#!/usr/bin/env ruby
+# :title: GitDS Model Example: User/Group
+=begin rdoc
+<i>Copyright 2011 Thoughtgang <http://www.thoughtgang.org></i>
+
+This example demonstrates a simple hierarchical data model for managing 
+unix-style users and groups.
+
+Note: This is not intended as a serious implementation of an auth system. It is
+intended only to illustrate the use of a hierarchical database using a
+familiar data model.
+
+==Usage
+
+An example of the usage of this model can be found in the following script:
+
+    doc/examples/user_group/test.rb
+
+This script can be run to generate an example Git-DS repository:
+
+    bash$ doc/examples/user_group/test.rb
+    bash$ cd ug_test.db && qgit &
+
+The following command-line utilities are provided for manipulating this 
+data model:
+
+    doc/examples/user_group/ug_add_group.rb
+    doc/examples/user_group/ug_add_group_user.rb
+    doc/examples/user_group/ug_add_user.rb
+    doc/examples/user_group/ug_init.rb
+    doc/examples/user_group/ug_list.rb
+
+
+===Initialize a TestSuite database
+
+  # connect the model, creating it if necessary
+  model = UserGroupModel.new(GitDS::Database.connect('ug_test.db', true))
+
+===Add a user
+
+  u = model.add_user(username, id, fullname)
+
+===Add a group
+
+  g = model.add_group(username, id, owner_name)
+
+  # add user to group
+  u = model.user(username)
+  g.add_user(u)
+
+=end
+
+require 'git-ds/database'
+require 'git-ds/model'
+
+=begin rdoc
+The model has the following structure in the repo:
+
+   user/                          : FsModelItemClass
+   user/$NAME/                    : FsModelItem
+   user/$NAME/id                  : Property
+   user/$NAME/full_name           : Property
+   user/$NAME/created             : Property
+            
+   group/                         : FsModelItemClass
+   group/$NAME/                   : FsModelItem
+   group/$NAME/id                 : Property
+   group/$NAME/owner              : ProxyProperty
+   group/$NAME/users              : ProxyItemList
+=end
+
+class UserGroupModel < GitDS::Model
+  def initialize(db)
+    super db, 'user/group model'
+  end
+
+=begin rdoc
+Add a User to the model.
+=end
+  def add_user(name, id, fullname='')
+    args = {:username => name, :id => id.to_i, :fullname => fullname }
+    UserModelItem.new self, UserModelItem.create(self.root, args)
+  end
+
+=begin rdoc
+Return a list of the usernames of all Users in the model
+=end
+  def users
+    UserModelItem.list(self.root)
+  end
+
+=begin rdoc
+Instantiate a User object based on the username.
+=end
+  def user(ident)
+    UserModelItem.new self, UserModelItem.instance_path(self.root.path, ident)
+  end
+
+=begin rdoc
+Add a Group to the model.
+=end
+  def add_group(name, id, owner_name)
+    owner = user(owner_name)
+
+    args = { :name => name, :id => id.to_i, :owner => owner }
+    GroupModelItem.new self, GroupModelItem.create(self.root, args)
+  end
+
+=begin rdoc
+List the names of all Groups in the model.
+=end
+  def groups
+    GroupModelItem.list(self.root)
+  end
+
+=begin rdoc
+Instantiate a Group object by name.
+=end
+  def group(ident)
+    GroupModelItem.new self, GroupModelItem.instance_path(self.root.path, ident)
+  end
+end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+A User. Users consist of a UNIX-style username, an ID number, a full name,
+and a timestamp marking when they were created.
+=end
+class UserModelItem < GitDS::FsModelItem
+
+  name 'user'
+
+  # properties
+  property(:id, 0) { |p| p.to_s.to_i == p }
+  property(:full_name, '')
+  property(:created)
+
+  # Use :username entry in Hash as primary key
+  def self.ident_key
+    :username
+  end
+
+  def self.fill(model, item_path, args)
+    super
+    properties[:created].set(model, item_path, Time.now.to_s)
+  end
+
+=begin rdoc
+The name of the user, e.g. 'root'.
+=end
+  alias :username :ident
+
+=begin rdoc
+The ID number of the user, e.g. 1000.
+=end
+  def id
+    integer_property(:id)
+  end
+
+  def id=(val)
+    set_property(:id, val)
+  end
+
+=begin rdoc
+The full name of the user, e.g. 'John Q. Public'.
+=end
+  def full_name
+    property(:full_name)
+  end
+
+  def full_name=(val)
+    set_property(:full_name, val)
+  end
+
+=begin rdoc
+The timestamp when the user was created.
+=end
+  def created
+    ts_property(:created)
+  end
+
+end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+A group of users. Groups consist of a UNIX-style name, a numeric ID, and
+owner (a valid User), and a list of members (valid Users).
+=end
+class GroupModelItem < GitDS::FsModelItem
+
+  name 'group'
+
+  # properties
+  property(:id, 0) { |p| p.to_s.to_i == p }
+  link_property(:owner, UserModelItem)
+
+  def initialize(model, path)
+    super
+    @users = GitDS::ProxyItemList.new(UserModelItem, model, path)
+  end
+
+  # Use :name entry in Hash as primary key
+  def self.ident_key()
+    :name
+  end
+
+=begin rdoc
+The name of the group, e.g. 'staff'.
+=end
+  alias :name :ident
+
+=begin rdoc
+The ID of the group, e.g. 1000.
+=end
+  def id
+    integer_property(:id)
+  end
+
+  def id=(val)
+    set_property(:id, val)
+  end
+
+=begin rdoc
+The owner of the group: a link to a User object.
+=end
+  def owner
+    property(:owner)
+  end
+
+  def owner=(u)
+    set_property(:owner, u)
+  end
+
+=begin rdoc
+The names of every User in the group.
+=end
+  def users
+    ensure_valid
+    @users.keys
+  end
+
+=begin rdoc
+Instantiate a User in the group by name.
+=end
+  def user(name)
+    ensure_valid
+    @users[name]
+  end
+
+=begin rdoc
+Add a User to the group. The argument must be a User object.
+=end
+  def add_user(u)
+    ensure_valid
+    @users.add(self, u, true)
+  end
+
+=begin rdoc
+Remove a user from the group, by name.
+=end
+  def del_user(name)
+    ensure_valid
+    @users.delete(name)
+  end
+end

data/doc/examples/user_group/test.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# Test User/Group database example
+# Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+
+BASE=File.dirname(File.expand_path(__FILE__)\
+                 ).split(File::SEPARATOR)[0..-4].join(File::SEPARATOR)
+$: << BASE + File::SEPARATOR + 'lib'
+$: << BASE + File::SEPARATOR + 'doc' + File::SEPARATOR + 'examples'
+
+require 'user_group/model'
+
+# ----------------------------------------------------------------------
+
+def fill_model(model)
+  users = [{ :username => 'root', :id => 1 },
+           { :username => 'admin', :id => 1000, :full_name => 'Administrator'},
+           { :username => 'humpty', :id => 1001, :full_name => 'H Umpty, Esq.'},
+           { :username => 'dumpty', :id => 1002, :full_name => 'Dump Ty'}
+          ]
+  groups = [ { :name => 'wheel', :id => 1, :owner_name => 'root',
+               :members => ['root', 'admin'] },
+             { :name => 'staff', :id => 1000, :owner_name => 'admin',
+               :members => ['admin', 'humpty', 'dumpty'] },
+             { :name => 'twins', :id => 1001, :owner_name => 'humpty',
+               :members => ['humpty', 'dumpty'] }
+           ]
+
+  users.each do |udef|
+    model.add_user(udef[:username], udef[:id], udef[:full_name])
+  end
+
+  groups.each do |gdef|
+    g = model.add_group(gdef[:name], gdef[:id], gdef[:owner_name])
+    gdef[:members].each { |name| g.add_user(model.user(name)) }
+  end
+
+end
+
+# ----------------------------------------------------------------------
+def list_model(model)
+  puts "Users:"
+  model.users.each do |user|
+    u = model.user(user)
+    puts "\t#{u.id}\t#{u.username}\t#{u.created}\t#{u.full_name}"
+  end
+
+  puts "\nGroups:"
+  model.groups.each do |grp|
+    puts "\t#{grp}"
+    g = model.group(grp)
+    puts "\t#{g.id}\t#{g.name}\t#{g.owner.username}\t#{g.users.inspect}"
+  end
+end
+
+# ----------------------------------------------------------------------
+if __FILE__ == $0
+  path = (ARGV.count > 0) ? ARGV.shift : 'ug_test.db'
+
+  db = GitDS::Database.connect(path, true)
+  model = UserGroupModel.new(db) if db
+  fill_model(model) if model
+  list_model(model) if model
+end
+

data/doc/examples/user_group/ug_add_group.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# Add a group to a User/Group database repo
+# Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+
+# Add examples dir and lib/git-ds to ruby path
+BASE=File.dirname(File.expand_path(__FILE__)\
+                 ).split(File::SEPARATOR)[0..-4].join(File::SEPARATOR)
+$: << BASE + File::SEPARATOR + 'lib'
+$: << BASE + File::SEPARATOR + 'doc' + File::SEPARATOR + 'examples'
+
+require 'user_group/model'
+
+if __FILE__ == $0
+  if ARGV.count < 3 || ARGV.count > 4
+    puts "Usage : #{$0} [FILENAME] NAME ID OWNER"
+    puts "Repo dir is assumed to be . if FILENAME is not specified."
+    puts "A new GitDS database will be created if FILENAME does not exist."
+    exit -1
+  end 
+
+  path = ''
+  autocreate = false
+  if ARGV.count == 4
+    path = ARGV.shift
+    autocreate = true
+  else
+    path = GitDS::Database.top_level
+  end
+  name = ARGV.shift
+  id = ARGV.shift
+  owner = ARGV.shift
+
+  model = UserGroupModel.new(GitDS::Database.connect(path, autocreate))
+  raise "Could not connect to Model!" if not model
+
+  model.add_group(name, id, owner)
+
+  exit 0
+end

data/doc/examples/user_group/ug_add_group_user.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# Add a user to a group in a User/Group database repo
+# Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+
+# Add examples dir and lib/git-ds to ruby path
+BASE=File.dirname(File.expand_path(__FILE__)\
+                 ).split(File::SEPARATOR)[0..-4].join(File::SEPARATOR)
+$: << BASE + File::SEPARATOR + 'lib'
+$: << BASE + File::SEPARATOR + 'doc' + File::SEPARATOR + 'examples'
+
+require 'user_group/model'
+
+if __FILE__ == $0
+  if ARGV.count < 2 || ARGV.count > 3
+    puts "Usage : #{$0} [FILENAME] GROUP USER"
+    puts "Repo dir is assumed to be . if FILENAME is not specified."
+    exit -1
+  end 
+
+  path = (ARGV.count == 3) ? ARGV.shift : GitDS::Database.top_level
+  group_name = ARGV.shift
+  user_name = ARGV.shift
+
+  model = UserGroupModel.new(GitDS::Database.connect(path, false))
+  raise "Could not connect to Model!" if not model
+
+  g = model.group(group_name)
+  raise "Invalid group #{group_name}" if not g
+
+  u = model.user(user_name)
+  raise "Invalid user #{user_name}" if not u
+
+  g.add_user(u)
+
+  exit 0
+end

data/doc/examples/user_group/ug_add_user.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# Add a user to a User/Group database repo
+# Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+
+# Add examples dir and lib/git-ds to ruby path
+BASE=File.dirname(File.expand_path(__FILE__)\
+                 ).split(File::SEPARATOR)[0..-4].join(File::SEPARATOR)
+$: << BASE + File::SEPARATOR + 'lib'
+$: << BASE + File::SEPARATOR + 'doc' + File::SEPARATOR + 'examples'
+
+require 'user_group/model'
+
+if __FILE__ == $0
+  if ARGV.count < 3 || ARGV.count > 4
+    puts "Usage : #{$0} [FILENAME] NAME ID FULLNAME"
+    puts "Repo dir is assumed to be . if FILENAME is not specified."
+    puts "A new GitDS database will be created if FILENAME does not exist."
+    exit -1
+  end 
+
+  path = ''
+  autocreate = false
+  if ARGV.count == 4
+    path = ARGV.shift
+    autocreate = true
+  else
+    path = GitDS::Database.top_level
+  end
+  username = ARGV.shift
+  id = ARGV.shift
+  fullname = ARGV.shift
+
+  model = UserGroupModel.new(GitDS::Database.connect(path, autocreate))
+  raise "Could not connect to Model!" if not model
+
+  model.add_user(username, id, fullname)
+
+  exit 0
+end