Nabaztag 0.2.0 → 0.3.0

data/CHANGES

@@ -1,5 +1,10 @@
 = Changes
 
+== 0.3.0
+
+* Understands new XML responses from API
+* Significant refactoring of response handling
+
 == 0.2.0
 
 * Version 2 API support

data/lib/nabaztag.rb

@@ -1,14 +1,12 @@
-# This file is in UTF-8
-
-require 'cgi'
-require 'open-uri'
-require 'iconv'
+require 'nabaztag/message'
+require 'nabaztag/response'
+require 'nabaztag/choreography'
 
 #
-# Nabaztag allows control of the text-to-speech, ear control, and choreography features of 
+# Nabaztag allows control of the text-to-speech, ear control, and choreography features of
 # Nabaztag devices.
 #
-# To use this library, you need to know the MAC of the device (written on the base) and its 
+# To use this library, you need to know the MAC of the device (written on the base) and its
 # API token. The token must be obtained from http://www.nabaztag.com/vl/FR/api_prefs.jsp .
 #
 # The API allows different commands to be dispatched simultaneously; in order to achieve this,
@@ -20,7 +18,7 @@ require 'iconv'
 #   nabaztag.move_ears(4, 4)  # Still not sent
 #   nabaztag.send             # Messages sent
 #
-# This also means that if two conflicting commands are issued without an intervening send, 
+# This also means that if two conflicting commands are issued without an intervening send,
 # only the latter will be carried out.
 #
 # However, beware! The API doesn't seem to respond well if multiple commands are sent in
@@ -30,38 +28,20 @@ require 'iconv'
 # text-to-speech and choreography are sent in one request, only the speech will get through
 # to the rabbit.
 #
-# With version 2 of the API, it is now possible to specify a voice for the message. The 
-# default is determined by the rabbit's language (claire22s for French; heather22k for 
-# English). The voice's language overrides that of the rabbit: i.e. a French rabbit will 
+# With version 2 of the API, it is now possible to specify a voice for the message. The
+# default is determined by the rabbit's language (claire22s for French; heather22k for
+# English). The voice's language overrides that of the rabbit: i.e. a French rabbit will
 # speak in English when told to use an English voice.
 #
-# The known voices are grouped by language in the Nabaztag::VOICES constant, but no attempt 
+# The known voices are grouped by language in the Nabaztag::VOICES constant, but no attempt
 # is made to validate against this list, as Violet may introduce additional voices in future.
 #
 class Nabaztag
-  
+
   class ServiceError < RuntimeError ; end
-  
-  SERVICE_ENCODING = 'iso-8859-1'
-  API_URI = 'http://www.nabaztag.com/vl/FR/api.jsp?'
-  
-  #
-  # The messages that indicate successful reception of various commands. Francophone rabbits reply in French; 
-  # anglophone ones reply in English
-  #
-  SUCCESS_RESPONSES = {
-    :say          => /Votre texte a bien été transmis|Your text was forwarded/u,
-    :left_ear     => /Votre changement d'oreilles gauche a été transmis|Your left change of ears was transmitted/u,
-    :right_ear    => /Votre changement d'oreilles droit a été transmis|Your right change of ears was transmitted/u,
-    :choreography => /Votre chorégraphie a bien été transmis|Your choreography was forwarded/u
-  }
-  EAR_POSITION_RESPONSES = {
-    :left  => /(?:Position gauche|Left position) = (-?\d+)/u,
-    :right => /(?:Position droite|Right position) = (-?\d+)/u
-  }
-  
+
   #
-  # The available voices for English and French according to the API. Note: although the French-language 
+  # The available voices for English and French according to the API. Note: although the French-language
   # documentation lists the voices with leading capitals (e.g. Graham22s), the API only seems to
   # recognise names all in lower case.
   #
@@ -69,33 +49,12 @@ class Nabaztag
     :fr => %w[julie22k claire22s],
     :en => %w[graham22s lucy22s heather22k ryan22k aaron22s laura22s]
   }
