msgthr 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9a571597f50c7ec04abef8c956d811854d727bcc
-  data.tar.gz: 07f8634e7f6bd758206ad6e8170acd5048af2b07
+SHA256:
+  metadata.gz: 5482fc1e20bf45ed07ee4b3eacc93eccd28c3f28195550d1629cb5d21919f42b
+  data.tar.gz: eaca3d5d6ef9840154d6b5fd70033382bdbb9fe3863f726585b7ef6d0d7dfae1
 SHA512:
-  metadata.gz: 1e13bda13b30d4548955d306570848c8bf5f0993575617b81822a4fc684085182eb7200f5e0cadfc56c38215c166d06d8fa07853cbbad784c21665b13e9355ee
-  data.tar.gz: 7217b572b347c32ef5a01d0b95c805dfc37e28bd54ad078d4bd38f8b7c5396ba0806d052c2194b078fac78770c72cb449cb485f2ec8af1f8fdff68b528fd3db6
+  metadata.gz: e73d95955bd492e97bd2c129986da0658df78fe82e185218195a769e77643b858bee1c64de84c94bb8e7baf6b5a611cad08ac492072ad25812c70821563dfc66
+  data.tar.gz: f12ec74ea787a1d09ccd20c191429bfafe0f291dfffa3fded5e4966efa1b8b82aad0e8653c06c1728e0a6ba06ee4703f63ffe2cf5a40e58a1cdb6d63c56c84d8

data/.olddoc.yml

@@ -1,6 +1,6 @@
 ---
 cgit_url: https://80x24.org/msgthr.git
 git_url: git://80x24.org/msgthr.git
-rdoc_url: https://80x24.org/msgthr/rdoc/
+rdoc_url: https://80x24.org/msgthr/
 ml_url: https://80x24.org/msgthr-public/
 public_email: msgthr-public@80x24.org

data/GNUmakefile

@@ -4,7 +4,7 @@ all::
 pkg = msgthr
 RUBY = ruby
 lib := lib
-VERSION := 1.0.1
+VERSION := 1.1.0
 RSYNC_DEST := 80x24.org:/srv/80x24/msgthr/
 
 RSYNC = rsync

data/README

@@ -76,7 +76,7 @@ because CSS/JS/images are all too complicated for us.
 
 RDoc API documentation in simple HTML is available at:
 
-	https://80x24.org/msgthr/rdoc/
+	https://80x24.org/msgthr/rdoc/Msgthr.html
 
 Copyright
 ---------

data/lib/msgthr.rb

@@ -7,8 +7,7 @@
 #
 # * use Msgthr.new to create a new object
 # * use Msgthr#add! for every message you have
-# * use Msgthr#thread! to perform threading operations
-# * optionally, use Msgthr#order! to sort messages
+# * use Msgthr#thread! to perform threading and (optionally) sort
 # * use Msgthr#walk_thread to iterate through the threaded tree
 #
 # See https://80x24.org/msgthr/README for more info
@@ -20,43 +19,39 @@ class Msgthr
   # calling Msgthr#thread!
   attr_reader :rootset
 
+  # raised when methods are called in an unsupported order
+  StateError = Class.new(RuntimeError)
+
   # Initialize a Msgthr object
   def initialize
     @id_table = {}
     @rootset = []
+    @state = :init # :init => :threaded => :ordered
   end
 
   # Clear internal data structures to save memory and prepare for reuse
   def clear
     @rootset.clear
     @id_table.clear
+    @state = :init
   end
 
   # Performs threading on the messages and returns the rootset
   # (set of message containers without parents).
   #
-  # Call this after all #add operations are complete.
-  # This does not sort, use #order! if sorting is necessary.
-  def thread!
-    ret = @rootset
-    @id_table.each_value { |cont| ret << cont if cont.parent.nil? }.clear
-    ret
-  end
-
-  # Performs an in-place sort on messages after thread!
-  # This is optional and intended to be called this only after #thread!
+  # Call this only after all #add operations are complete.
   #
