Permalink
Browse files

Add documentation (or at least start to)

  • Loading branch information...
sprsquish committed Nov 27, 2008
1 parent fa9a9dd commit d052d21ced2902b2ed120f73d8095e7412f6dc3f
View
@@ -1,3 +1,4 @@
pkg
Manifest
doc
+coverage
View
@@ -1,3 +1,78 @@
= Blather
An evented XMPP library
+
+== Features
+
+* evented architecture
+* uses libxml
+* simplified starting point
+
+== Project Pages
+
+GitHub:: https://github.com/sprsquish/blather
+
+RubyForge:: http://rubyforge.org/projects/squishtech/
+
+Lighthouse:: http://squishtech.lighthouseapp.com/projects/20652-blather
+
+== Author
+
+Jeff Smick <sprsquish@gmail.com>
+
+= Usage
+
+== Installation
+
+ sudo gem install blather
+
+== Example
+
+See the /examples directory for more advanced examples.
+
+This will auto-accept any subscription requests and echo back any messages or presence notifications.
+
+ require 'lib/blather/client'
+
+ class Echo < Blather::Client
+ # Auto-approve subscription requests
+ def receive_subscription(s)
+ send_data(s.approve!) and true if s.request?
+ end
+
+ # Echo presence
+ def receive_status(status)
+ set_status(status.state, status.message, status.from) if roster[status.from]
+ end
+
+ # Echo message
+ def receive_message(message)
+ send_data(message.reply) if message.type == :chat
+ end
+ end
+
+ Blather.run 'echo@jabber.local', 'echo', Echo.new
+
+
+= License
+
+Copyright (c) 2008 Jeff Smick
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
View
@@ -1,11 +1,16 @@
require 'echoe'
require 'lib/blather'
+require 'hanna/rdoctask'
Echoe.new('blather') do |p|
- p.version = Blather.version
- p.project = 'squishtech'
p.author = 'Jeff Smick'
+ p.email = 'sprsquish@gmail.com'
+
+ p.project = 'squishtech'
+ p.version = Blather::VERSION
p.summary = 'An evented XMPP library written on EventMachine and libxml-ruby'
- p.runtime_dependencies = %w[eventmachine libxml]
- p.retain_gemspec = true
+
+ p.runtime_dependencies = ['eventmachine', 'libxml >=1.0.11']
+ p.rdoc_options += %w[-S -T hanna --main README.rdoc --exclude autotest]
+ p.test_pattern = 'spec/**/*_spec.rb'
end
View
@@ -36,19 +36,11 @@
XML::Parser.indent_tree_output = false
module Blather
+ VERSION = '0.1'
LOG = Logger.new STDOUT
def run(jid, password, client, host = nil, port = 5222)
EM.run { Stream.start client, JID.new(jid), password, host, port }
end
module_function :run
-
- MAJOR = 0
- MINOR = 1
- VERSION = [MAJOR, MINOR]*'.'
-
- def version
- VERSION
- end
- module_function :version
end
@@ -19,6 +19,6 @@ def to_s
end
# Stanza errors
- class StanzaError < StandardError; end
+ class StanzaError < BlatherError; end
class ArgumentError < StanzaError; end
end
View
@@ -1,13 +1,7 @@
-# =XMPP4R - XMPP Library for Ruby
-# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
-# Website::http://home.gna.org/xmpp4r/
-
module Blather
+
##
- # The JID class represents a Jabber Identifier as described by
- # RFC3920 section 3.1.
- #
- # Note that you can use JIDs also for Sorting, Hash keys, ...
+ # This is a simple modification of the JID class from XMPP4R
class JID
include Comparable
@@ -70,7 +64,7 @@ def to_s
s = @domain
s = "#{@node}@#{s}" if @node
s = "#{s}/#{@resource}" if @resource
- return s
+ s
end
##
@@ -97,9 +91,11 @@ def <=>(o)
to_s <=> o.to_s
end
- # Test id jid is strepped
+ ##
+ # Test if JID is stripped
def stripped?
@resource.nil?
end
end
+
end
View
@@ -1,5 +1,8 @@
module Blather
+ ##
+ # Local Roster
+ # Takes care of adding/removing JIDs through the stream
class Roster
include Enumerable
@@ -9,6 +12,9 @@ def initialize(stream, stanza = nil)
stanza.items.each { |i| push i, false } if stanza
end
+ ##
+ # Process any incoming stanzas adn either add or remove the
+ # corresponding RosterItem
def process(stanza)
stanza.items.each do |i|
case i.subscription
@@ -18,11 +24,18 @@ def process(stanza)
end
end
+ ##
+ # Pushes a JID into the roster
+ # then returns self to allow for chaining
def <<(elem)
push elem
self
end
+ ##
+ # Push a JID into the roster
+ # Will send the new item to the server
+ # unless overridden by calling #push(elem, false)
def push(elem, send = true)
jid = elem.respond_to?(:jid) ? elem.jid : JID.new(elem)
@items[key(jid)] = node = RosterItem.new(elem)
@@ -31,20 +44,29 @@ def push(elem, send = true)
end
alias_method :add, :push
+ ##
+ # Remove a JID from the roster
+ # Sends a remove query stanza to the server
def delete(jid)
@items.delete key(jid)
@stream.send_data Stanza::Iq::Roster.new(:set, Stanza::Iq::Roster::RosterItem.new(jid, nil, :remove))
end
alias_method :remove, :delete
+ ##
+ # Get a RosterItem by JID
def [](jid)
items[key(jid)]
end
+ ##
+ # Iterate over all RosterItems
def each(&block)
items.each &block
end
+ ##
+ # Returns a duplicate of all RosterItems
def items
@items.dup
end
@@ -1,19 +1,29 @@
module Blather
+ ##
+ # RosterItems hold internal representations of the user's roster
+ # including each JID's status.
class RosterItem
+ VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to]
+
attr_reader :jid,
:ask,
:statuses
attr_accessor :name,
:groups
+ ##
+ # item:: can be a JID, String (a@b) or a Stanza
def initialize(item)
@statuses = []
- if item.is_a?(JID)
+ case item
+ when JID
self.jid = item.stripped
- elsif item.is_a?(XMPPNode)
+ when String
+ self.jid = JID.new(item).stripped
+ when XMPPNode
self.jid = JID.new(item['jid']).stripped
self.name = item['name']
self.subscription = item['subscription']
@@ -22,36 +32,54 @@ def initialize(item)
end
end
+ ##
+ # Set the jid
def jid=(jid)
@jid = JID.new(jid).stripped
end
- VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to].freeze
+ ##
+ # Set the subscription
+ # Ensures it is one of VALID_SUBSCRIPTION_TYPES
def subscription=(sub)
raise ArgumentError, "Invalid Type (#{sub}), use: #{VALID_SUBSCRIPTION_TYPES*' '}" if
sub && !VALID_SUBSCRIPTION_TYPES.include?(sub = sub.to_sym)
@subscription = sub ? sub : :none
end
+ ##
+ # Get the current subscription
+ # returns:: :both, :from, :none, :remove, :to or :none
def subscription
@subscription || :none
end
+ ##
+ # Set the ask value
+ # ask:: must only be nil or :subscribe
def ask=(ask)
- raise ArgumentError, "Invalid Type (#{ask}), use: #{VALID_SUBSCRIPTION_TYPES*' '}" if ask && (ask = ask.to_sym) != :subscribe
+ raise ArgumentError, "Invalid Type (#{ask}), can only be :subscribe" if ask && (ask = ask.to_sym) != :subscribe
@ask = ask ? ask : nil
end
+ ##
+ # Set the status then sorts them according to priority
+ # presence:: Status
def status=(presence)
@statuses.delete_if { |s| s.from == presence.from }
@statuses << presence
@statuses.sort!
end
+ ##
+ # Return the status with the highest priority
+ # if resource is set find the status of that specific resource
def status(resource = nil)
top = resource ? @statuses.detect { |s| s.from.resource == resource } : @statuses.first
end
+ ##
+ # Translate the RosterItem into a proper stanza that can be sent over the stream
def to_stanza(type = nil)
r = Stanza::Iq::Roster.new type
n = Stanza::Iq::Roster::RosterItem.new jid, name, subscription, ask
Oops, something went wrong.

0 comments on commit d052d21

Please sign in to comment.