-  
-  class <<self
-  
-    #
-    # Override the default system encoding: use this if your program is not using UTF-8
-    #
-    def system_encoding=(encoding)
-      @system_encoding = encoding
-    end
-    
-    def system_encoding
-      return @system_encoding || 'utf-8'
-    end
-  
-    def encode_text(string)
-      Iconv.iconv(SERVICE_ENCODING, system_encoding, string)[0]
-    end
-  
-    def decode_response(string)
-      # Responses are only used for verification, so the encoding should match the present file.
-      Iconv.iconv('utf-8', SERVICE_ENCODING, string)[0]
-    end
-  
-  end
-  
+
+  attr_reader :mac, :token, :message
+  attr_accessor :voice
+
   #
-  # Create a new Nabaztag instance to communicate with the device with the given MAC address and 
+  # Create a new Nabaztag instance to communicate with the device with the given MAC address and
   # service token (see class overview for explanation of token).
   #
   def initialize(mac, token)
@@ -103,8 +62,6 @@ class Nabaztag
     @message = new_message
     @ear_positions = [nil, nil]
   end
-  attr_reader :mac, :token
-  attr_accessor :voice
   
   #
   # Send all pending messages
@@ -112,29 +69,30 @@ class Nabaztag
   def send
     response = @message.send
     @message = new_message
+    unless response.success?
+      raise ServiceError, response.raw
+    end
     return response
   end
-  attr_reader :message
-  
+
   #
   # Send a message immediately to get the ear positions.
   #
   def ear_positions
     ear_message = new_message
     ear_message.ears = 'ok'
-    ear_message.send
-    return ear_message.ear_positions
+    response = ear_message.send
+    return [response.left_ear, response.right_ear]
   end
-  
+
   #
   # Say text.
   #
   def say(text)
     message.tts = text
-    message.verifiers["Speech"] = lambda{ |response| response =~ SUCCESS_RESPONSES[:say] }
     nil
   end
-  
+
   #
   # Say text immediately.
   #
@@ -142,7 +100,7 @@ class Nabaztag
     say(text)
     send
   end
-  
+
   #
   # Make the rabbit bark.
   #
@@ -158,24 +116,18 @@ class Nabaztag
     bark
     send
   end
-  
+
   #
   # Set the position of the left and right ears between 0 and 16. Use nil to avoid moving an ear.
-  # Note that these positions are not given in degrees, and that it is not possible to specify the 
+  # Note that these positions are not given in degrees, and that it is not possible to specify the
   # direction of movement. For more precise ear control, use choreography instead.
   #
   def move_ears(left, right)
     message.posleft = left if left
     message.posright = right if right
-    if left
-      message.verifiers["Left ear"] = lambda{ |response| response =~ SUCCESS_RESPONSES[:left_ear] }
-    end
-    if right
-      message.verifiers["Right ear"] = lambda{ |response| response =~ SUCCESS_RESPONSES[:right_ear] }
-    end
-    return nil
+    nil
   end
-  
+
   #
   # Move ears immediately.
   #
@@ -183,28 +135,25 @@ class Nabaztag
     move_ears(left, right)
     send
   end
-    
+
   #
-  # Creates a new choreography message based on the actions instructed in the block. The commands 
+  # Creates a new choreography message based on the actions instructed in the block. The commands
   # are evaluated in the context of a new Choreography instance.
   #
   # E.g.
   #  nabaztag.choreography do
-  #    event { led :middle, :green ; led :left, :red }
+  #    together { led :middle, :green ; led :left, :red }
   #    led :right, :yellow
-  #    event { led :left, :off ; led :right, :off}
+  #    together { led :left, :off ; led :right, :off}
   #    ...
   #  end
   #
   def choreography(title=nil, &blk)
     message.chortitle = title
-    obj = Choreography.new
-    obj.instance_eval(&blk)
-    message.chor = obj.emit
-    message.verifiers["Choreography"] = lambda{ |response| response =~ SUCCESS_RESPONSES[:choreography] }
+    message.chor = Choreography.new(&blk).build
     nil
   end
-  
+
   #
   # Creates choreography and sends it immediately.
   #
@@ -212,173 +161,11 @@ class Nabaztag
     choreography(title, &blk)
     send
   end
-    
-  private
-  
+
+private
+
   def new_message
-    return Message.new(self)
+    return Message.new(mac, token)
   end
