mail-sympa 0.1.0

data/CHANGES

@@ -0,0 +1,2 @@
+= 0.1.0 - 13-Apr-2010
+* Initial release

data/MANIFEST

@@ -0,0 +1,7 @@
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* mail-sympa.gemspec
+* lib/mail/sympa.rb
+* test/test_mail_sympa.rb

data/README

@@ -0,0 +1,50 @@
+= Description
+  The mail-sympa library is Ruby interface for the Sympa mailing list management
+  software.
+
+= Prerequisites
+  soap4r 1.5.8 or later
+
+= Installation
+  gem install mail-sympa
+
+= Synopsis (tentative)
+  require 'mail/sympa'
+
+  mail = Mail::Sympa.new(server, namespace)
+  mail.login(email, password)
+
+  # Enumerate over each list and inspect it
+  puts mail.lists.each do |list|
+    p list
+  end
+
+  # Add a user quietly
+  mail.add('foo@bar.com', 'some_list', 'Mr. Foo', true)
+
+= Known Issues
+  The Sympa#add and Sympa#del methods return an empty string instead of
+  a boolean. I am unsure why.
+
+= Future Plans
+  Add wrappers for createList and closeList.
+
+= License
+  Artistic 2.0
+
+= Copyright
+  (C) 2010 Daniel J. Berger, Mark Sallee, David Salisbury
+  All Rights Reserved
+
+= Warranty
+  This library is provided "as is" and without any express or
+  implied warranties, including, without limitation, the implied
+  warranties of merchantability and fitness for a particular purpose.
+
+= Notes
+  See http://www.sympa.org for details.
+
+= Authors
+  Daniel Berger
+  David Salisbury
+  Mark Sallee

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rake'
+require 'rake/testtask'
+include Config
+
+namespace 'gem' do
+  desc 'Remove any existing gem file'
+  task :clean do
+    Dir['*.gem'].each{ |f| File.delete(f) }
+  end
+
+  desc 'Build the mail-sympa gem'
+  task :build => [:clean] do
+    spec = eval(IO.read('mail-sympa.gemspec'))
+    Gem::Builder.new(spec).build
+  end
+
+  desc 'Install the mail-sympa gem'
+  task :install => [:build] do
+    file = Dir["*.gem"].first
+    sh "gem install #{file}"
+  end
+end
+
+Rake::TestTask.new('test') do |t|
+  t.warning = true
+  t.verbose = true
+end

data/lib/mail/sympa.rb

