svn 0.1.0

data/README

@@ -0,0 +1,39 @@
+== About ==
+
+This is a library for interacting with Subverison repositories. It is a
+new set of ruby bindings that are simple to use and compatible with RVM
+because they are dynamically linked to libsvn and do not require any native
+extensions.
+
+In addition, these new bindings expose a ruby-style API and try to hide the
+underlying SVN details---for example, SVN separates repositories from their
+inner filesystems, but this library hides that distinction.
+
+== Getting Started ==
+
+Example code:
+
+ require 'svn'
+ 
+ repo = Svn::Repo.open('/path/to/repo')
+ r4 = repo.revision(4)
+ puts "#{r}, by #{r.author} (on #{r.timestamp.strftime('%Y-%m-%d %H:%M')})\nLog: #{r.log}"
+ 
+ r4.changes.each_pair { |path, changes| ... }
+ puts r4.props.inspect
+ # => {"svn:log"=>"...", "svn:author"=>"blue", "svn:date"=>"2011-10-14T23:51:58.705026Z"}
+ puts r4.diff('/some/repo/file') # by default, against the previous revision
+
+== Current Status ==
+
+Version 0.1.0 supports read-only operations to inspect a subversion repository,
+its files, and file properties. Transactions are planned and will be included
+in a future version.
+
+The current release, 0.1.0 is an experimental release and the API included is
+subject to change. Rubygems version number conventions will be respected, so it
+is recommended that callers specify the version of this library using the "~>"
+operator:
+ spec.add_dependency 'ffi', '~> 0.1'
+
+== Contributing ==

data/lib/svn.rb

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'ffi'
+
+require 'svn/utils'
+require 'svn/misc'
+require 'svn/errors'
+require 'svn/pools'
+require 'svn/apr_utils'
+require 'svn/counted_strings'
+
+# General Svn docs here!
+module Svn
+  autoload :Stream, 'svn/streams'
+  autoload :Log, 'svn/logs'
+  autoload :Repo, 'svn/repos'
+  autoload :Root, 'svn/roots'
+  autoload :Revision, 'svn/revisions'
+  autoload :Diff, 'svn/diffs'
+end

data/lib/svn/apr_utils.rb