-  
-  #
-  # Choreography class uses class methods to implement a simple DSL. These build API choreography 
-  # messages based on instructions to move the ears and light the LEDs.
-  #
-  class Choreography
-    
-    LED_COLORS = {
-      :red          => [255,   0,   0],
-      :orange       => [255, 127,   0],
-      :yellow       => [255, 255,   0],
-      :green        => [  0, 255,   0],
-      :blue         => [  0,   0, 255],
-      :purple       => [255,   0, 255],
-      :dim_red      => [127,   0,   0],
-      :dim_orange   => [127,  63,   0],
-      :dim_yellow   => [127, 127,   0],
-      :dim_green    => [  0, 127,   0],
-      :dim_blue     => [  0,   0, 127],
-      :dim_purple   => [127,   0, 127],
-      :off          => [  0,   0,   0]
-    }
-    EARS = {:left => [1], :right => [0], :both => [0,1]}
-    LEDS = {:bottom => 0, :left => 1, :middle => 2, :right => 3, :top => 4}
-    EAR_DIRECTIONS = {:forward => 0, :backward => 1}
-    
-    def emit
-      @messages ||= []
-      return (['%d' % (@tempo || 10)] + (@messages || []) ).join(',')
-    end
-    
-    #
-    # Set the tempo of the choreography in Hz (i.e. events per secod). The default is 10
-    # events per second.
-    #
-    def tempo(t)
-      @tempo = t
-    end
-  
-    #
-    # Move :left, :right, or :both ears to angle degrees (0-180) in direction 
-    # :forward (default) or :backward.
-    #
-    def ear(which_ear, angle, direction=:forward)
-      direction_number = EAR_DIRECTIONS[direction]
-      EARS[which_ear].each do |ear_number|
-        append_message('motor', ear_number, angle, 0, direction)
-      end
-      skip 1
-    end
-  
-    #
-    # Change colour of an led (:top, :right:, middle, :left, :bottom) to a specified colour.
-    # The colour may be specified either as RGB values (0-255) or by using one of the named colours 
-    # in LED_COLORS.
-    #
-    # E.g. 
-    #  led :middle, :red
-    #  led :top, 0, 0, 255
-    #  led :bottom, :off
-    #
-    def led(which_led, c1, c2=nil, c3=nil)
-      led_number = LEDS[which_led]
-      if (c1 && c2 && c3)
-        red, green, blue = c1, c2, c3
-      else
-        red, green, blue = LED_COLORS[c1]
-      end
-      append_message('led', led_number, red, green, blue)
-      skip 1
-    end
-  
-    #
-    # Group several actions into a single chronological step via a block.
-    #
-    # E.g.
-    #  event { led :top, :yellow ; ear :both, 0 }
-    #
-    def event(&blk)
-      length(1, &blk)
-    end
-    
-    #
-    # Perform one or more actions for n chronological steps
-    #
-    # E.g.
-    #  length 3 do 
-    #    led :top, :red ; led :middle, :yellow
-    #  end
-    #
-    def length(duration, &blk)
-      old_in_event = @in_event
-      @in_event = true
-      yield
-      @in_event = old_in_event
-      skip duration
-    end
-    
-    private
-    
-    def append_message(*params)
-      fields = [@time_stamp || 0] + params
-      (@messages ||= []) << ("%d,%s,%d,%d,%d,%d" % fields)
-    end
 
-    def skip(duration=1)
-      @time_stamp ||= 0
-      @time_stamp += duration unless @in_event
-    end
-
-  end # Choreography
-  
-  class Message
-    
-    FIELDS = [:idmessage, :posright, :posleft, :idapp, :tts, :chor, :chortitle, :nabcast, :ears]
-    FIELDS.each do |field|
-      attr_accessor field
-    end
-    
-    def initialize(nabaztag)
-      @nabaztag = nabaztag
-      @verifiers = {}
-    end
-    attr_reader :verifiers, :ear_positions
-    
-    def send
-      parameters = FIELDS.inject({
-        :sn => @nabaztag.mac,
-        :token => @nabaztag.token,
-        :voice => @nabaztag.voice
-      }){ |hash, element|
-        value = __send__(element)
-        hash[element] = value if value
-        hash
-      }
-      request = build_request(parameters)
-      response = Nabaztag.decode_response(open(request).read).split(/\s{2,}/m).join("\n")
-      decode_ear_positions(response) if @ears
-      verifiers.each do |name, verifier|
-        unless verifier.call(response)
-          raise ServiceError, "#{name}: #{response}"
-        end
-      end
-      return true
-    end
-    
-    def decode_ear_positions(response)
-      left_ear = response[EAR_POSITION_RESPONSES[:left], 1]
-      right_ear = response[EAR_POSITION_RESPONSES[:right], 1]
-      @ear_positions = [left_ear.to_i, right_ear.to_i] if left_ear && right_ear
-    end
-    
-    private
-    
-    def build_request(parameters)
-      return API_URI << parameters.map{ |k,v| 
-        value = CGI.escape(Nabaztag.encode_text(v.to_s))
-        "#{k}=#{value}" 
-      }.join('&')
-    end
-    
-  end # Message
-  
-end # Nabaztag
+end