@@ -0,0 +1,233 @@
+require 'soap/rpc/driver'
+
+# The Mail module serves as a namespace only.
+module Mail
+  # The Sympa module encapsulates the various Sympa server SOAP methods
+  class Sympa
+    # Error class raised in some cases if a Mail::Sympa method fails.
+    class Error < StandardError; end
+
+    # The version of the mail-sympa library.
+    VERSION = '0.1.0'
+
+    # The session cookie returned by the login method.
+    attr_reader :cookie
+
+    # The endpoint URL of the SOAP service.
+    attr_reader :endpoint
+
+    # The URN namespace. The default is 'urn:sympasoap'.
+    attr_reader :namespace
+
+    # Creates and returns a new Mail::Sympa object based on the +endpoint+
+    # (the endpoint URL) and a +namespace+ which defaults to 'urn:sympasoap'.
+    #
+    # Example:
+    #
+    #   sympa = Mail::Sympa.new('http://your.sympa.home/sympasoap')
+    #
+    def initialize(endpoint, namespace = 'urn:sympasoap')
+      @endpoint  = endpoint.to_s # Allow for URI objects
+      @namespace = namespace
+
+      @soap = SOAP::RPC::Driver.new(endpoint, namespace)
+
+      @email    = nil
+      @password = nil
+      @cookie   = nil
+
+      @soap.add_method('login', 'email', 'password')
+  
+      @soap.add_method(
+        'authenticateAndRun',
+        'email',
+        'cookie',
+        'service',
+        'parameters'
+      )
+
+      @soap.add_method(
+        'authenticateRemoteAppAndRun',
+        'appname',
+        'apppassword',
+        'vars',
+        'service',
+        'parameters'
+      )
+    end
+
+    # Authenticate with the Sympa server. This method must be called before
+    # any other methods can be used successfully.
+    #
+    # Example:
+    #
+    #  sympa = Mail::Sympa.new(url)
+    #  sympa.login(email, password)
+    #
+    def login(email, password) 
+      @email    = email
+      @password = password
+      @cookie   = @soap.login(email, password)
+    end
+
+    # Returns an array of available mailing lists based on +topic+ and
+    # +sub_topic+. If +sub_topic+ is nil then all sub-topics are returned.
+    # If +topic+ is nil then all lists are returned.
+    #
+    # The returned lists contains an array of strings. If you prefer objects
+    # with methods corresponding to keys, see complex_lists instead.
+    #
+    # Example:
+    #
+    #  sympa = Mail::Sympa.new(url)
+    #  sympa.login(email, password)
+    #
+    #  sympa.lists.each{ |list| puts list }
+    #
+    def lists(topic='', sub_topic='')
+      raise Error 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'lists', [topic, sub_topic])
+    end
+
+    # Returns an array of available mailing lists in complex object format,
+    # i.e. these are SOAP::Mapping objects that you can call methods on.
+    #
+    # Example:
+    #
+    #  sympa = Mail::Sympa.new(url)
+    #  sympa.login(email, password)
+    #
+    #  sympa.complex_lists.each{ |list|
+    #    puts list.subject
+    #    puts list.homepage
+    #  }
+    #
+    def complex_lists(topic='', sub_topic='')
+      raise Error 'must login first' unless @cookie
+      args = [topic, sub_topic]
+      @soap.authenticateAndRun(@email, @cookie, 'complexLists', args)
+    end
+
+    alias complexLists complex_lists
+
+    # Returns a description about the given +list_name+. This is a
+    # SOAP::Mapping object.
+    #
+    # Example:
+    #
+    #  sympa = Mail::Sympa.new(url)
+    #  sympa.login(email, password)
+    #
+    #  info = sympa.info(list)
+    #
+    #  puts info.subject
+    #  puts info.homepage
+    #  puts info.isOwner
+    #
+    def info(list_name)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'info', [list_name])
+    end
+
+    # Returns an array of members that belong to the given +list_name+.
+    #
+    # Example:
+    #
+    #  sympa = Mail::Sympa.new(url)
+    #  sympa.login(email, password)
+    #
+    #  sympa.review(list)
+    #
+    def review(list_name)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'review', [list_name])
+    end
+
+    # Returns an array of lists that the +user+ is subscribed to. The +user+
+    # should include the proxy variable setup in the trusted_applications.conf
+    # file.
+    #
+    # The +app_name+ is whatever is set in your trusted_applications.conf file.
+    # The +app_password+ for that app must also be provided.
+    # 
+    # Example:
+    #
+    #   sympa = Mail::Sympa.new(url)
+    #   sympa.login(email, password)
+    #
+    #   # If vars contains USER_EMAIL
+    #   sympa.which('USER_EMAIL=some_user@foo.com', 'my_app', 'my_password')
+    #
+    # An alternative is to use complex_lists + review, though it's slower.
+    #
+    def which(user, app_name, app_passwd)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateRemoteAppAndRun(app_name, app_passwd, user, 'which', [''])
+    end
+
+    # Same as the Sympa#which method, but returns an array of SOAP::Mapping
+    # objects that you can call methods on.
+    #
+    def complex_which(user, app_name, app_passwd)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateRemoteAppAndRun(app_name, app_passwd, user, 'complexWhich', [''])
+    end
+
+    alias complexWhich complex_which
+
+    # Returns a boolean indicating whether or not +user+ has +function+
+    # on +list_name+. The two possible values for +function+ are 'editor'
+    # and 'owner'.
+    #
+    def am_i?(user, list_name, function = 'editor')
+      raise Error, 'must login first' unless @cookie
+
+      unless ['editor', 'owner'].include?(function)
+        raise Error, 'invalid function name "#{editor}"'
+      end
+
+      @soap.authenticateAndRun(@email, @cookie, 'amI', [list_name, function, user])
+    end
+
+    alias amI am_i?
+
+    # Adds the given +email+ to +list_name+ using +name+ (gecos). If +quiet+
+    # is set to true (the default) then no email notification is sent.
+    #--
+    # TODO: Determine why this method does not return a boolean.
+    #
+    def add(email, list_name, name, quiet=true)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'add', [list_name, email, name, quiet])
+    end
+
+    # Deletes the given +email+ from +list_name+. If +quiet+ is set to true
+    # (the default) then no email notification is sent.
+    #--
+    # TODO: Determine why this method does not return a boolean.
+    #
+    def del(email, list_name, quiet=true)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'del', [list_name, email, quiet])
+    end
+
+    # Subscribes the currently logged in user to +list_name+. By default the
+    # +name+ (gecos) will be the email address.
+    #
+    def subscribe(list_name, name = @email)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'subscribe', [list_name, name])
+    end
+
+    # Removes the currently logged in user from +list_name+.
+    #
+    def signoff(list_name)
+      raise Error, 'must login first' unless @cookie
+      @soap.authenticateAndRun(@email, @cookie, 'signoff', [list_name, @email])
+    end
+
+    alias delete del
+    alias unsubscribe signoff
+    alias url endpoint
+  end
+end

