activesp 0.0.1 → 0.0.4

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2010 XAOP bvba
+
+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.rdoc

@@ -0,0 +1,105 @@
+= ActiveSP Release 0.0.3 "Under Pressure" (Aug 27th 2010)
+
+== What?
+
+ActiveSP is a library for talking to SharePoint through its web services in an
+object-oriented way.
+
+At the moment it only provides read-only access and write access to list items.
+Full write access is on the way!
+
+== Why?
+
+Because Ruby is great and SharePoint's popularity is a fact of life.
+
+== When?
+
+This library is pure Ruby and does not need a Ruby VM running on .NET (such as IronRuby).
+Use this library when using IronRuby is not an option, or when it needs to run on more
+than IronRuby.
+
+The web services are not fully functional and somewhat slow, so if you can use
+the .NET platform then consider talking to the .NET API's directly instead.
+
+== How?
+
+Install the gem and its dependencies:
+
+  gem install activesp
+
+Create a file <tt>test.rb</tt> like this:
+
+  require 'rubygems'
+  require 'activesp'
+
+  def browse(item, indentation = 0)
+    puts "  " * indentation + "- " + item.class.to_s + " : " + item.url
+    case item
+    when ActiveSP::Site
+      puts "  " * indentation + "    Title = #{item.Title}, Description = #{item.Description}"
+      item.sites.each { |site| browse(site, indentation + 1) }
+      item.lists.each { |list| browse(list, indentation + 1) }
+    when ActiveSP::List
+      puts "  " * indentation + "    Description = #{item.Description}, Hidden = #{item.Hidden}"
+      item.items.each { |item| browse(item, indentation + 1) }
+    when ActiveSP::Folder
+      item.items.each { |item| browse(item, indentation + 1) }
+    when ActiveSP::Item
+      item.content_urls.each do |url|
+        puts "  " * indentation + "    Content URL = #{url}"
+      end
+    end
+  end
+
+  c = ActiveSP::Connection.new(:login => "your login", :password => "your password", :root => "URL of root site")
+
+  browse(c.root)
+
+Run <tt>ruby test.rb</tt> and it will print the structure of your SharePoint site.
+
+The examples directory contains this example plus a few others. We will add more along the way.
+
+== Support
+
+We support read access to sites (webs), lists, items, documents, folders, content type,
+columns (fields), content, users, groups, roles.
+
+We support write access to list items (including documents): create, update and delete list items.
+
+We do not yet support life cycles, versions, full write support.
+
+== Compatibility
+
+We have tested ActiveSP with SharePoint 2007 and SharePoint 2010. ActiveSP has been tested
+on Mac OS X with Ruby 1.8.6, but we do not see any reason why it would not work on Linux
+or Windows, or with other Ruby implementations.
+
+For release 0.0.3, we have not tested extensively on SharePoint 2007 so we can't guarantee
+compatibility.
+
+== Changelog
+
+=== ActiveSP Release 0.0.3 "Under Pressure" (Aug 27th 2010)
+
+* Added write support for list items (including documents): create, update, delete
+* Use association proxies for list items and item attachments
+* Decode field names (e.g., File_x0020_Type becomes File Type)
+* A few bug fixes
+* Added method to ask for list changes since token
+
+=== ActiveSP Release 0.0.1 "Space Oddity" (Apr 9th 2010)
+
+* Initial release
+
+== License
+
+ActiveSP is released under the MIT license. The usual disclaimers apply, including that we are
+not responsible for inevitable Ruby addiction.
+
+See the LICENSE file included in the distribution for further details.
+
+== Who?
+
+ActiveSP is copyright (c) 2010 XAOP bvba
+
+Visit us at http://www.xaop.com.

data/Rakefile

@@ -1,5 +1,31 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 require 'rubygems'
 require 'rake/gempackagetask'
+require 'yard'
 
 ACTIVESP_VERSION = File.readlines("VERSION")[0][/[\d.]*/]
 
@@ -9,18 +35,17 @@ spec = Gem::Specification.new do |s|
   s.version = ACTIVESP_VERSION
   s.author = "Peter Vanbroekhoven"
   s.email = "peter@xaop.com"
-  #s.homepage = "http://www.xaop.com/pages/dctmruby"
+  s.homepage = "http://www.xaop.com/labs/activesp"
   s.summary = "Interface to SharePoint"
-  s.description = s.summary
-  #s.rubyforge_project = s.name
-  s.files += %w(VERSION Rakefile)
+  s.description = "An object-oriented interface to SharePoint that uses the web services provided by SharePoint to connect to it. Supports SharePoint 2007 and 2010."
+  s.files += %w(VERSION LICENSE README.rdoc Rakefile)
   s.files += Dir['lib/**/*.rb']
   # s.bindir = "bin"
-  # s.executables.push(*(Dir['bin/*.rb'] - ["bin/encrypt-dmcl.rb"]).map { |f| File.basename(f) })
+  # s.executables.push(*(Dir['bin/*.rb']))
   s.add_dependency('savon-xaop')
   s.add_dependency('nokogiri')
   # s.rdoc_options << '--exclude' << 'ext' << '--main' << 'README'
-  # s.extra_rdoc_files = ["README", "docs/README.html"]
+  # s.extra_rdoc_files = ["README"]
   s.has_rdoc = false
   s.require_paths << 'lib'
   # s.autorequire = 'mysql'
@@ -32,3 +57,7 @@ Rake::GemPackageTask.new(spec) do |pkg|
   pkg.need_zip = true
   pkg.need_tar = true
 end
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--no-private', '--readme', 'README.rdoc']
+end

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.4

data/lib/activesp.rb

