weft-qda 0.9.6

data/lib/weft/coding.rb

@@ -0,0 +1,355 @@
+module QDA
+  # Classes mixing-in should implement the offset, length, [x, y], and
+  # << methods
+  module Coding
+    def end()
+      offset + length
+    end
+
+    def include?(point)
+      if point.nil?
+        raise ArgumentError, 
+        "Point should be an integer, got #{point.inspect}"
+      end
+      point >= self.offset && point < self.end()
+    end
+    alias :contains? :include?
+
+    # Returns true if self and +other+ overlap at any point - ie there
+    # is at least one character that is coded by both items
+    def overlap?(other)
+      first, second = [self, other].sort_by { | x | x.offset }
+      first.end > second.offset ? true : false
+    end
+
+    # Returns true if self and +other+ overlap or are contiguous
+    def touch?(other)
+      first, second = [self, other].sort_by { | x | x.offset }
+      first.end >= second.offset ? true : false
+    end
+
+    # note that no-argument version of Array#sort does *not* call this
+    # method
+    def <=>(other)
+      self.offset == other.offset ?
+      self.end <=> other.end :
+        self.offset <=> other.offset
+    end
+
+
+    def prepare_args(other)
+      # it should be a type that implements these methods
+      unless other.kind_of?(Coding)
+        raise ArgumentError,
+        "Cannot combine with #{other.inspect}, should implement Coding"
+      end
+      
+      # if it's not the same class, we need to determine what kind of
+      # thing to return by combining the classes
+      if other.is_a?(self.class)
+        return self, other
+      else
+        return self.coerce(other), other.coerce(self)
+      end
+    end
+
+    # returns the code representing the intersection of +self+ and +other+
+    # returns nil if there is no overlap
+    def intersect(other)
+      # this represents self, possibly coerced into a different class
+      this, other = prepare_args(other)
+      unless this.overlap?(other)
+        return nil
+      end
+      sorted = QDA::CodeSet[ this, other ].sort
+      this_start = [ other.offset, this.offset ].max
+      this_end = [other.end, this.end ].min
+      fragment = sorted[0][this_start, this_end - this_start ]
+    end
+    alias :% :intersect
+
+    # returns a QDA::CodeSet created by removing the characters coded
+    # by +other+ from +self+. The returned CodeSet may be 0, 1 or 2
+    # elements long. The diagram below shows how 2 results may be
+    # returned.
+    # 
+    #  -----+++++++++++++++++------ # self
+    #  -
+    #  -----------++++++++--------- # exclude
+    #  =
+    #  -----++++++--------+++------ # result
+    def exclude(other)
+      this, other = prepare_args(other)
+      results = QDA::CodeSet[]
+      if offset < other.offset
+        if this.end < other.offset
+          results.add( this )
+        else
+          results.add( this[offset, other.offset - offset] )
+        end
+      end
+      if this.end > other.end
+        if this.offset > other.end
+          results.add(this)
+        else
+          results.add( this[other.end, this.end - other.end] )
+        end
+      end
+      return results
+	end
+    alias :- :exclude
+
+    # Returns the code produced by merging +self+ with +other+. If the
+    # two codes do not touch each other, then an CodeSet of the two codes
+    # is returned.
+	def union(other)
+      this, other = prepare_args(other)
+      return this if this == other
+      return QDA::CodeSet[ self, other ].sort unless touch?(other)
+
+      # if they overlap or touch, a single coding will be returned
+      first, second = QDA::CodeSet[ this, other ].sort
+      fragment = first.dup()
+      if second.end > first.end
+        fragment << second[first.end, second.end - first.end]  
+      end
+      return fragment
+    end
+    alias :+ :union
+  end
+
+  # A collection of things that are +Coding+ - ie that mix-in the class
+  # above. 
+  class CodeSet < Array
+    protected :<<, :push, :pop, :shift, :unshift
+
+    # Populate a new CodeSet from an array of coding items +arr+. These
+    # should either be QDA::Codes, QDA::Fragments or three-item arrays.
+    # Where the latter are found, they will be automatically turned into
+    # QDA::Code, taking the contents of each three-item array to be
+    # [+docid+, +offset+, +length+]
+    def initialize(arr = [])
+      arr.collect! do | item |
+        case item
+        when Array
+          Code.new(*item)
+        when Fragment, Code
+          item
+        else
+          raise ArgumentError, "unexpected item #{item} in list"
+        end
+      end
+      super(arr)
+    end
+
+    # iterate over each successive neighbouring pair of codings in
+    # the set, i.e. items 1, 2; items 2,3; items 3, 4 ..  items n-1,
+    # n]. This is practically useful for +intersect+ but no other
+    # use at the moment.
+    def each_pair()
+      0.upto( length - 2 ) { | i | yield self[i], self[i + 1] }
+    end
+
+    def sort()
+      block_given? ? super : super { | a, b | a <=> b }
+    end
+
+    def intersect(other)
+      results = CodeSet[]
+      sorted  = CodeSet[ *(self  + other).sort_by { | x | x.end } ]
+      sorted.each_pair { | a, b | results << a % b }
+      results.compact # return less nils
+    end
+
+    # add the extent covered by +code+ (a QDA::Code) to the set,
+    # modifying in place.
+    def add(code)
+      replace( union( CodeSet[code] ) )
+    end
+
+    # remove the extent covered by +uncode+ (a QDA::Code) from the set,
+    # modifying it in place.
+    def subtract(uncode)
+      replace( exclude( CodeSet[uncode] ) )
+    end
+
+    # returns the set produced by removing all extents covered by
+    # +other+, which should be a QDA::CodeSet. Note that unlike +union+
+    # and +intersect+
+    #  self.exclude(other) != other.exclude(self)
+    def exclude(other)
+      return self if other.nil?
+      results = self.dup
+      other.each do | uncode |
+        results.collect! { | code | code - uncode }.flatten!
+      end
+      return results
+    end
+
+    # Returns the set produced by merging all the codes in this one
+    # with those in +other+, which should be a QDA::CodeSet
+    def union(other)
+      results = CodeSet[]
+      sorted  = CodeSet[ *(self  + other).sort_by { | f | f.end } ]
+
+	  last_code = nil
+	  sorted.each do | code |
+		if ! last_code
+		  last_code = code
+		elsif last_code.touch?(code)
+		  last_code = last_code + code
+        else
+		  results.push(last_code)
+		  last_code = code.dup
+		end
+	  end
+	  results.push(last_code)
+	  return results
+	end
+  end
+
+  # a hash representing a complex series of codes applied to one or
+  # more documents
+  class CodingTable < Hash
+    def initialize
+      super { |  h, k | h[k] = CodeSet.new() }
+    end
+
+    # should access using +add+ or +set+
+    # private :[]=
+    protected :[]=
+      
+    # add the coding of +item+ to the coding table. +item+ should be
+    # a QDA::Code or QDA::Fragment.
+    def add(item)
+      self[item.docid].add(item)
+    end
+
+    # Sets the coding of the document identified by +docid+ to be +codeset+
+    def set(docid, codeset)
+      unless codeset.kind_of?(CodeSet)
+        raise ArgumentError, 
+          "Cannot set codeset #{codeset.inspect} as a CodingTable entry"
+      end
+      self[docid] = codeset
+    end
+
+    # Removes all coding associated with +docid+
+    alias :unset :delete
+
+    # remove the coding of +item+ to the coding table. +item+ should be
+    # a QDA::Code or QDA::Fragment.
+    def subtract(item)
+      self[item.docid].subtract(item)
+    end
+
+    def num_of_docs
+      keys.reject { | set | self[set].length == 0 }.length
+    end
+
+    def num_of_codes
+      values.inject(0) { | count, codeset | count + codeset.length }
+    end
+
+    def num_of_chars
+      values.inject(0) do | total, codes | 
+        codes.inject(total) { | sub_total, code | sub_total + code.length }
+      end
+    end
+
+    # returns true if this coding table contains coding for the
+    # document +doc+
+    def codes?(doc)
+      key?(doc.dbid) and self[doc.dbid].length > 0
+    end
+
+    # Adds the coding of the other coding table +other+ to this one,
+    # modifying +self in place
+    def merge(other)
+      results = CodingTable.new()
+      either = self.keys + other.keys
+      either.uniq.each do | docid |
+        if ! other[docid]
+          results[docid] = self[docid]
+        elsif ! self[docid]
+          results[docid] = other[docid]
+        else
+          results[docid] = self[docid].union(other[docid])
+        end
+      end
+      replace(results)
+    end
+
+    # Removes all coding from this table that occurs in the other table
+    # +other+, modifying this CodingTable in place
+    def remove(other)
+      results = CodingTable.new()
+      each do | docid, codes |
+        results[docid] = self[docid].exclude(other[docid])
+      end
+      replace(results)
+    end
+
+    # deletes all coding except that which is also covered by +other+
+    def join(other)
+      both = keys.find_all { | doc | other.key?(doc) }
+      results = CodingTable.new()
+      both.each do | docid |
+        results[docid] = self[docid].intersect( other[docid] )
+      end
+      replace(results)
+    end
+
+    def sort(&block)
+      if block_given
+        super(&block)
+      else
+        super { | a, b | a <=> b }
+      end
+    end
+  end
+
+  # a FragmentTable holds a collection of fragments. It contains a
+  # number of CodeSets of Fragments. Each CodeSet can be retrieved
+  # either by document title or by document dbid. 
+  #  tbl = FragmentTable.new()
+  #  f   = Fragment.new('Weft QDA', 'the title', 6, 1)
+  #  tbl.add(f)
+  #  tbl['the title'] # => QDA::CodeSet[ <Fragment 1 6-14: 'Weft QDA'> ]
+  #  tbl[1] # => QDA::CodeSet[ <Fragment 1 6-14: 'Weft QDA'> ]
+  class FragmentTable < CodingTable
+    def initialize
+      @titles = Hash.new() { | h, k | h[k] = CodeSet }
+      super()
+    end
+
+    # Assumes this is a document title if a string, or an dbid if an integer
+    def [](k)
+      k.kind_of?(String) ? super(@titles[k]) : super(k)
+    end
+
+    # Always use this method to add fragments to the collection
+    def add(fragment)
+      unless fragment.is_a?(Fragment)
+        raise ArgumentError, "Fragment expected, got #{fragment.inspect}"
+      end
+      self[fragment.docid].add(fragment)
+      @titles[fragment.doctitle] = fragment.docid
+    end
+
+    def each_title()
+      titles = @titles.keys.sort
+      titles.each do | title |
+        yield title, self[ @titles[title] ]
+      end
+    end
+    
+    def to_codingtable()
+      ct = CodingTable.new 
+      each do | docid, codeset |
+        ct[docid] = QDA::CodeSet[ *codeset.map { | frag | frag.to_code } ]
+      end
+      return ct
+    end
+  end
+end