data/mail-sympa.gemspec

@@ -0,0 +1,26 @@
+require 'rubygems'
+
+Gem::Specification.new do |gem|
+  gem.name        = 'mail-sympa'
+  gem.version     = '0.1.0' 
+  gem.authors     = ['Daniel J. Berger', 'David Salisbury', 'Mark Sallee']
+  gem.license     = 'Artistic 2.0'
+  gem.description = 'Ruby interface for the Sympa mailing list server'
+  gem.email       = 'djberg96@gmail.com'
+  gem.files       = Dir['**/*'].reject{ |f| f.include?('git') }
+  gem.test_files  = ['test/test_mail_sympa.rb']
+  gem.has_rdoc    = true
+  gem.homepage    = 'http://github.com/djberg96/mail-sympa'
+
+  gem.extra_rdoc_files  = ['README', 'CHANGES', 'MANIFEST']
+
+  gem.add_dependency('soap4r', '>= 1.5.8')
+
+  gem.summary = <<-EOF
+    The mail-sympa library provides a Ruby interface to the Sympa mailing
+    list server software. This is a convenient and pretty wrapper for the
+    various SOAP functions that Sympa server publishes.
+
+    See http://www.sympa.org for more information.
+  EOF
+end

data/test/test_mail_sympa.rb