data/lib/nabaztag/choreography.rb

@@ -0,0 +1,119 @@
+class Nabaztag
+
+  #
+  # The Choreography class uses class methods to implement a simple DSL. These build API choreography
+  # messages based on instructions to move the ears and light the LEDs.
+  #
+  class Choreography
+
+    LED_COLORS = {
+      :red          => [255,   0,   0],
+      :orange       => [255, 127,   0],
+      :yellow       => [255, 255,   0],
+      :green        => [  0, 255,   0],
+      :blue         => [  0,   0, 255],
+      :purple       => [255,   0, 255],
+      :dim_red      => [127,   0,   0],
+      :dim_orange   => [127,  63,   0],
+      :dim_yellow   => [127, 127,   0],
+      :dim_green    => [  0, 127,   0],
+      :dim_blue     => [  0,   0, 127],
+      :dim_purple   => [127,   0, 127],
+      :off          => [  0,   0,   0]
+    }
+    EARS = {:left => [1], :right => [0], :both => [0,1]}
+    LEDS = {:bottom => 0, :left => 1, :middle => 2, :right => 3, :top => 4}
+    EAR_DIRECTIONS = {:forward => 0, :backward => 1}
+    
+    def initialize(&blk)
+      @messages = []
+      @tempo = 10
+      @time_stamp = 0
+      instance_eval(&blk) if block_given?
+    end
+
+    def build
+      return (['%d' % @tempo] + @messages).join(',')
+    end
+
+    #
+    # Set the tempo of the choreography in Hz (i.e. events per secod). The default is 10
+    # events per second.
+    #
+    def tempo(t)
+      @tempo = t
+    end
+
+    #
+    # Move :left, :right, or :both ears to angle degrees (0-180) in direction
+    # :forward (default) or :backward.
+    #
+    def ear(which_ear, angle, direction=:forward)
+      direction_number = EAR_DIRECTIONS[direction]
+      EARS[which_ear].each do |ear_number|
+        append_message('motor', ear_number, angle, 0, direction_number)
+      end
+      advance
+    end
+
+    #
+    # Change colour of an led (:top, :right:, middle, :left, :bottom) to a specified colour.
+    # The colour may be specified either as RGB values (0-255) or by using one of the named colours
+    # in LED_COLORS.
+    #
+    # E.g.
+    #  led :middle, :red
+    #  led :top, 0, 0, 255
+    #  led :bottom, :off
+    #
+    def led(which_led, c1, c2=nil, c3=nil)
+      led_number = LEDS[which_led]
+      if (c1 && c2 && c3)
+        red, green, blue = c1, c2, c3
+      else
+        red, green, blue = LED_COLORS[c1]
+      end
+      append_message('led', led_number, red, green, blue)
+      advance
+    end
+
+    #
+    # Group several actions into a single chronological step via a block.
+    #
+    # E.g.
+    #  event { led :top, :yellow ; ear :both, 0 }
+    #
+    def event(duration=1, &blk)
+      length(duration, &blk)
+    end
+    
+    alias_method :together, :event
+
+    #
+    # Perform one or more actions for n chronological steps
+    #
+    # E.g.
+    #  length 3 do
+    #    led :top, :red ; led :middle, :yellow
+    #  end
+    #
+    def length(duration, &blk)
+      old_in_event = @in_event
+      @in_event = true
+      yield
+      @in_event = old_in_event
+      advance duration
+    end
+
+  private
+
+    def append_message(*params)
+      @messages << ("%d,%s,%d,%d,%d,%d" % ([@time_stamp] + params))
+    end
+
+    def advance(duration=1)
+      @time_stamp += duration unless @in_event
+    end
+
+  end
+end

data/lib/nabaztag/message.rb

