Salut 0.3.1 → 0.4.0

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Mark Rada
+Copyright (c) 2010-2011 Mark Rada
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -3,6 +3,12 @@ Salut
 
 Salut is just a little bit of example code of using Bonjour with MacRuby.
 
+If all you want to do is log that callbacks were called back, or just add
+very little to a callback, then this code will work well for you. But Apple
+has already done a very good job of distilling Bonjour to the point that
+even without this gem you would not have to add much code in order to use
+Bonjour.
+
 Of course, this is not a substitute for reading the [Bonjour Overview](http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/NetServices/Introduction.html%23//apple_ref/doc/uid/TP40002445-SW1) and related documentation (not even close).
 
 Reference Documentation
@@ -22,27 +28,28 @@ Example Usage
 
 Advertising a hypothetical service:
 
-            service = Salut::Service.new({
-              service_type:'_http._tcp.',
-              instance_name:`hostname s`.chomp,
-              port:3000
-            })
+            service = Salut::Service.new(
+               service_type:'_http._tcp.',
+              instance_name:'SalutDemo',
+                       port:3000
+            )
             service.start_advertising
 
 Finding the service using the browser:
 
             browser = Salut::Browser.new
-            # look at the delegate methods to find out what variables are given to the proc
-            browser.delegates[:'netServiceBrowser:didFindService:moreComing:'] = Proc.new {
+            # the NSNetServiceBrowserDelegate lists all the possible delegates
+            # or look at the 'Delegate methods' group in lib/Salut/Browser.rb
+            browser.delegate :"netServiceBrowser:didFindService:moreComing:" do
                 |sender, service, more|
-                service.resolve # because we want to resolve them all!
+                service.resolve # if you want to resolve all services found
                 if more
                    NSLog('Not up to date yet')
                 else
                    NSLog('All caught up')
                 end
-            }
-            browser.find_services '_http._tcp.', in_domain:''
+            end
+            browser.find_services '_http._tcp.'
 
 If you want to stop advertising:
 
@@ -58,12 +65,11 @@ a GUI app, but a command line app will have to force the loop to run.
 You can only use a Service or Browser for one thing at a time, and the API is designed
 with that assumption in mind.
 
-TODO
-====
+TODO for 1.0
+==========
 
 - Monitoring and TXT record stuff
 - publishWithOptions default argument
-- Do not pass NSNetService or NSNetServiceBrowser to callbacks
 
 Contributing to Salut
 =====================
@@ -79,6 +85,6 @@ Contributing to Salut
 Copyright
 =========
 
-Copyright (c) 2010 Mark Rada. See LICENSE.txt for
+Copyright (c) 2010-2011 Mark Rada. See LICENSE.txt for
 further details.
 

data/lib/Salut/Browser.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+require 'Salut/Service'
 
 module Salut
 
@@ -21,9 +21,12 @@ module Salut
     # @return [Array<String>]
     attr_reader :domains
 
-    # @return [Array<NSNetService>]
+    # @return [Array<Salut::Service>]
     attr_reader :services
 
+    # @return [NSNetServiceBrowser]
+    attr_reader :browser
+
     # Ensure that some instance variables are initialized
     def initialize
       @browser          = NSNetServiceBrowser.alloc.init
@@ -42,26 +45,17 @@ module Salut
 
     # @group Adding callback extensions
 
-    # @return [Hash{Symbol=>Proc}]
-    attr_accessor :delegates
-
-    # A shortcut for reading from the delegate methods
-    # @param [Symbol] key
-    # @return [Proc]
-    def [] key
-      @delegates[key]
-    end
-
-    # A shortcut for writing to the delegate methods hash
-    # @param [Symbol] key
-    # @param [Proc] value
+    # A shortcut for reading/writing to the delegate methods hash
+    # @param [Symbol] method the name of the callback
     # @return [Proc]
-    def []= key, value
-      @delegates[key] = value
+    def delegate method
+      if block_given?
+        @delegates[method] = Proc.new
+      else
+        @delegates[method]
+      end
     end
 
-    # @endgroup
-
 
     # @group Finding domains
 
@@ -72,99 +66,86 @@ module Salut
 
     alias_method :stop_finding_domains, :stop_finding
 
-    # @endgroup
-
 
     # @group Finding services
 
     # @todo find a way to use default arguments
     # @param [String] service_name
     # @param [String] domain_name
-    def find_services service_type, in_domain:domain_name
+    def find_services service_type, domain_name = ''
       @browser.searchForServicesOfType service_type, inDomain:domain_name
     end
 
     alias_method :stop_finding_services, :stop_finding
 
-    # @endgroup
-
 
     # @group Delegate methods
 
-    # @yieldparam [NSNetServiceBrowser] sender
+    # @yieldparam [Salut::Browser] sender
     # @yieldparam [String] domain_name
     # @yieldparam [Boolean] more
-    # @return [nil]
     def netServiceBrowser sender, didFindDomain:domain_name, moreComing:more
       @domains << domain_name
-      @delegates[__method__].call sender, domain_name, more if @delegates[__method__]
+      @delegates[__method__].call self, domain_name, more if @delegates[__method__]
       Salut.log.info "Found domain: #{domain_name}"
     end
 
-    # @yieldparam [NSNetServiceBrowser] sender
+    # @yieldparam [Salut::Browser] sender
     # @yieldparam [String] domain_name
     # @yieldparam [Boolean] more
-    # @return [nil]
     def netServiceBrowser sender, didRemoveDomain:domain_name, moreComing:more
       @domains.delete domain_name
-      @delegates[__method__].call sender, domain_name, more if @delegates[__method__]
+      @delegates[__method__].call self, domain_name, more if @delegates[__method__]
       Salut.log.info "Removing domain: #{domain_name}"
     end
 
-    # @yieldparam [NSNetServiceBrowser] sender
+    # @yieldparam [Salut::Browser] sender
     # @yieldparam [Salut::Service] service
     # @yieldparam [Boolean] more
-    # @return [nil]
     def netServiceBrowser sender, didFindService:service, moreComing:more
-      salut_service = Service.new({ service:service })
+      salut_service = Service.new service:service
       @services << salut_service
-      @delegates[__method__].call sender, salut_service, more if @delegates[__method__]
+      @delegates[__method__].call self, salut_service, more if @delegates[__method__]
       Salut.log.info "Found service (#{service.description})"
     end
 
-    # @yieldparam [NSNetServiceBrowser] sender
+    # @yieldparam [Salut::Browser] sender
     # @yieldparam [Salut::Service] removed_service
     # @yieldparam [Boolean] more
-    # @return [nil]
     def netServiceBrowser sender, didRemoveService:service, moreComing:more
-      removed_service
+      removed_service = nil
       @services.delete_if { |salut_service|
         if salut_service.service == service
           removed_service = salut_service
           true
         end
       }
-      @delegates[__method__].call sender, removed_service, more if @delegates[__method__]
+      @delegates[__method__].call self, removed_service, more if @delegates[__method__]
       Salut.log.info "Removing service (#{service.description})"
     end
 
-    # @yieldparam [NSNetServiceBrowser] sender
-    # @return [nil]
+    # @yieldparam [Salut::Browser] sender
     def netServiceBrowserWillSearch sender
       @searching = true
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Starting search (#{sender.description})"
     end
 
-    # @yieldparam [NSNetServiceBrowser] sender
+    # @yieldparam [Salut::Browser] sender
     # @yieldparam [Hash] error_dict
-    # @return [nil]
     def netServiceBrowser sender, didNotSearch:error_dict
       @searching = false
-      @delegates[__method__].call sender, error_dict if @delegates[__method__]
+      @delegates[__method__].call self, error_dict if @delegates[__method__]
       Salut.log.info "Failed to search (#{sender.description})\n\t problem was\n#{error_dict.description}"
     end
 
-    # @yieldparam [NSNetServiceBrowser] sender
-    # @return [nil]
+    # @yieldparam [Salut::Browser] sender
     def netServiceBrowserDidStopSearch sender
       @searching = false
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Done searching (#{sender.description})"
     end
 
-    # @endgroup
-
   end
 
 end

data/lib/Salut/Service.rb

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 module Salut
 
   # Advertises its service on the local network using Bonjour or is
@@ -53,26 +51,17 @@ module Salut
 
     # @group Adding callback extensions
 
-    # @return [Hash{Symbol=>Proc}]
-    attr_accessor :delegates
-
-    # A shortcut for reading from the delegate methods
-    # @param [Symbol] key
-    # @return [Proc]
-    def [] key
-      @delegates[key]
-    end
-
-    # A shortcut for writing to the delegate methods hash
-    # @param [Symbol] key
-    # @param [Proc] value
+    # A shortcut for reading/writing from the delegate methods
+    # @param [Symbol] method
     # @return [Proc]
-    def []= key, value
-      @delegates[key] = value
+    def delegate method
+      if block_given?
+        @delegates[method] = Proc.new
+      else
+        @delegates[method]
+      end
     end
 
-    # @endgroup
-
 
     # @group Advertising a service
 
@@ -102,8 +91,6 @@ module Salut
       @service = nil
     end
 
-    # @endgroup
-
 
     # @group Working with discovered services
 
@@ -114,76 +101,64 @@ module Salut
       @service.resolveWithTimeout timeout
     end
 
-    # @endgroup
-
 
     # @group Delegate methods
 
-    # @yieldparam [NSNetService] sender
-    # @return [nil]
+    # @yieldparam [Salut::Service] sender a reference to self
     def netServiceWillPublish sender
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Starting to advertise service (#{sender.description})"
     end
 
-    # @yieldparam [NSNetService] sender
+    # @yieldparam [Salut::Service] sender a reference to self
     # @yieldparam [Hash] error_dict
-    # @return [nil]
     def netService sender, didNotPublish:error_dict
       @advertising = false
-      @delegates[__method__].call sender, error_dict if @delegates[__method__]
+      @delegates[__method__].call self, error_dict if @delegates[__method__]
       Salut.log.info "ERROR: could not advertise service (#{sender.description})\n\t the problem was\n#{error_dict.description}"
     end
 
-    # @yieldparam [NSNetService] sender
-    # @return [nil]
+    # @yieldparam [Salut::Service] sender a reference to self
     def netServiceDidPublish sender
       @advertising = true
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Successfully advertising service (#{sender.description})"
     end
 
-    # @yieldparam [NSNetService] sender
-    # @return [nil]
+    # @yieldparam [Salut::Service] sender a reference to self
     def netServiceWillResolve sender
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Resolving service (#{sender.description})"
     end
 
-    # @yieldparam [NSNetService] sender
+    # @yieldparam [Salut::Service] sender a reference to self
     # @yieldparam [Hash] error_dict
-    # @return [nil]
     def netService sender, didNotResolve:error_dict
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self, error_dict if @delegates[__method__]
       Salut.log.info "ERROR: could not resolve service (#{sender.description})\n\t the problem was\n#{error_dict.description}"
     end
 
-    # @yieldparam [NSNetService] sender
-    # @return [nil]
+    # @yieldparam [Salut::Service] sender a reference to self
     def netServiceDidResolveAddress sender
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Resolved address for service (#{sender.description})"
     end
 
     # @todo should I process the TXT record before giving it to the proc?
-    # @yieldparam [NSNetService] sender
+    # @yieldparam [Salut::Service] sender a reference to self
     # @yieldparam [NSData] data the new TXT record
-    # @return [nil]
     def netService sender, didUpdateTXTRecordData:data
-      @delegates[__method__].call sender, data if @delegates[__method__]
+      @delegates[__method__].call self, data if @delegates[__method__]
       Salut.log.info "Updated TXT record for service (#{sender.description})"
     end
 
-    # @yieldparam [NSNetService] sender
-    # @return [nil]
+    # @yieldparam [Salut::Service] sender a reference to self
     def netServiceDidStop sender
       @advertising = false
-      @delegates[__method__].call sender if @delegates[__method__]
+      @delegates[__method__].call self if @delegates[__method__]
       Salut.log.info "Stopped advertising/resolving service (#{sender.description})"
     end
 
-    # @endgroup
-
   end
 
 end

data/spec/Browser_spec.rb

@@ -1,2 +1,136 @@
 require './spec_helper'
 
+describe Salut::Browser do
+  before do
+    Salut.log.level = Logger::WARN
+    @browser = Salut::Browser.new
+  end
+
+  describe '#searching?' do
+    it 'should be initialized to false' do
+      @browser.searching?.should.be.equal false
+    end
+
+    it 'should be false after I stop searching' do
+      @browser.find_services '_ssh._tcp.'
+      run_run_loop 1
+      @browser.searching?.should.be.equal true
+
+      @browser.stop_finding_services
+      run_run_loop 1
+      @browser.searching?.should.be.equal false
+
+      @browser.find_browsable_domains
+      run_run_loop 1
+      @browser.searching?.should.be.equal true
+
+      @browser.stop_finding_domains
+      run_run_loop 1
+      @browser.searching?.should.be.equal false
+    end
+
+    # I don't know how to cause a failure when searching
+    # for browsable domains
+    it 'should be false if searching fails' do
+      @browser.find_services 'badname'
+      run_run_loop
+      @browser.searching?.should.be.equal false
+    end
+
+    it 'should be true when searching starts' do
+      @browser.find_services '_ssh._tcp.'
+      @browser.searching?.should.be.equal true
+
+      @browser.stop_finding_services
+      run_run_loop 1
+      @browser.searching?.should.be.equal false
+
+      @browser.find_browsable_domains
+      @browser.searching?.should.be.equal true
+    end
+  end
+
+
+  describe '#domains' do
+    it 'should be initialized to an empty array' do
+      @browser.domains.class.should.be.equal Array
+      @browser.domains.should.be.equal []
+    end
+
+    # here I assume that local. will always be found
+    it 'should be populated with domains when I browse for domains' do
+      @browser.domains.size.should.be.equal 0
+      @browser.find_browsable_domains
+      run_run_loop
+      @browser.domains.size.should.not.be.equal 0
+    end
+
+    # @todo not sure how to fake this one
+    it 'should shrink when domains disappear'
+  end
+
+
+  describe '#services' do
+    before do
+      @service = Salut::Service.new(
+        service_type:'_test._tcp.',
+        instance_name:'TEST',
+        port:9000
+      )
+      @service.start_advertising
+      run_run_loop
+    end
+
+    it 'should be initialized to an empty array' do
+      @browser.services.class.should.be.equal Array
+      @browser.services.should.be.equal []
+    end
+
+    it 'should populate when I call #find_services' do
+      @browser.services.size.should.be.equal 0
+      @browser.find_services '_test._tcp.'
+      run_run_loop
+      @browser.services.size.should.not.be.equal 0
+    end
+
+    it 'should dispopulate if services go away after being discovered by calling #find_services' do
+      @browser.services.size.should.be.equal 0
+      @browser.find_services '_test._tcp.'
+      run_run_loop
+      @browser.services.size.should.be.equal 1
+      @service.stop_advertising
+      run_run_loop
+      @browser.services.size.should.be.equal 0
+    end
+  end
+
+
+  describe '#browser' do
+    it 'should be the underlying NSNetServiceBrowser' do
+      @browser.browser.class.should.be.equal NSNetServiceBrowser
+    end
+
+    it 'should be set at initialization' do
+      @browser.browser.should.not.be.equal nil
+    end
+  end
+
+
+  describe '#initialize' do
+    it 'should initialize browser with an NSNetServiceBrowser' do
+      @browser.browser.should.not.be.equal nil
+    end
+
+    it 'should initialize #domains to an empty array' do
+      @browser.domains.should.be.equal []
+    end
+
+    it 'should initialize #services to an empty array' do
+      @browser.services.should.be.equal []
+    end
+
+    it 'should initialize #searching? to false' do
+      @browser.searching?.should.be.equal false
+    end
+  end
+end