@@ -0,0 +1,313 @@
+require 'rubygems'
+require 'ffi'
+
+module Svn #:nodoc:
+
+  class AprHash < FFI::AutoPointer
+
+    # when used as key length, indicates that string length should be used
+    HASH_KEY_STRING = -1
+
+    include Enumerable
+
+    attr_accessor :keys_null_terminated
+    alias_method :keys_null_terminated?, :keys_null_terminated
+
+    def initialize( ptr, key_type, val_type, keys_null_terminated=true)
+      super( ptr )
+      @key_type = key_type
+      @val_type = val_type
+      @pointers = []
+      @keys_null_terminated = keys_null_terminated
+    end
+
+    class << self
+      # creates a new apr_hash_t that contains +contents+, if given
+      def create( key_type, val_type, pool=RootPool )
+        ptr = C.create( pool )
+        new( ptr, key_type, val_type )
+      end
+
+      def create_from( rb_hash, key_type, val_type, pool=RootPool )
+        create( key_type, val_type, pool ).copy_from( rb_hash )
+      end
+
+      def release( ptr )
+        # memory will be released with the allocation pool
+      end
+    end
+
+    module C
+      extend FFI::Library
+      ffi_lib 'libapr-1.so.0'
+
+      typedef :pointer, :index
+      typedef :pointer, :out_pointer
+      typedef :long, :apr_ssize
+      typedef Pool, :pool
+      typedef AprHash, :hash
+
+      # lifecycle functions
+      # returns a :pointer instead of a :hash because AprHash#create needs to
+      # add extra args to the ruby instantiation
+      attach_function :create,
+          :apr_hash_make,
+          [ :pool ],
+          :pointer
+
+      # pool accessor -- returns a Pointer instead of a Pool because Pool
+      # objects will destroy the pool when they are garbage collected. If the
+      # pool was created in SVN, we should never destroy it and if the pool was
+      # created elsewhere, then we should let the original instance destroy it.
+      # This means that the function here should not actually return a Pool.
+      attach_function :pool,
+          :apr_hash_pool_get,
+          [ :hash ],
+          :pointer
+
+      # size
+      attach_function :count,
+          :apr_hash_count,
+          [ :hash ],
+          :uint
+
+      # getter/setter methods
+      attach_function :get,
+          :apr_hash_get,
+          #  hash   key       klen
+          [ :hash, :pointer, :apr_ssize ],
+          :pointer
+      attach_function :set,
+          :apr_hash_set,
+          #  hash   key       klen  val (NULL = delete entry)
+          [ :hash, :pointer, :apr_ssize, :pointer ],
+          :void
+
+      # iteration functions
+      attach_function :first,
+          :apr_hash_first,
+          [ :pool, :hash ],
+          :index
+      attach_function :next,
+          :apr_hash_next,
+          [ :index ],
+          :index
+      attach_function :this,
+          :apr_hash_this,
+          [ :index, :out_pointer, :out_pointer, :out_pointer ],
+          :void
+    end
+
+    # use the above C module for the source of bound functions
+    bind_to C
+
+    # bound method definitions
+    bind :size, :to => :count
+
+    # because pool returns a Pointer and not a Pool as is expected, make it
+    # private so others can't use it.
+    bind :pool
+    private :pool
+
+    def each_pair
+      # outgoing pointers for keys and values
+      key_ptr = FFI::MemoryPointer.new( :pointer )
+      # apr_ssize_t => ssize_t => platform-specific long
+      len_ptr = FFI::MemoryPointer.new( :long )
+      val_ptr = FFI::MemoryPointer.new( :pointer )
+
+      # initialize a hash index to the first entry
+      iter = C.first( pool, self )
+
+      while !iter.null?
+        # get the key, key length, and val
+        C.this( iter, key_ptr, len_ptr, val_ptr )
+
+        # read the key
+        key_len = len_ptr.read_long
+        key = Utils.content_for( key_ptr.read_pointer, @key_type, key_len )
+
+        # yield the key and value
+        yield key, Utils.content_for( val_ptr.read_pointer, @val_type ) if block_given?
+
+        # advance to the next iteration
+        iter = C.next( iter )
+      end
+    end
+
+    def []( key )
+      val = nil # keep val in scope
+
+      if key.is_a?( String ) && keys_null_terminated?
+        val = C.get( self, key, HASH_KEY_STRING )
+      elsif key.respond_to? :size
+        val = C.get( self, key, key.size )
+      elsif key.respond_to? :length
+        val = C.get( self, key, key.length )
+      else
+        raise ArgumentError, "Invalid key #{key}: cannot determine length"
+      end
+
+      Utils.content_for( val, @val_type )
+    end
+
+    def []=( key, val )
+      val_ptr = Utils.pointer_for( val, @val_type )
+
+      # because the pointers passed in are referenced in native code, keep
+      # track of the pointers so they aren't garbage collected until this hash
+      # is destroyed
+      @pointers << val_ptr
+
+      if key.is_a?( String ) && keys_null_terminated?
+        C.set( self, key, HASH_KEY_STRING, val_ptr )
+      elsif key.respond_to? :size
+        C.set( self, key, key.size, val_ptr )
+      elsif key.respond_to? :length
+        C.set( self, key, key.length, val_ptr )
+      else
+        raise ArgumentError, "Invalid key #{key}: cannot determine length"
+      end
+
+      val
+    end
+
+    def copy_from( rb_hash )
+      rb_hash.each_pair do |key, val|
+        self[ key ] = val
+      end
+
+      self
+    end
+
+    def to_h
+      rb_hash = {}
+      each_pair do |key, val|
+        rb_hash[ key ] = val
+      end
+      rb_hash
+    end
+
+  end
+
+  class AprArray < FFI::AutoPointer
+
+    include Enumerable
+
+    def initialize( ptr, type )
+      super( ptr )
+      @type = type
+      @pointers = []
+    end
+
+    class << self
+      # creates a new AprArray of +nelts+ elements of +type+; allocation is done
+      # in +pool+, which defaults to Svn::RootPool
+      def create( type, nelts, pool=RootPool )
+        ptr = C.create( pool, nelts, FFI::Pointer.size )
+        new( ptr, type )
+      end
+
+      def create_from( rb_arr, type, pool=RootPool )
+        create( type, rb_arr.size ).copy_from( rb_arr )
+      end
+
+      def release
+        # memory will be released with the allocation pool
+      end
+    end
+
+    module C
+      extend FFI::Library
+      ffi_lib 'libapr-1.so.0'
+
+      typedef :pointer, :index
+      typedef :pointer, :out_pointer
+      typedef :long, :apr_ssize
+      typedef Pool, :pool
+      typedef AprArray, :array
+
+      # allocation
+      # returns a :pointer instead of a :array because AprArray#create needs to
+      # add extra args to the ruby instantiation
+      attach_function :create,
+          :apr_array_make,
+          [ :pool, :int, :int ],
+          :pointer
+
+      # empty?
+      attach_function :is_empty,
+          :apr_is_empty_array,
+          [ :array ],
+          :int
+
+      # modifier methods
+      attach_function :push,
+          :apr_array_push,
+          [ :array ],
+          :pointer
+
+      attach_function :pop,
+          :apr_array_pop,
+          [ :array ],
+          :pointer
+    end
+
+    # helper procs for method binding
+    test_c_true = Proc.new { |i| i == 1 }
+
+    # use the above C module for the source of bound functions
+    bind_to C
+
+    # bound method definitions
+    bind :empty?, :to => :is_empty,
+        :before_return => test_c_true
+
+    def push( el )
+      # turn element into a pointer
+      ptr = Utils.pointer_for( el, @type )
+      # get the array element location and write ptr there
+      location = C.push( self )
+      location.write_pointer( ptr )
+
+      # because the pointers passed in are referenced in native code, keep
+      # track of the pointers so they aren't garbage collected until this hash
+      # is destroyed
+      @pointers << ptr
+
+      el
+    end
+    alias_method :add, :push
+    alias_method :<<, :push
+
+    def copy_from( arr )
+      arr.each do |el|
+        self << el
+      end
+      self
+    end
+
+    def pop
+      location = C.pop( self )
+      Utils.content_for( location.read_pointer, @type )
+    end
+
+# these are commented out because they don't work. it doesn't look like APR
+# array accesses happen this way.
+#    def []( num )
+#      num = num.to_i
+#      Utils.content_for( get_pointer( num * FFI::Pointer.size ), @type )
+#    end
+#
+#    def []=( num, val )
+#      num = num.to_i
+#
+#      ptr = Utils.pointer_for( val, @type )
+#      put_pointer( num * FFI::Pointer.size, ptr )
+#
+#      val
+#    end
+
+  end
+
+end