data/lib/weft/document.rb

@@ -0,0 +1,118 @@
+require 'weft/coding'
+
+module QDA
+class Fragment < String
+  include Coding
+  attr_reader :doctitle, :offset
+  attr_accessor :docid
+  
+  def initialize(text, doctitle, offset, docid = nil)
+    super(text)
+    unless doctitle.kind_of? String
+      raise ArgumentError, 
+      "Fragment.new expects a doctitle string, got #{doctitle.inspect}"
+    end
+
+    unless offset.kind_of?(Fixnum) && offset >= 0
+      raise ArgumentError, 
+      "Fragment.new expects an integer offset, got #{offset.inspect}"
+    end
+
+    unless docid.nil? || docid.kind_of?(Fixnum)
+      raise ArgumentError, 
+      "Fragment.new expects an integer docid, got #{docid.inspect}"
+    end
+    @doctitle = doctitle
+    @offset   = offset
+    # of the document - duplicates role of doctitle - to fix
+    @docid    = docid
+  end
+
+  def ==(other)
+    super(other) and
+      @offset == other.offset and
+      @doctitle == other.doctitle
+  end
+
+  def to_code()
+    Code.new(@docid, offset, length)
+  end
+
+  def coerce(other)
+    self.to_code()
+  end
+
+  # does this code completely cover the document
+  def complete?()
+    return NotImplementedError # need to fix
+    if @doc.fragments.length == @length + 1
+      return true
+    end
+    return false
+  end
+
+  # returns a fragment from +abs+ (relative to the whole document)
+  # that is +length+ long
+  def [](abs, length)
+    if abs < self.offset
+      raise "Can't get part of non-overlapping string"
+    end
+    Fragment.new( super(abs - self.offset, length),
+                  @doctitle, abs, @docid )
+  end
+
+  def inspect()
+    str = length < 50 ? self.to_s : self.to_s[0, 50] << '...'
+    "<*Fragment #{docid} #{offset}-#{self.end} : '#{str}>"
+  end
+end
+
+class Document < Fragment
+  attr_reader :meta, :create_date, :mod_date, :dbid
+  attr_accessor :title, :memo
+  
+  # expects dbid to be set later
+  def initialize(title, text = '', memo = '', 
+                 create_date = nil, mod_date = nil)
+    super(text, title, 0)
+	@title = title
+    @memo  = memo
+
+    @create_date = create_date
+    @mod_date    = mod_date 
+  end
+
+  def text
+    self.to_s
+  end
+
+  def dbid=(dbid)
+    unless dbid.nil? || dbid.kind_of?(Fixnum)
+      raise ArgumentError,
+      "Document dbid should be an integer or nil, got #{dbid.inspect}"
+    end
+    @dbid = dbid
+  end
+
+  # marks the document as created now
+  def create()
+    @create_date = Time.now()
+  end
+
+  #   def append(text, fragtype = 0)
+  # returns the number of characters appended
+  def append(text, term_char = "\n")
+    ins = text.gsub(/[\r\n]+$/, '') + term_char
+	self << ins
+    ins.length 
+  end
+  
+  def [](from, num_chars)
+	Fragment.new(super, title, from, @dbid)
+  end
+  
+  def inspect()
+    "<*Document #{dbid} '#{title}' (#{length} chars)>"
+  end
+end
+end