@@ -0,0 +1,290 @@
+##############################################################################
+# test_mail_sympa.rb
+#
+# This is the test suite for the mail-sympa library. You should run these
+# tests via the test rake task.
+#
+# In order for these tests to run successfully you must use the dbi-dbrc
+# library, and create an entry for 'test_sympa'. The user name should include
+# the full domain, e.g. foo@bar.org. and the driver should be set to the URL:
+#
+# test_sympa postmaster@foo.org xxx http://foo.bar.org/sympasoap
+#
+# For all tests to complete successfully, you must use admin credentials.
+##############################################################################
+require 'rubygems'
+gem 'test-unit'
+
+require 'test/unit'
+require 'mail/sympa'
+require 'dbi/dbrc'
+
+class MailSympaTest < Test::Unit::TestCase
+  def self.startup
+    @@info = DBI::DBRC.new('test_sympa')
+    @@url  = @@info.driver
+  end
+
+  def setup
+    @mail  = Mail::Sympa.new(@@url)
+    @user  = @@info.user
+    @pass  = @@info.passwd
+    @list  = 'testlist'
+    @nosub = 'partners'
+  end
+
+  # Because most methods won't work without logging in first
+  def login
+    @mail.login(@user, @pass)
+  end
+
+  test "version constant is expected value" do
+    assert_equal('0.1.0', Mail::Sympa::VERSION)
+  end
+
+  test "endpoint method basic functionality" do
+    assert_respond_to(@mail, :endpoint)
+    assert_nothing_raised{ @mail.endpoint }
+    assert_kind_of(String, @mail.endpoint)
+  end
+
+  test "endpoint method returns expected result" do
+    assert_equal(@@url, @mail.endpoint)
+  end
+
+  test "endpoint method is a readonly attribute" do
+    assert_raise(NoMethodError){ @mail.endpoint = 'foo' }
+  end
+
+  test "namespace method basic functionality" do
+    assert_respond_to(@mail, :namespace)
+    assert_nothing_raised{ @mail.namespace }
+    assert_kind_of(String, @mail.namespace)
+  end
+
+  test "namespace method returns expected result" do
+    assert_equal("urn:sympasoap", @mail.namespace)
+  end
+
+  test "namespace method is a readonly attrubite" do
+    assert_raise(NoMethodError){ @mail.namespace = 'foo' }
+  end
+
+  test "login method basic functionality" do
+    assert_respond_to(@mail, :login)
+  end
+
+  test "login method works as expected with proper credentials" do
+    assert_nothing_raised{ @mail.login(@user, @pass) }
+    assert_not_nil(@mail.cookie)
+    assert_kind_of(String, @mail.login(@user, @pass))
+  end
+
+  test "login method raises an error if the credentials are invalid" do
+    assert_raise(SOAP::FaultError){ @mail.login('bogus', 'bogus') }
+  end
+
+  test "login method requires two arguments" do
+    assert_raise(ArgumentError){ @mail.login }
+    assert_raise(ArgumentError){ @mail.login('bogus') }
+  end
+
+  test "lists method basic functionality" do
+    login
+    assert_respond_to(@mail, :lists)
+    assert_nothing_raised{ @mail.lists }
+  end
+
+  test "lists method with no arguments returns all lists" do
+    login
+    assert_kind_of(Array, @mail.lists)
+    assert_kind_of(String, @mail.lists.first)
+  end
+
+  test "lists method accepts a topic and subtopic" do
+    login
+    assert_kind_of(Array, @mail.lists(@list))
+    assert_kind_of(Array, @mail.lists(@list, @list))
+  end
+
+  test "lists method returns empty array if topic or subtopic is not found" do
+    login
+    assert_equal([], @mail.lists('bogus'))
+    assert_equal([], @mail.lists(@list, 'bogus'))
+  end
+
+  test "lists method accepts a maximum of two arguments" do
+    assert_raise(ArgumentError){ @mail.lists(@list, @list, @list) }
+  end
+
+  test "complex_lists method basic functionality" do
+    login
+    assert_respond_to(@mail, :complex_lists)
+    assert_nothing_raised{ @mail.complex_lists }
+  end
+
+  test "complex_lists method with no arguments returns all lists" do
+    login
+    assert_kind_of(Array, @mail.lists)
+    assert_kind_of(SOAP::Mapping::Object, @mail.complex_lists.first)
+  end
+
+  test "complex_lists method accepts a topic and subtopic" do
+    login
+    assert_kind_of(Array, @mail.complex_lists(@list))
+    assert_kind_of(Array, @mail.complex_lists(@list, @list))
+  end
+
+  test "lists method returns empty array if topic or subtopic is not found" do
+    login
+    assert_equal([], @mail.complex_lists('bogus'))
+    assert_equal([], @mail.complex_lists(@list, 'bogus'))
+  end
+
+  test "lists method accepts a maximum of two arguments" do
+    assert_raise(ArgumentError){ @mail.complex_lists(@list, @list, @list) }
+  end
+
+  test "info method basic functionality" do
+    login
+    assert_respond_to(@mail, :info)
+    assert_nothing_raised{ @mail.info(@list) }
+  end
+
+  test "info method expected results" do
+    login
+    assert_kind_of(SOAP::Mapping::Object, @mail.info(@list))
+  end
+
+  test "review method basic functionality" do
+    login
+    assert_respond_to(@mail, :review)
+    assert_nothing_raised{ @mail.review(@list) }
+  end
+
+  test "review method returns expected results" do
+    login
+    assert_kind_of(Array, @mail.review(@list))
+    assert_kind_of(String, @mail.review(@list).first)
+  end
+
+  test "review method returns 'no_subscribers' if list has no subscribers" do
+    login
+    assert_equal(['no_subscribers'], @mail.review(@nosub))
+  end
+
+  test "review method raises an error if list isn't found" do
+    login
+    assert_raise(SOAP::FaultError){ @mail.review('bogusxxxyyyzzz') }
+  end
+
+  test "which basic functionality" do
+    assert_respond_to(@mail, :which)
+  end
+
+  test "complex_which basic functionality" do
+    assert_respond_to(@mail, :complex_which)
+  end
+
+  test "complexWhich is an alias for complex_which" do
+    assert_alias_method(@mail, :complexWhich, :complex_which)
+  end
+
+  test "am_i basic functionality" do
+    login
+    assert_respond_to(@mail, :am_i?)
+    assert_nothing_raised{ @mail.am_i?(@user, @list) }
+    assert_nothing_raised{ @mail.am_i?(@user, @list, 'owner') }
+  end
+
+  test "am_i returns expected result" do
+    login
+    assert_boolean(@mail.am_i?(@user, @list))
+  end
+
+  test "am_i function name must be owner or editor" do
+    assert_raise(Mail::Sympa::Error){ @mail.am_i?(@user, @list, 'bogus') }
+  end
+
+  test "amI is an alias for am_i?" do
+    assert_alias_method(@mail, :amI, :am_i?)
+  end
+
+  test "add basic functionality" do
+    assert_respond_to(@mail, :add)
+  end
+
+  test "add returns expected result" do
+    login
+    notify("The documentation says this should return a boolean")
+    assert_boolean(@mail.add('test@foo.com', @list, 'test'))
+  end
+
+  test "add requires at least three arguments" do
+    assert_raise(ArgumentError){ @mail.add }
+    assert_raise(ArgumentError){ @mail.add('test@foo.com') }
+    assert_raise(ArgumentError){ @mail.add('test@foo.com', @list) }
+  end
+
+  test "del basic functionality" do
+    assert_respond_to(@mail, :del)
+  end
+
+  test "del returns expected result" do
+    login
+    notify("The documentation says this should return a boolean")
+    assert_boolean(@mail.del('test@foo.com', @list))
+  end
+
+  test "delete is an alias for del" do
+    assert_alias_method(@mail, :delete, :del)
+  end
+
+  test "del requires at least two arguments" do
+    assert_raise(ArgumentError){ @mail.delete }
+    assert_raise(ArgumentError){ @mail.delete('test@foo.com') }
+  end
+
+  test "subscribe basic functionality" do
+    assert_respond_to(@mail, :subscribe)
+  end
+
+  test "subscribe expected results" do
+    login
+    assert_boolean(@mail.subscribe(@list, 'test'))
+  end
+
+  test "subscribe requires at least one argument" do
+    assert_raise(ArgumentError){ @mail.subscribe }
+  end
+
+  test "signoff basic functionality" do
+    assert_respond_to(@mail, :signoff)
+  end
+
+  test "signoff expected results" do
+    login
+    assert_boolean(@mail.signoff(@list))
+  end
+
+  test "unsubscribe is an alias for signoff" do
+    assert_alias_method(@mail, :unsubscribe, :signoff)
+  end
+
+  test "signoff requires one argument only" do
+    assert_raise(ArgumentError){ @mail.signoff }
+    assert_raise(ArgumentError){ @mail.signoff(@user, @list) }
+  end
+
+  def teardown
+    @mail = nil
+    @user = nil
+    @pass = nil
+    @list = nil
+  end
+
+  def self.shutdown
+    @@url  = nil
+    @@info = nil
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: mail-sympa
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Daniel J. Berger
+- David Salisbury
+- Mark Sallee
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-13 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: soap4r
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.5.8
+    version: 
+description: Ruby interface for the Sympa mailing list server
+email: djberg96@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+- MANIFEST
+files: 
+- CHANGES
+- lib/mail/sympa.rb
+- mail-sympa.gemspec
+- MANIFEST
+- Rakefile
+- README
+- test/test_mail_sympa.rb
+has_rdoc: true
+homepage: http://github.com/djberg96/mail-sympa
+licenses: 
+- Artistic 2.0
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: The mail-sympa library provides a Ruby interface to the Sympa mailing list server software. This is a convenient and pretty wrapper for the various SOAP functions that Sympa server publishes.  See http://www.sympa.org for more information.
+test_files: 
+- test/test_mail_sympa.rb