= Overview

Sympa::SOAP::Client is a pure-Ruby client for programmatically interacting with a Sympa mailing-list server via the SOAP protocol.

== For details on the SOAP Protocol, refer to the {Wikipedia SOAP Protocol description}[http://en.wikipedia.org/wiki/SOAP]

== For details on the Sympa/SOAP Web-Service, refer to the {Sympa SOAP manual}[http://www.sympa.org/manual/soap]

= Requirements
    
- {patron}[http://patron/] for the HTTP handling
- {savon}[http://savonrb.com/] for the SOAP processing
- {yaml}[http://toto/truc.txt] for the YAML parsing
- {nokogiri}[http://nokogiri.org] for the XML parsing

= Installation

    $ sudo gem install sympa-soap-client

= Examples

== Simple cases

=== Listing lists

    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'
    require 'pp'

    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      pp lists
    end

=== Creating a list

    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'

    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      pp create_list :list_name   => 'some.list@domain.tld',
                     :subject     => 'shiny.user@domain.tld',
                     :template    => '',
                     :description => 'SHINY User',
                     :topics      => true
    end

=== Adding some user to a list

    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'

    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      pp add :list_name  => 'some.list@domain.tld',
             :user_email => 'shiny.user@domain.tld',
             :gecos      => 'SHINY User',
             :quiet      => true
    end

=== Removing some user from a list
    
    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'

    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      pp del :list_name  => 'some.list@domain.tld',
             :user_email => 'shiny.user@domain.tld',
             :quiet      => true
    end
    
=== Closing a list
    
    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'

    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      pp close_list :list_name  => 'some.list@domain.tld'
    end
    

== Complex cases

=== Populating some list with users picked-up form a csv-file.

    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'

    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      list_name = 'some.list@domain.tld'
      File.open('users.csv').each_line do |user|
        user_email,gecos = user.split(';')
        if add :list_name  => list_name,
               :user_email => user_email,
               :gecos      => gecos,
               :quiet      => true
        then
          puts "User '#{gecos}' added successfully to the list '#{list_name}'"
        else
          puts "An error occured adding user '#{gecos}' to the list '#{list_name}'"
        end
      end
    end

=== Updating mailing-lists according to users properties

    require 'rugygems'
    require 'sympa/auth/cas'
    require 'sympa/soap/client'
    require 'sequel'

    # create an in-memory sqlite database
    db = Sequel.sqlite
    db.create_table :lists do
      primary_key :id
      String :name
    end
    db.create_table :subscribers do
      primary_key :id
      Integer :list_id
      String  :email
    end
    mailing_lists     = db[:lists]
    lists_subscribers = db[:subscribers]

    # connect to the sympa SOAP service
    Sympa::SOAP::Client.new(
       :service_uri           => 'https://lists.domain.tld',
       :authentication_helper => Sympa::Auth::Cas.new(
          :credential_file    => File.expand_path('~/.auth_file')
       )
    ) do
      complex_lists.each do |complex_list|
        review(:list_name => complex_list[:toto]).each do |subscriber|
          

        end

        File.open('users.csv').each_line do |user|
          user_email,gecos,status,building,stage, = user.split(';')
          if add :list_name  => list_name,
                 :user_email => user_email,
                 :gecos      => gecos,
                 :quiet      => true
          then
            puts "User '#{gecos}' added successfully to the list '#{list_name}'"
          else
            puts "An error occured while adding user '#{gecos}' to the list '#{list_name}'"
          end
        end
      end
    end





= Credits

Author:: {David Delavennat}[mailto:sympa-soap-client.project@u-psud.fr]
 
= Licence (BSD)

 Copyright (c) 2011 David Delavennat

 Permission to use, copy, modify, and distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
 copyright notice and this permission notice appear in all copies.

 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER
 IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
--
 $Id$
++