Move code to unique ClockworkSMS namespace

README.md

@@ -12,15 +12,15 @@ Full documentation is at [http://rubydoc.info/github/mediaburst/clockwork-ruby/m
 
 ## Usage
 
-For more information on the available optional parameters for the API (Clockwork::API), see [here][4].
+For more information on the available optional parameters for the API (ClockworkSMS::API), see [here][4].
 
-For more information on the available optional parameters for each SMS (Clockwork::SMS), see [here][5]. For more information on the response object returned from each SMS (Clockwork::SMS::Response), see [here][6].
+For more information on the available optional parameters for each SMS (ClockworkSMS::SMS), see [here][5]. For more information on the response object returned from each SMS (ClockworkSMS::SMS::Response), see [here][6].
 
 ### Send a single SMS message
 
 ```ruby
 require 'clockwork'
-api = Clockwork::API.new( 'API_KEY_GOES_HERE' )
+api = ClockworkSMS::API.new( 'API_KEY_GOES_HERE' )
 message = api.messages.build( :to => '441234123456', :content => 'This is a test message.' )
 response = message.deliver
 
@@ -36,7 +36,7 @@ end
 
 ```ruby
 require 'clockwork'
-api = Clockwork::API.new( 'API_KEY_GOES_HERE' )
+api = ClockworkSMS::API.new( 'API_KEY_GOES_HERE' )
 
 message = api.messages.build
 message.to = '441234123456'
@@ -53,7 +53,7 @@ end
 
 ### Send multiple SMS messages (with an optional client ID)
 
-You should not use the `Clockwork::Message#deliver` method for each message, but instead use the `Clockwork::API#deliver` method to send multiple messages in the same API request. This will decrease load on the API and ensure your requests are processed significantly faster.
+You should not use the `ClockworkSMS::Message#deliver` method for each message, but instead use the `ClockworkSMS::API#deliver` method to send multiple messages in the same API request. This will decrease load on the API and ensure your requests are processed significantly faster.
 
 ```ruby
 
@@ -67,7 +67,7 @@ messages = [
 ]
 
 require 'clockwork'
-api = Clockwork::API.new( 'API_KEY_GOES_HERE' )
+api = ClockworkSMS::API.new( 'API_KEY_GOES_HERE' )
 messages.each do |m|
     api.messages.build(m)
 end
@@ -88,8 +88,8 @@ end
 
 ```ruby
 require 'clockwork'
-api = Clockwork::API.new( 'API_KEY_GOES_HERE' )
-balance = Clockwork::API.balance
+api = ClockworkSMS::API.new( 'API_KEY_GOES_HERE' )
+balance = ClockworkSMS::API.balance
 puts balance # => { :account_type => "PAYG", :balance => 575.23, :currency => { :code => "GBP", :symbol => "£" } }
 ```
 

lib/clockwork_sms.rb

@@ -0,0 +1,16 @@
+lib_dir = File.expand_path(File.dirname(__FILE__))
+$LOAD_PATH.unshift lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'net/http'
+require 'net/https'
+require 'openssl'
+require 'nokogiri'
+
+require 'clockwork_sms/error'
+require 'clockwork_sms/http'
+require 'clockwork_sms/xml/xml'
+
+require 'clockwork_sms/message_collection'
+require 'clockwork_sms/api'
+require 'clockwork_sms/sms'
+require 'clockwork_sms/sms/response'

lib/clockwork/api.rb → lib/clockwork_sms/api.rb

@@ -1,11 +1,11 @@
-# A wrapper around the Clockwork API.
-module Clockwork
+# A wrapper around the ClockworkSMS API.
+module ClockworkSMS
 
   # Current API wrapper version
   VERSION = '1.2.1'
 
   # @author James Inman <james@mediaburst.co.uk>
-  # You must create an instance of Clockwork::API to begin using the API.
+  # You must create an instance of ClockworkSMS::API to begin using the API.
   class API
 
     # URL of the SMS API send action
@@ -15,62 +15,62 @@ class API
     # URL of the SMS API check balance action
     BALANCE_URL = "api.clockworksms.com/xml/balance"    
 
-    # API key provided in Clockwork::API#initialize.
+    # API key provided in ClockworkSMS::API#initialize.
     # @return [string] 
     attr_reader :api_key
 
     # This is the number of messages to concatenate (join together). 
     # @raise ArgumentError - if a value less than 2 or more than 3 is passed
     # @return [symbol] One of +error+, +:replace+, +:remove+ 
-    # @note Defaults to 3 if not set and Clockwork::API#long is set to +true+.
+    # @note Defaults to 3 if not set and ClockworkSMS::API#long is set to +true+.
     attr_reader :concat
 
     # @!attribute from
     # The from address displayed on a phone when the SMS is received. This can be either a 12 digit number or 11 characters long.
     # @return [string] 
-    # @note This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.
+    # @note This can be overriden for specific ClockworkSMS::SMS objects; if it is not set your account default will be used.
     attr_accessor :from
 
-    # What to do with any invalid characters in the message content. +:error+ will raise a Clockwork::InvalidCharacterException, +:replace+ will replace a small number of common invalid characters, such as the smart quotes used by Microsoft Office with a similar match, +:remove+ will remove invalid characters.
+    # What to do with any invalid characters in the message content. +:error+ will raise a ClockworkSMS::InvalidCharacterException, +:replace+ will replace a small number of common invalid characters, such as the smart quotes used by Microsoft Office with a similar match, +:remove+ will remove invalid characters.
     # @raise ArgumentError - if value is not one of +:error+, +:replace+, +:remove+
     # @return [symbol] One of +error+, +:replace+, +:remove+ 
-    # @note This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.
+    # @note This can be overriden for specific ClockworkSMS::SMS objects; if it is not set your account default will be used.
     attr_reader :invalid_char_action
 
     # @!attribute long
     # Set to +true+ to enable long SMS. A standard text can contain 160 characters, a long SMS supports up to 459. Each recipient will cost up to 3 message credits.
     # @return [boolean]
-    # @note This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.
+    # @note This can be overriden for specific ClockworkSMS::SMS objects; if it is not set your account default will be used.
     attr_accessor :long
 
     # @!attribute messages
-    # Returns a Clockwork::MessageCollection containing all built SMS messages.
-    # @return [Clockwork::MessageCollection]
+    # Returns a ClockworkSMS::MessageCollection containing all built SMS messages.
+    # @return [ClockworkSMS::MessageCollection]
     attr_reader :messages
 
-    # Password provided in Clockwork::API#initialize.
+    # Password provided in ClockworkSMS::API#initialize.
     # @return [string]
     # @deprecated Use api_key instead.
     attr_reader :password
 
     # @!attribute truncate
     # Set to +true+ to trim the message content to the maximum length if it is too long.
     # @return [boolean] 
-    # @note This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.
+    # @note This can be overriden for specific ClockworkSMS::SMS objects; if it is not set your account default will be used.
     attr_accessor :truncate
 
     # Whether to use SSL when connecting to the API.
     # Defaults to +true+
     # @return [boolean] 
     attr_accessor :use_ssl
 
-    # Username provided in Clockwork::API#initialize.
+    # Username provided in ClockworkSMS::API#initialize.
     # @return [string]
     # @deprecated Use api_key instead.
     attr_reader :username
 
-    # Alias for Clockwork::API#credit to preserve backwards compatibility with original Mediaburst API.
-    # @deprecated Use Clockwork::API#credit. Support for Clockwork::API#get_credit will be removed in a future version of this wrapper.
+    # Alias for ClockworkSMS::API#credit to preserve backwards compatibility with original Mediaburst API.
+    # @deprecated Use ClockworkSMS::API#credit. Support for ClockworkSMS::API#get_credit will be removed in a future version of this wrapper.
     def get_credit
       credit
     end
@@ -93,11 +93,11 @@ def concat= number
     #   @param [hash] options Optional hash of attributes on API
     #   @deprecated Use an API key instead. Support for usernames and passwords will be removed in a future version of this wrapper.
     # @raise ArgumentError - if more than 3 parameters are passed
-    # @raise Clockwork::Error::InvalidAPIKey - if API key is invalid
-    # Clockwork::API is initialized with an API key, available from http://www.mediaburst.co.uk/api.
+    # @raise ClockworkSMS::Error::InvalidAPIKey - if API key is invalid
+    # ClockworkSMS::API is initialized with an API key, available from http://www.mediaburst.co.uk/api.
     def initialize *args
       if args.size == 1 || ( args.size == 2 && args[1].kind_of?(Hash) ) 
-        raise Clockwork::Error::InvalidAPIKey unless args[0][/^[A-Fa-f0-9]{40}$/]
+        raise ClockworkSMS::Error::InvalidAPIKey unless args[0][/^[A-Fa-f0-9]{40}$/]
         @api_key = args[0]
       elsif args.size == 2 || ( args.size == 3 && args[2].kind_of?(Hash) ) 
         raise ArgumentError, "You must pass both a username and password." if args[0].empty? || args[1].empty?
@@ -111,35 +111,35 @@ def initialize *args
 
       @use_ssl = true if @use_ssl.nil?
       @concat = 3 if @concat.nil? && @long
-      @messages ||= Clockwork::MessageCollection.new( :api => self )
+      @messages ||= ClockworkSMS::MessageCollection.new( :api => self )
       @invalid_char_action = [nil, :error, :remove, :replace].index(@invalid_char_action) if @invalid_char_action
       @truncate = @truncate ? true : false unless @truncate.nil?
     end
 
     # Check the remaining credit for this account.
-    # @raise Clockwork::Error::Authentication - if API login details are incorrect
+    # @raise ClockworkSMS::Error::Authentication - if API login details are incorrect
     # @return [integer] Number of messages remaining    
     def credit
-      xml = Clockwork::XML::Credit.build( self )
-      response = Clockwork::HTTP.post( Clockwork::API::CREDIT_URL, xml, @use_ssl )
-      credit = Clockwork::XML::Credit.parse( response )
+      xml = ClockworkSMS::XML::Credit.build( self )
+      response = ClockworkSMS::HTTP.post( ClockworkSMS::API::CREDIT_URL, xml, @use_ssl )
+      credit = ClockworkSMS::XML::Credit.parse( response )
     end
 
     # Check the remaining credit for this account.
-    # @raise Clockwork::Error::Authentication - if API login details are incorrect
+    # @raise ClockworkSMS::Error::Authentication - if API login details are incorrect
     # @return [integer] Number of messages remaining    
     def balance
-      xml = Clockwork::XML::Balance.build( self )
-      response = Clockwork::HTTP.post( Clockwork::API::BALANCE_URL, xml, @use_ssl )
-      balance = Clockwork::XML::Balance.parse( response )
+      xml = ClockworkSMS::XML::Balance.build( self )
+      response = ClockworkSMS::HTTP.post( ClockworkSMS::API::BALANCE_URL, xml, @use_ssl )
+      balance = ClockworkSMS::XML::Balance.parse( response )
     end
 
-    # Deliver multiple messages created using Clockwork::API#messages.build.
-    # @return [array] Array of Clockwork::SMS::Response objects for messages.    
+    # Deliver multiple messages created using ClockworkSMS::API#messages.build.
+    # @return [array] Array of ClockworkSMS::SMS::Response objects for messages.
     def deliver
-      xml = Clockwork::XML::SMS.build_multiple( self.messages )
-      http_response = Clockwork::HTTP.post( Clockwork::API::SMS_URL, xml, @use_ssl )
-      responses = Clockwork::XML::SMS.parse_multiple( self.messages, http_response )
+      xml = ClockworkSMS::XML::SMS.build_multiple( self.messages )
+      http_response = ClockworkSMS::HTTP.post( ClockworkSMS::API::SMS_URL, xml, @use_ssl )
+      responses = ClockworkSMS::XML::SMS.parse_multiple( self.messages, http_response )
     end
 
   end

lib/clockwork/error.rb → lib/clockwork_sms/error.rb

@@ -1,6 +1,6 @@
-module Clockwork
+module ClockworkSMS
 
-  # Module containing Clockwork::Error classes, all of which extend StandardError.
+  # Module containing ClockworkSMS::Error classes, all of which extend StandardError.
   module Error
 
     # @author James Inman <james@mediaburst.co.uk>

lib/clockwork/http.rb → lib/clockwork_sms/http.rb

@@ -1,4 +1,4 @@
-module Clockwork
+module ClockworkSMS
 
   # @author James Inman <james@mediaburst.co.uk>
   # Wrapper around NET/HTTP
@@ -26,7 +26,7 @@ def self.post url, data = '', use_ssl = true
 
       req.content_type = "text/xml"
       req.body = data
-      req.add_field "User-Agent", "Clockwork Ruby Wrapper/#{Clockwork::VERSION}"
+      req.add_field "User-Agent", "ClockworkSMS Ruby Wrapper/#{ClockworkSMS::VERSION}"
 
       response = socket.start do |http|
         http.request( req )

lib/clockwork_sms/message_collection.rb

@@ -0,0 +1,39 @@
+module ClockworkSMS
+
+  # @author James Inman <james@mediaburst.co.uk>
+  # Use an instance of ClockworkSMS::API#messages.build to create SMS messages.
+  class MessageCollection
+
+    # @!attribute api
+    # An instance of ClockworkSMS::API.
+    # @return [ClockworkSMS::API]
+    attr_accessor :api
+
+    # @!attribute messages
+    # An array of ClockworkSMS::SMS messages.
+    # @return [array]    
+    attr_accessor :messages
+
+    # @param [hash] options Hash of attributes which must include an instance of ClockworkSMS::API
+    # @raise ArgumentError - if a valid instance of API is not passed as :api in options 
+    # Create a new instance of ClockworkSMS::MessageCollection.
+    def initialize options
+      @api = options[:api]
+      raise ArgumentError, "ClockworkSMS::MessageCollection#new must include an instance of ClockworkSMS::API as :api" unless @api.kind_of?(ClockworkSMS::API)
+
+      @messages = []
+    end
+
+    # @param [hash] params Hash of parameters as attributes on ClockworkSMS::SMS
+    # @see ClockworkSMS::SMS
+    # Create a new instance of ClockworkSMS::SMS in this MessageCollection.
+    def build params = {}
+      sms = ClockworkSMS::SMS.new({ :api => @api }.merge(params))
+      sms.wrapper_id = @messages.count
+      @messages << sms
+      sms
+    end
+
+  end
+
+end