@@ -0,0 +1,58 @@
+require 'cgi'
+require 'iconv'
+require 'open-uri'
+require 'nabaztag/response'
+
+class Nabaztag
+  class Message
+
+    SERVICE_ENCODING = 'iso-8859-1'
+    API_URI = 'http://api.nabaztag.com/vl/FR/api.jsp?'
+    FIELDS = [
+      :idmessage, :posright, :posleft, :idapp, :tts, :chor, :chortitle, :ears, :nabcast, 
+      :ttlive, :voice, :speed, :pitch
+    ]
+
+    FIELDS.each do |field|
+      attr_accessor field
+    end
+
+    def initialize(mac, token)
+      @mac, @token = mac, token
+      @expected_identifiers = []
+    end
+    
+    def send
+      Response.new(open(request_uri){ |io| io.read })
+    end
+    
+    def expect(identifier)
+      @expected_identifiers << identifier
+    end
+
+  private
+
+    def request_uri
+      API_URI + parameters.sort_by{ |k,v| k.to_s }.map{ |k,v|
+        value = CGI.escape(encode_text(v.to_s))
+        "#{k}=#{value}"
+      }.join('&')
+    end
+    
+    def parameters
+      FIELDS.inject({
+        :sn => @mac,
+        :token => @token
+      }){ |hash, element|
+        value = __send__(element)
+        hash[element] = value if value
+        hash
+      }
+    end
+
+    def encode_text(string)
+      Iconv.iconv(SERVICE_ENCODING, 'utf-8', string)[0]
+    end
+
+  end
+end

data/lib/nabaztag/response.rb

@@ -0,0 +1,55 @@
+require 'rexml/document'
+
+class Nabaztag
+  class Response
+    include REXML
+    
+    ERROR_MESSAGES = %w[
+      NOGOODTOKENORSERIAL
+      NOTAVAILABLE
+    ]
+    SUCCESS_MESSAGES = %w[
+      TTSEND
+      EARPOSITIONSEND
+      POSITIONEAR
+      MESSAGESEND
+    ]
+    # As at 2007-03-07, choreography and nabcast always return NOTAVAILABLE
+
+    attr_reader :raw
+    
+    def initialize(xml)
+      @raw = xml
+      @doc = Document.new(xml)
+    end
+    
+    def messages
+      lookup('/rsp/message')
+    end
+    
+    def comments
+      lookup('/rsp/comment')
+    end
+    
+    def left_ear
+      position = lookup('/rsp/leftposition').first
+      position && position.to_i
+    end
+
+    def right_ear
+      position = lookup('/rsp/rightposition').first
+      position && position.to_i
+    end
+    
+    def success?
+      (messages & ERROR_MESSAGES).empty?
+    end
+    
+  private
+  
+    def lookup(xpath)
+      XPath.match(@doc, xpath).map{ |n| n.text }
+    end
+    
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0
+rubygems_version: 0.9.1
 specification_version: 1
 name: Nabaztag
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
-date: 2006-08-02 00:00:00 +01:00
+  version: 0.3.0
+date: 2007-04-25 00:00:00 +01:00
 summary: Nabaztag communication library for Ruby.
 require_paths: 
-  - lib
+- lib
 email: paulbattley@reevoo.com
 homepage: 
 rubyforge_project: 
@@ -18,28 +18,35 @@ bindir: bin
 has_rdoc: true
 required_ruby_version: !ruby/object:Gem::Version::Requirement 
   requirements: 
-    - 
-      - ">"
-      - !ruby/object:Gem::Version 
-        version: 0.0.0
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
   version: 
 platform: ruby
 signing_key: 
 cert_chain: 
 post_install_message: 
 authors: 
-  - Paul Battley
+- Paul Battley
 files: 
-  - lib/nabaztag.rb
-  - README
-  - CHANGES
+- lib/nabaztag.rb
+- lib/nabaztag/choreography.rb
+- lib/nabaztag/message.rb
+- lib/nabaztag/response.rb
+- README
+- CHANGES
 test_files: []
+
 rdoc_options: []
+
 extra_rdoc_files: 
-  - README
-  - CHANGES
+- README
+- CHANGES
 executables: 
-  - nabaztag-say
+- nabaztag-say
 extensions: []
+
 requirements: []
-dependencies: []
+
+dependencies: []
+