-  # This takes a block which yields an array of Msgthr::Container
-  # objects for sorting.
+  # If given an optional block, it will perform an in-place sort
+  # using the block parameter.
   #
-  # To sort by unique +mid+ identifiers for each container:
+  # To thread and sort by unique +mid+ identifiers for each container:
   #
-  #   msgthr.order! { |ary| ary.sort_by!(&:mid) }
+  #   msgthr.thread! { |ary| ary.sort_by!(&:mid) }
   #
   # If your opaque message pointer contains a +time+ accessor which gives
   # a Time object:
   #
-  #   msgthr.order! do |ary|
+  #   msgthr.thread! do |ary|
   #     ary.sort_by! do |cont| # Msgthr::Container
   #       cur = cont.topmost
   #       cur ? cur.msg.time : Time.at(0)
@@ -67,16 +62,40 @@ class Msgthr
   # Msgthr::Container#mid, as any known missing messages (ghosts)
   # will still have a +mid+.  However, Msgthr::Container#topmost is
   # necessary if accessing Msgthr::Container#msg.
+  def thread!
+    raise StateError, "already #@state" if @state != :init
+    ret = @rootset
+    @id_table.each_value { |cont| ret << cont if cont.parent.nil? }.clear
+    @state = :threaded
+    order! { |ary| yield(ary) } if block_given?
+    ret
+  end
+
+  # Calling this method is unnecessary since msgthr 1.1.0.
+  # In previous releases, the #thread! did not support a block
+  # parameter for ordering.  This method remains for compatibility.
   def order!
+    case @state
+    when :init then raise StateError, "#thread! not called"
+    when :ordered then raise StateError, "already #@state"
+    # else @state == :threaded
+    end
+
     yield @rootset
     @rootset.each do |cont|
       # this calls Msgthr::Container#order!, which is non-recursive
       cont.order! { |children| yield(children) }
     end
+    @state = :ordered
+    @rootset
   end
 
   # non-recursively walk a set of messages after #thread!
-  # (and optionally, #order!)
+  # (and optionally, #order!).
+  #
+  # If you do not care about ordering, you may call this
+  # immediately after all #add operations are complete starting
+  # with msgthr 1.1.0
   #
   # This takes a block and yields 3 elements to it: +|level, container, index|+
   # for each message container.
@@ -95,6 +114,8 @@ class Msgthr
   #     printf("#{indent} % 3d. %s\n", index, subject)
   #   end
   def walk_thread
+    thread! if @state == :init
+    order! { |_| } if @state == :threaded
     i = -1
     q = @rootset.map { |cont| [ 0, cont, i += 1 ] }
     while tmp = q.shift
@@ -128,6 +149,8 @@ class Msgthr
   # calling this method to avoid wasting memory on hash keys.  Likewise
   # is true for any String objects in +refs+.
   def add(mid, refs, msg)
+    @state == :init or raise StateError, "cannot add when already #@state"
+
     cur = @id_table[mid] ||= Msgthr::Container.new(mid)
     cur.msg = msg
     refs or return

data/lib/msgthr/container.rb

@@ -1,9 +1,9 @@
 # Copyright (C) 2016 all contributors <msgthr-public@80x24.org>
 # License: GPL-2.0+ <https://www.gnu.org/licenses/gpl-2.0.txt>
 
-# An internal container class, this is exposed for Msgthr#order!
-# and Msgthr#walk_thread APIs.  They should should not be initialized
-# in your own code.
+# An internal container class, this is exposed for Msgthr#thread!
+# Msgthr#order! and Msgthr#walk_thread APIs through block parameters.
+# They should should not be initialized in your own code.
 #
 # One container object will exist for every message you call Msgthr#add! on,
 # so there can potentially be many of these objects for large sets of

data/msgthr.gemspec

@@ -4,7 +4,7 @@
 Gem::Specification.new do |s|
   manifest = File.read('.manifest').split(/\n/)
   s.name = %q{msgthr}
-  s.version = ENV['VERSION'] || '1.0.1'
+  s.version = ENV['VERSION'] || '1.1.0'
   s.authors = ['msgthr hackers']
   s.summary = 'container-agnostic, non-recursive message threading'
   s.description = File.read('README').split(/\n\n/)[1].strip