data/lib/svn/counted_strings.rb

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'ffi'
+
+module Svn #:nodoc:
+
+  # a struct for interacting with svn_string_t values
+  class CountedStringStruct < FFI::Struct
+
+    layout(
+        # because the data may not be NULL-terminated, treat it as a pointer
+        # and always read the string contents with FFI::Pointer#read_string
+        :data, :pointer,
+        :length, :size_t
+      )
+
+    # returns a new ruby String with the CountedString's contents.
+    def to_s
+      self[:data].read_string( self[:length] )
+    end
+
+    def inspect
+      to_s.inspect
+    end
+
+  end
+
+  # the svn_string_t pointer type, which is the one used externally
+  CountedString = CountedStringStruct.by_ref
+
+  def CountedString.from_string( content )
+    return content if content.is_a? CountedStringStruct
+    cstr = CountedStringStruct.new
+    cstr[:data] = FFI::MemoryPointer.from_string( content )
+    cstr[:length] = content.size
+    cstr
+  end
+
+end

data/lib/svn/diffs.rb

@@ -0,0 +1,209 @@
+require 'rubygems'
+require 'stringio'
+require 'ffi'
+
+module Svn #:nodoc:
+
+  class Diff < FFI::AutoPointer
+
+    class << self
+      def string_diff( original, modified, options={}, pool=RootPool )
+        options = FileOptions.from_hash( options ) if options.is_a? Hash
+        original = CountedString.from_string( original )
+        modified = CountedString.from_string( modified )
+
+        out = FFI::MemoryPointer.new( Diff )
+
+        Error.check_and_raise(
+            C.string_diff( out, original, modified, options, pool )
+          )
+
+        d = new( out.read_pointer )
+
+        return nil if d.null?
+
+        d.type = :string
+        d.original = original
+        d.modified = modified
+        d.options = options
+        d.pool = pool
+
+        return d
+      end
+
+      def file_diff( original_path, modified_path, options={}, pool=RootPool )
+        options = FileOptions.from_hash( options ) if options.is_a? Hash
+
+        out = FFI::MemoryPointer.new( Diff )
+
+        Error.check_and_raise(
+            C.file_diff( out, original_path, modified_path, options, pool )
+          )
+
+        d = new( out.read_pointer )
+
+        return nil if d.null?
+
+        d.type = :file
+        d.original_path = original_path
+        d.modified_path = modified_path
+        d.options = options
+        d.pool = pool
+
+        return d
+      end
+
+      def release( ptr )
+        # diff objects will probably need to keep track of the pool in which
+        # they are allocated so they can be freed in that pool
+      end
+    end
+
+    attr_accessor :type
+    attr_accessor :original
+    attr_accessor :original_path
+    attr_accessor :modified
+    attr_accessor :modified_path
+    attr_accessor :options
+    attr_accessor :pool
+
+    def changed?
+      ( C.is_changed( self ) == 1 )
+    end
+
+    def conflicts?
+      ( C.has_conflicts( self ) == 1 )
+    end
+
+    def unified( *args )
+      # keep these in scope
+      out_stream = nil
+      options = nil
+      pool = nil
+
+      case args.size
+      when 0
+        # use all defaults
+      when 1
+        if args.first.is_a? Hash
+          options = args.first
+        elsif args.first.is_a? IO or args.first.is_a? StringIO
+          out_stream = args.first
+        elsif args.first.is_a? Pool
+          pool = args.first
+        end
+      when 2, 3
+        out_stream, options, pool = args
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.size} for 3)"
+      end
+
+      # defaults
+      out_stream ||= StringIO.new
+      options ||= {}
+      pool ||= RootPool
+
+      # get common options
+      encoding = options[:encoding] || 'utf-8'
+      original_header = options[:original_header]
+      modified_header = options[:modified_header]
+
+      case type
+      when :string
+        with_diff_header = ( options[:with_diff_header] ? 1 : 0 )
+
+        Error.check_and_raise( C.string_output_unified(
+            Svn::Stream.wrap_io( out_stream ), self,
+            original_header, modified_header, encoding,
+            original, modified, pool
+          ) )
+
+      when :file
+        path_strip = options[:path_strip]
+        show_c_function = ( options[:show_c_function] ? 1 : 0 )
+
+        Error.check_and_raise( C.file_output_unified(
+            Svn::Stream.wrap_io( out_stream ), self,
+            original_path, modified_path,
+            original_header, modified_header, encoding, path_strip,
+            show_c_function, pool
+          ) )
+      end
+
+      out_stream.rewind if out_stream.is_a? StringIO
+
+      out_stream
+    end
+
+    class FileOptionsStruct < FFI::Struct
+      layout(
+          :ignore_whitespace, :int, # :whitespace,
+          :ignore_eol_style, :int,
+          :show_c_function, :int
+        )
+    end
+
+    # create a mapped type for use elsewhere
+    FileOptions = FileOptionsStruct.by_ref
+
+    def FileOptions.from_hash( hash )
+      options = FileOptionsStruct.new
+      hash.each_pair do |key, val|
+        # add a check if key is in members?
+        options[key] = val
+      end
+      options
+    end
+
+    module C
+
+      extend FFI::Library
+      ffi_lib 'libsvn_diff-1.so.1'
+
+      typedef :pointer, :out_pointer
+      typedef Pool, :pool
+      typedef CError.by_ref, :error
+      typedef Stream, :stream
+      typedef FileOptions, :file_options
+      typedef CountedString, :counted_string
+      typedef Diff, :diff
+
+      enum :whitespace, [
+          :none,    # do not ignore whitespace
+          :change,  # treat as a single char
+          :all      # ignore all whitespace chars
+        ]
+
+      # diff functions
+      attach_function :file_diff,
+          :svn_diff_file_diff_2,
+          [ :out_pointer, :string, :string, :file_options, :pool ],
+          :error
+
+      attach_function :string_diff,
+          :svn_diff_mem_string_diff,
+          [ :out_pointer, :counted_string, :counted_string, :file_options,
+            :pool ],
+          :error
+
+      # diff inspection
+      attach_function :is_changed, :svn_diff_contains_diffs, [:diff], :int
+      attach_function :has_conflicts, :svn_diff_contains_conflicts, [:diff], :int
+
+      # output functions
+      attach_function :file_output_unified,
+          :svn_diff_file_output_unified3,
+          [ :stream, :diff, :string, :string, :string, :string, :string,
+            :string, :int, :pool ],
+          :error
+
+      attach_function :string_output_unified,
+          :svn_diff_mem_string_output_unified,
+          [ :stream, :diff, :string, :string, :string,
+            :counted_string, :counted_string, :pool ],
+          :error
+    end
+
+  end
+
+end