@@ -1,3 +1,28 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 require 'nokogiri'
 require 'time'
 
@@ -6,6 +31,7 @@ end
 
 require 'activesp/util'
 require 'activesp/caching'
+require 'activesp/associations'
 require 'activesp/persistent_caching'
 
 require 'activesp/base'
@@ -24,3 +50,4 @@ require 'activesp/user'
 require 'activesp/group'
 require 'activesp/role'
 require 'activesp/permission_set'
+require 'activesp/file'

data/lib/activesp/associations.rb

@@ -0,0 +1,76 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
+module ActiveSP
+  
+  # @private
+  module Associations
+    
+    class AssociationProxy
+      
+      include Enumerable
+      
+      def initialize(object, &element_getter)
+        @object = object
+        @element_getter = element_getter
+      end
+      
+      def each(&blk)
+        @element_getter.call(blk)
+      end
+      
+      def first
+        each { |element| return element }
+        nil
+      end
+      
+      def last
+        inject { |_, element| element }
+      end
+      
+      def count
+        inject(0) { |cnt, _| cnt + 1 }
+      end
+      
+    end
+    
+  private
+    
+    def association(name, each_method = ("each_" + name.to_s.sub(/s\z/, "")).to_sym, &blk)
+      proxy = Class.new(AssociationProxy) do
+        class_eval(&blk) if blk
+        define_method(:to_s) { "#{@object.to_s}.#{name}" }
+        define_method(:inspect) { "#{@object.inspect}.#{name}" }
+      end
+      define_method(name) do |*a|
+        proxy.new(self) do |blk|
+          send(each_method, *a, &blk)
+        end
+      end
+    end
+    
+  end
+  
+end

data/lib/activesp/base.rb

@@ -1,35 +1,99 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 module ActiveSP
   
+  # The base class for all objects stored in SharePoint
   class Base
     
     extend Caching
+    extend Associations
     
+    # Returns a key that can be used to retrieve this object later on using {Connection#find_by_key}
+    # @return [String]
+    def key
+      raise "This is here for documentation purposes only"
+    end
+    
+    # Returns the attributes of this object as a Hash
+    # @return [Hash{String => Integer, Float, String, Time, Boolean, Base}]
     def attributes
       current_attributes
     end
-    cache :attributes, :dup => true
+    cache :attributes, :dup => :always
     
+    # Returns the types of the attributes of this object as a Hash
+    # @return [Hash{String => Field}]
     def attribute_types
       internal_attribute_types
     end
-    cache :attribute_types, :dup => true
+    cache :attribute_types, :dup => :always
     
+    # Returns whether or not this object has an attribute with the given name
+    # @param [String] name The name of the attribute
+    # @return [Boolean]
     def has_attribute?(name)
-      attributes.has_key?(name)
+      current_attributes.has_key?(name)
     end
     
+    # Returns whether or not this object has an attribute with the given name that can be assigned to
+    # @param [String] name The name of the attribute
+    # @return [Boolean]
     def has_writable_attribute?(name)
-      has_attribute?(name) && !attribute_types[name].ReadOnly
+      has_attribute?(name) and attr = internal_attribute_types[name] and !attr.ReadOnly
     end
     
+    # Returns the value of the attribute of the given name, or nil if this object does not have an attribute by the given name
+    # @param [String] name The name of the attribute
+    # @return [Integer, Float, String, Time, Boolean, Base]
     def attribute(name)
-      attributes[name]
+      current_attributes[name]
+    end
+    
+    # Returns the type of the attribute by the given name, or nil if this object does not have an attribute by the given name
+    # @param [String] name The name of the attribute
+    # @return [Field]
+    def attribute_type(name)
+      internal_attribute_types[name]
     end
     
+    # Sets the attribute with the given name to the given value
+    # @param [String] name The name of the attribute
+    # @param [Integer, Float, String, Time, Boolean, Base] value The value to assign
+    # @return [Integer, Float, String, Time, Boolean, Base] The assigned value
+    # @raise [ArgumentError] Raised when this object does not have an attribute by the given name or if the attribute by the given name is read-only
     def set_attribute(name, value)
-      current_attributes[name] = value
+      has_attribute?(name) and field = attribute_type(name) and internal_attribute_types[name] or raise ArgumentError, "#{self} has no field by the name #{name}"
+      !field.ReadOnly or raise ArgumentError, "field #{name} of #{self} is read-only"
+      current_attributes[name] = type_check_attribute(field, value)
     end
     
+    # Provides convenient getters and setters for attributes. Note that no name mangling
+    # is done, so an attribute such as Title is accessed as obj.Title. The main rationale
+    # behind this is that name mangling is usually not lossless (e.g., both <tt>Title</tt>
+    # and <tt>title</tt> could map to the more Rubyish <tt>title</tt>) and imperfect.
     def method_missing(m, *a, &b)
       ms = m.to_s
       if a.length == 0 && has_attribute?(ms)
@@ -41,13 +105,35 @@ module ActiveSP
       end
     end
     
+    # Reloads the object from the server
+    # @return [void]
+    def reload
+    end
+    
+    # Saves the object to the server. Raises an exception when the save fails
+    # @return [void]
+    def save
+    end
+    
   private
     
     def current_attributes
-      original_attributes
+      original_attributes.inject({}) { |h, (k, v)| h[k] = ::Array === v ? v.dup.freeze : v ; h }
     end
     cache :current_attributes
     
+    def changed_attributes
+      before = original_attributes
+      after = current_attributes
+      changes = {}
+      after.each do |name, value|
+        if before[name] != value
+          changes[name] = value
+        end
+      end
+      changes
+    end
+    
   end
   
 end