@@ -14,4 +14,12 @@ Gem::Specification.new do |s|
   s.files = manifest
   s.licenses = 'GPL-2.0+'
   s.required_ruby_version = '>= 1.9.3'
+
+  if s.respond_to?(:metadata=)
+    s.metadata = {
+      'source_code_uri' => 'https://80x24.org/msgthr.git',
+      'mailing_list_uri' => 'https://80x24.org/msgthr-public/',
+      'bug_tracker_uri' => 'https://80x24.org/msgthr-public/',
+    }
+  end
 end

data/test/test_msgthr.rb

@@ -11,8 +11,9 @@ class TestMsgthr < Test::Unit::TestCase
     thr.add('c', nil, 'c')
     thr.add('D', nil, 'D')
     thr.add('d', %w(missing), 'd')
-    thr.thread!
+    rset = thr.thread!
     rootset = thr.order! { |c| c.sort_by!(&:mid) }
+    assert_same rset, rootset
     assert_equal %w(D c missing), rootset.map(&:mid)
     assert_equal 'D', rootset[0].msg
     assert_equal %w(b), rootset[1].children.map(&:mid)
@@ -30,6 +31,67 @@ class TestMsgthr < Test::Unit::TestCase
        0. abc
    2. [missing: <missing>]
      0. d
+EOF
+    assert_equal exp, out
+  end
+
+  def test_order_in_thread
+    thr = Msgthr.new
+    thr.add(1, nil, 'a')
+    thr.add(2, [1], 'b')
+    thr.thread! do |ary|
+      ary.sort_by! do |cont|
+        cur = cont.topmost
+        cur ? cur : 0
+      end
+    end
+    out = ''
+    thr.walk_thread do |level, container, index|
+      msg = container.msg
+      out << "#{level} [#{index}] #{msg}\n"
+    end
+    exp = <<EOF.b
+0 [0] a
+1 [0] b
+EOF
+    assert_equal exp, out
+  end
+
+  def test_out_of_order
+    thr = Msgthr.new
+    thr.thread!
+    assert_raise(Msgthr::StateError) { thr.add(1, nil, 'a') }
+    thr.clear # make things good again, following should not raise:
+    thr.add(1, nil, 'a')
+    thr.thread!
+    assert_raise(Msgthr::StateError) { thr.thread! }
+
+    out = []
+    thr.walk_thread do |level, container, index|
+      msg = container.msg
+      out << "#{level} [#{index}] #{msg}"
+    end
+    assert_equal [ '0 [0] a' ], out
+    assert_raise(Msgthr::StateError) { thr.thread! { raise "DO NOT CALL" } }
+    assert_raise(Msgthr::StateError) { thr.order! { |_| raise "DO NOT CALL" } }
+
+    # this is legal, even if non-sensical
+    thr.clear
+    thr.walk_thread { |level, container, index| raise "DO NOT CALL" }
+  end
+
+  def test_short_add_to_walk
+    thr = Msgthr.new
+    thr.add(1, nil, 'a')
+    thr.add(2, [1], 'b')
+    out = ''
+    thr.walk_thread do |level, container, index|
+      msg = container.msg
+      out << "#{level} [#{index}] #{msg}\n"
+    end
+    exp = <<EOF.b
+0 [0] a
+1 [0] b
 EOF
     assert_equal exp, out
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: msgthr
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - msgthr hackers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-08 00:00:00.000000000 Z
+date: 2017-12-31 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Pure Ruby message threading based on the algorithm described by
@@ -33,7 +33,10 @@ files:
 homepage: https://80x24.org/msgthr/
 licenses:
 - GPL-2.0+
-metadata: {}
+metadata:
+  source_code_uri: https://80x24.org/msgthr.git
+  mailing_list_uri: https://80x24.org/msgthr-public/
+  bug_tracker_uri: https://80x24.org/msgthr-public/
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -50,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: container-agnostic, non-recursive message threading