gossip 0.3.0

data/lib/gossip/multi-exceptions.rb

@@ -0,0 +1,47 @@
+#! /opt/local/bin/ruby
+#
+#  Created by Brian Marick on 2007-09-15.
+#  Copyright (c) 2007. All rights reserved.
+
+
+
+require 'thread'
+
+class Queue # :nodoc:
+  def to_a
+    result = []
+    until empty?
+      result << self.pop
+    end
+    result
+  end
+end
+
+module Gossip
+  # This collects exceptions from several threads and packages them up 
+  # into a single exception.
+  class MultiException < StandardError
+
+    attr_reader :traces
+    
+    def initialize(exceptions)
+      messages = exceptions.collect { | ex | "#{ex.to_s} (#{ex.class})" }
+      super(messages.join("\n"))
+      @traces = exceptions.collect { | ex | ex.backtrace }
+    end
+
+    def self.reraise_with_combined_backtrace
+      yield
+    rescue MultiException => ex
+      ex.traces.each_with_index { | trace, index | 
+        trace.unshift("Trace number #{index}:\n")
+      }
+      ex.set_backtrace(ex.traces.flatten)
+      raise
+    end
+      
+    
+  end
+  
+end
+  

data/lib/gossip/preteen.rb

@@ -0,0 +1,86 @@
+#! /opt/local/bin/ruby
+#
+#  Created by Brian Marick on 2007-09-15.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'gossip/multi-exceptions'
+require 'gossip/crony'
+
+module Gossip
+
+  # A Preteen is someone who tells her Best Friends Forever some gossip. 
+  # Each BFF is a Crony, but some Cronies can be out of favor during a 
+  # particular invocation of a script. A Crony who's out of favor is not 
+  # told the gossip.
+  class Preteen
+    include Gossip
+
+    attr_reader :cronies
+    
+    # The second and third arguments are symbols that name Crony subclasses. 
+    # (See Crony#symbol.) The first
+    # set will hear gossip; the second will not. The _cronymaker_ is a hash. 
+    # It is indexed by crony symbol. The values are blocks that first load
+    # the Crony subclass's source, then return a new crony of that class. 
+    def initialize(cronymaker = {}, bff =[], on_the_outs_forever_and_ever_until_tomorrow=[])
+      @cronies = []
+      (bff+on_the_outs_forever_and_ever_until_tomorrow).each do | name |
+        user_claims(cronymaker.has_key?(name)) {
+          "#{name.inspect} is not a known crony."
+        }
+        crony = cronymaker[name].call
+        crony.is_bff_by_default = bff.include?(name)
+        accept(crony)
+      end
+    end
+
+    def accept(*cronies) # :nodoc: 
+      @cronies += cronies
+    end
+
+    # Tell Crony objects who are in favor (best friends forever) a _scandal_
+    # and its _details_. The _scandal_ should be short - think an email
+    # Subject line.
+    def tell_bffs(scandal, details)
+      simultaneously do | crony | 
+        crony.hear(scandal, details) if crony.is_bff?
+      end
+    end
+    
+    
+    
+    private 
+
+    def annotate(exception, crony)
+      # Note: cannot raise exception.class because on Windows the 
+      # exception message for Net errors will contain duplicate errors.
+      # This is annoying because with_pleasant_exceptions appends the
+      # exception class. So we have to append it ourselves.
+      annotated = StandardError.new("Complaint from #{crony.name}: #{exception.to_s} (#{exception.class})")
+      annotated.set_backtrace(exception.backtrace)
+      annotated
+    end
+
+
+    def simultaneously # execute block in thread
+      Thread.abort_on_exception = false
+      queue = Queue.new
+      threads = @cronies.collect do | crony |
+        Thread.new(crony) do | crony |
+          begin
+            yield(crony)
+          rescue Exception => ex
+            queue << annotate(ex, crony)
+          end
+        end
+      end
+      threads.each { | thread | thread.join }
+      # This peculiarness is the way to set the exception's
+      # backtrace with the combination of the backtraces of
+      # all saved exceptions (if any)
+      MultiException.reraise_with_combined_backtrace { 
+        raise MultiException.new(queue.to_a) if queue.length > 0
+      }
+    end
+  end               
+end

data/lib/gossip/site-config.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-09-23.
+#  Copyright (c) 2007. All rights reserved.
+
+# Suppose you want to use many of these example programs. Chances are, you 
+# want each one to use the same site-wide defaults. Change this config file,
+# put it somewhere, and change the examples you use to load it. 
+
+# CHANGE: These arrays describe the destinations for gossip messages. 
+# Unless defaults are overridden, output will go only to the BFFS
+# The difference between ON_THE_OUTS and TOTAL_OUTSIDERS is that the 
+# user can override ON_THE_OUTS. For example, the -j command-line
+# option will cause messages to be sent to Jabber. A TOTAL_OUTSIDER
+# can never be sent a message. This is useful because, for example, 
+# you don't even need to have the twitter gem on your system when 
+# :twitter is a TOTAL_OUTSIDER.
+
+BFFS = [:standard_output] # By default, gossip with these 
+ON_THE_OUTS = [:mail, :jabber, :campfire, :twitter, :trac]  # By default, do not gossip with these. 
+TOTAL_OUTSIDERS = [] # These will never ever gossiped with.
+
+
+# CHANGE: The following sets those values the program will use unless the 
+# invoker overrides them on either (or both) the command line or YAML
+# configuration file. If you do not intend to use one of the destinations
+# (twitter, say), you can just ignore the values. 
+
+when_not_TOTALLY_out_of_the_social_scene :jabber do 
+  require 'gossip/cronies/jabber'
+  JabberCrony.new(:default_to => ['listener@example.com', 'other@example.com'],
+                  :default_account => 'watchdog@example.com',
+                  :default_password => 'jabber password')
+end
+
+when_not_TOTALLY_out_of_the_social_scene :mail do
+  require 'gossip/cronies/smtp'
+  SmtpCrony.new(:default_to => ['listener@example.com', 'other@example.com'],
+                :default_from => 'watchdog@example.com',
+                :default_from_domain => 'localhost',
+                :default_smtp_server => 'example.com',
+                :default_smtp_port => 25,
+                :default_smtp_account => 'watchdog',
+                :default_smtp_password => 'mail password',
+                :default_smtp_authentication => 'login')
+end
+
+when_not_TOTALLY_out_of_the_social_scene :campfire do 
+  require 'gossip/cronies/campfire'
+  CampfireCrony.new(:default_login => 'watchdog@example.com',
+                    :default_password => 'campfire password',
+                    :default_subdomain => 'project',
+                    :default_room => 'activity')
+end
+
+when_not_TOTALLY_out_of_the_social_scene :trac do 
+  require 'gossip/cronies/trac'
+  TracCrony.new(:default_trac_admin_path => '/usr/local/bin/trac-admin',
+                  :default_environment_path => '/home/user/trac_env1',
+                  :default_page_name => 'AnnouncingSuccessfulDeployment',
+                  :default_content_file => '/home/user/tmp/deployment')
+end
+
+when_not_TOTALLY_out_of_the_social_scene :twitter do 
+  require 'gossip/cronies/twitter'
+  TwitterCrony.new(:default_login => 'marick@exampler.com',
+                  :default_password => 'twitter password')
+end
+
+
+when_not_TOTALLY_out_of_the_social_scene :standard_output do 
+  require 'gossip/cronies/stdout'
+  StdoutCrony.new
+end
+
+
+
+# CHANGE: add_sources if, for example, you want to override defaults using an 
+# XML file instead of a YAML file.
+
+class GossipCommand
+  
+  # This is the name (in the home directory) of the config file that
+  # applies to all Gossip scripts.
+  def gossip_config_file; ".gossiprc"; end
+  
+  
+  # Determine how the user can override defaults.
+  def add_sources(builder)
+    builder.add_source(PosixCommandLineSource, :usage, *describe_all_but_options)
+    builder.add_source(YamlConfigFileSource, :from_file, script_config_file)
+    builder.add_source(YamlConfigFileSource, :from_file, gossip_config_file)
+  end
+end

data/lib/gossip/social-universe.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-09-17.
+#  Copyright (c) 2007. All rights reserved.
+
+module Gossip
+  
+  CronyMaker = {}
+  
+  # Syntactic sugar to associate a symbol naming a Crony subclass 
+  # with a block that knows how to load that class and create an object
+  # from it. The symbol must be one returned by Crony#symbol.
+ 
+  def when_not_TOTALLY_out_of_the_social_scene(crony, &crony_maker) 
+    CronyMaker[crony] = crony_maker
+  end
+
+end

data/lib/gossip/version.rb

@@ -0,0 +1,8 @@
+#! /opt/local/bin/ruby
+#
+#  Created by Brian Marick on 2007-09-15.
+#  Copyright (c) 2007. All rights reserved.
+
+module Gossip
+  Version = '0.3.0'
+end

data/pages/classes.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+	<head>
+		<title>Gossip</title>
+		<meta http-equiv="Content-Type" content="application/xhtml+xml" />
+		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+		<link rel="stylesheet" type="text/css" media="all" href="css/main.css" />
+	</head>
+	<body>
+	<div id="pageBody">
+		<div id="outer-container">
+			<div id="container">
+			<div id="header">
+				<div id="headerLeft"></div>
+				<div id="headerRight"><h1>Gossip</h1><span class="highlight"><h2>tools for telling people things</h2></span></div>
+			</div>
+			<div id="headerNav">
+					<div id="centerNav">
+					<ul>
+						<li><a href="index.html">Home</a></li>
+						<li><a href="installation.html">Installation</a></li>
+						<li><a href="starting-to-use.html">Using Bundled Scripts</a></li>
+						<li><a href="writing-new-scripts.html">Writing Scripts</a></li>
+						<li><a href="rdoc">RDoc</a></li>
+						<li><a href="http://rubyforge.org/frs/?group_id=4455">Download</a></li>
+					</ul>
+					</div>
+			</div>
+			<div id="content">
+				<h2>The pieces</h2>
+				<p>
+					<img alt="A class diagram of sorts" src="images/classes.png" class="right" />
+					A gossip script doesn't do much more than configure a GossipCommand subclass and then tell it what to do. See "Using Bundled Scripts" for how configuration works. 
+				</p>
+				<p>
+					Gossip uses preteens as its <a href="http://c2.com/xp/SystemMetaphor.html" title="System Metaphor">system metaphor</a>. However, the reader should not assume that the metaphor was inspired by any <em>particular</em> 11-year-old and her social circle. Nor does the use of the variable <code>sophie</code> in the tests mean anything at all. No sirree. 
+					</p>
+					
+					<p>
+					In any case, the GossipCommand's <code>execute</code> sends a Preteen a tell_bff message to have her tell some scandal and its details to her Best Friends Forever (her bffs). These bffs have names like <code>:twitter</code>, <code>:jabber</code>, or <code>:trac</code>. They are instances of the Crony class (more precisely, of a Crony subclass).
+				</p>
+
+				<p>
+					Notice that the "best" in "Best Friends Forever" is not to be taken literally. It is quite typical to have more than one bff. Similarly,  "forever" is more an an aspiration than a literal fact. The set of bffs can change from one invocation of the script to another (according to changes in configuration files or command-line options).
+					</p>
+				<p>
+					Cronies who are not currently in the set of bffs do not hear the gossip.
+					</p>
+				<p>
+					Outside the world of the Preteen and her Cronies, there are&mdash;theoretically&mdash;other people. However, it is inconceivable that they could ever become a Crony, so they can be ignored. (That means that a person writing a script could provide no <code>--trac</code> option. You might do that if you don't use Trac on your project.) 
+				</p>				
+			</div>
+		</div>
+	</div>
+	</body>
+</html>
+

data/pages/cronies.html

@@ -0,0 +1,256 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+	<head>
+		<title>Gossip</title>
+		<meta http-equiv="Content-Type" content="application/xhtml+xml" />
+		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+		<link rel="stylesheet" type="text/css" media="screen" href="css/main.css" />
+	</head>
+	<body>
+	<div id="pageBody">
+		<div id="outer-container">
+			<div id="container">
+			<div id="header">
+				<div id="headerLeft"></div>
+				<div id="headerRight"><h1>Gossip</h1><span class="highlight"><h2>tools for telling people things</h2></span></div>
+			</div>
+			<div id="headerNav">
+					<div id="centerNav">
+					<ul>
+							<li><a href="index.html">Home</a></li>
+							<li><a href="installation.html">Installation</a></li>
+							<li id="current"><a href="starting-to-use.html">Using Bundled Scripts</a></li>
+							<li><a href="writing-new-scripts.html">Writing Scripts</a></li>
+							<li><a href="rdoc">RDoc</a></li>
+							<li><a href="http://rubyforge.org/frs/?group_id=4455">Download</a></li>
+					</ul>
+					</div>
+			</div>
+			<div id="content">
+				<div id="inlineTOC">
+				  <ul>
+				    <li><a href="starting-to-use.html">Getting started</a></li>
+				    <ul>
+				      <li><a href="starting-to-use.html#definitions">Three important words</a></li>
+				      <li><a href="starting-to-use.html#config">Your own private configuration</a></li>
+				    </ul>
+				    <li><a href="cronies.html">All cronies</a></li>
+				    <ul>
+				      <li><a href="cronies.html#campfire">campfire</a></li>
+				      <li><a href="cronies.html#jabber">jabber</a></li>
+				      <li><a href="cronies.html#mail">mail</a></li>
+				      <li><a href="cronies.html#stdout">standard output</a></li>
+				      <li><a href="cronies.html#trac">trac</a></li>
+				      <li><a href="cronies.html#twitter">twitter</a></li>
+				    </ul>
+				    <li><a href="scripts.html">All scripts</a></li>
+				    <ul>
+				      <li><a href="scripts.html#fanout">fanout: broadcast a message</a></li>
+				      <li><a href="scripts.html#watchdog">watchdog: report on a script</a></li>
+				      <li><a href="scripts.html#svntell">svntell: Subversion post-commit</a></li>
+				    </ul>
+				  </ul>
+				</div>
+				<h2>The different cronies</h2>
+				
+				<p>
+					Here are the capsule descriptions:
+				</p>
+				
+				<ul>
+					<li>
+						<p>
+							The <strong><a href="#campfire">campfire crony</a></strong> talks to <a href="http://campfirenow.com/" title="Business chat for groups: Campfire">Campfire</a>, a browser-based chat room.
+						</p>
+					</li>
+					<li>
+						<p>
+							The <strong><a href="#jabber">jabber crony</a></strong> talks <a href="http://www.jabber.org/" title="Jabber: Open Instant Messaging and a Whole Lot More, Powered by XMPP">Jabber</a>, a chat protocol with servers that are easy to set up, making it nice for workgroups.
+						</p>
+					</li>
+					<li>
+						<p>
+							The <strong><a href="#mail">mail crony</a></strong> speaks to email servers via the SMTP protocol. SSL is not supported.
+						</p>
+					</li>
+					<li>
+						<p>
+							The <strong><a href="#stdout">standard output crony</a></strong> just sends mail to standard output (the current window). It's useful checking whether (for example), you're using <code>watchdog</code> correctly before blasting the results to the entire world.
+						</p>
+					</li>
+					<li>
+						<p>
+							The <strong><a href="#trac">trac crony</a></strong> puts a notice in a <a href="http://trac.edgewall.org/" title="The Trac Project - Trac">Trac</a> timeline.
+						</p>
+					</li>
+					<li>
+						<p>
+							The <strong><a href="#twitter">twitter crony</a></strong> sends an update to a <a href="http://twitter.com/home" title="Twitter">Twitter</a> account.
+						</p>
+					</li>
+				</ul>
+
+				<h2><a name="campfire">Campfire</a></h2>
+				<p>My configuration file turns the <code>campfile</code> crony off. I can turn it on with the <code>-c</code> (or <code>--campfire</code>) option, like this:
+
+<pre>
+   % watchdog -c rake
+</pre>
+
+<p>
+	The result at wevouchfor.campfirenow.com looks like this:
+</p>
+
+<img class="center" src="images/campfire.png" />
+
+
+<p>
+	The scandal is the first line of the message; the details are the rest.
+</p>
+<p>
+	To use the <code>campfire</code> crony, you must have a <a href="http://campfirenow.com/" title="Business chat for groups: Campfire">Campfire</a> account with a chat room set up. Set the following in a configuration file or on the command line:
+</p>
+
+<ul>
+	<li><strong>campfire-login</strong>: Usually an email address.</li>
+	<li><strong>campfire-password</strong></li>
+	<li><strong>campfire-subdomain</strong>: Each campfire group gets its own subdomain. Mine is <a href="http://wevouchfor.campfirenow.com/" title="We Vouch For...">http://wevouchfor.campfirenow.com</a>. So my value for this choice is <code>wevouchfor</code>.</li>
+	<li><strong>campfire-room</strong>: A group can have multiple rooms, each with its own name. The one I've used in this case is <code>wevouchfor activity</code>.</li>
+</ul>
+
+				<h2><a name="jabber">Jabber</a></h2>
+				<p>
+					Here is an example of a continuous build server telling jabber (and perhaps other cronies) about a broken build:
+					</p>
+					
+					<img class="center" src="images/jabber-big.png" />
+
+					<p>
+						The scandal is the first line of the message; the details are the rest.
+					</p>
+					
+					<p>
+						To use the <code>jabber</code> crony, you must have an account on some <a href="http://www.jabber.org/" title="Jabber: Open Instant Messaging and a Whole Lot More, Powered by XMPP">Jabber</a> server. In this example, Jabber messages come from <code>huivoufor@jabber.se</code>.
+					</p>
+					
+
+					<ul>
+						<li><strong>jabber-account</strong>: <code>huivoufor@jabber.se</code>, in this case.</li>
+						<li><strong>jabber-password</strong></li>
+						<li><strong>jabber-to</strong>: One or more accounts to sent to. In YAML, that would look like this: 
+<pre>
+	jabber-to: 
+	    - brianmarick@jabberplace.org
+	    - someone@xmpphost.org
+</pre>
+
+<p>If you only want one account to receive the message, you can abbreviate
+	the YAML to this:
+	</p>
+<pre>
+	jabber-to: brianmarick@jabberplace.org
+</pre>	
+
+<p>One the command line, multiple accounts are separated by commas, like this:
+<pre>
+	 --jabber-to=fred@example.com,brianmarick@example.com 
+</pre>
+
+						</li>
+					</ul>
+					
+				<h2><a name="mail">Mail</a></h2>
+				<p>
+					When mail is sent, the scandal is used as the subject line and the details are put into the body. Here are the choices you have to make:
+				</p>
+				<ul>
+					<li><strong>mail-from</strong>: What's put in the From line of the mail message.</li>
+					<li><strong>mail-to</strong>: The intended recipients.
+<pre>
+    mail-to: 
+    - marick@example.com
+    - person@example.org
+</pre>
+
+						<p>If you only want one account to receive the mail, you can abbreviate
+							the YAML to this:
+							</p>
+<pre>
+    mail-to: marick@example.com
+</pre>	
+
+						<p>One the command line, multiple accounts are separated by commas, like this:
+<pre>
+    --mail-to=marick@example.com,person@example.com 
+</pre>
+						</li>
+					<li><strong>mail-server</strong>: An SMTP server.</li>
+					<li><strong>mail-port</strong></li>
+					<li><strong>mail-from-domain</strong>: The domain the mail claims to be from. Some SMTP servers look at this. The default is localhost.</li>
+<li><strong>mail-account</strong>: An account on the server. Not necessarily the same as <code>mail-from</code>.</li>
+					<li><strong>mail-authentication</strong>: One of <code>plain</code>, <code>login</code>, or <code>cram_md5</code>.</li>
+					<li><strong>mail-password</strong></li>
+				</ul>
+				
+				<h2><a name="stdout">Standard output</a></h2>
+				<p>This crony just prints the scandal and details to the current terminal window. There are no options.</p>
+				<h2><a name="trac">Trac</a></h2>
+				<p>
+					The <code>trac</code> crony puts a notice in the <a href="http://trac.edgewall.org/" title="The Trac Project - Trac">Trac</a> timeline, where it looks like this:
+					</p>
+					
+					<img class="center" src="images/trac-bigger.png" />
+					
+					<p>
+						The mechanism is a hack. To do it right, you'd have to write a plugin and enable XMP/RPC and whatnot. So the implementation is to edit a Wiki page, turning the scandal into a header and putting the details below it. That looks like this:
+					</p>
+					
+					<img class="center" src="images/trac-detail.png" />
+					
+					<p>
+						Then, if the Trac timeline is set to display changes to Wiki pages (configurable per-user on the Timeline page), the changed page's title will appear in the Timeline. You have to click through to see the scandal and details.
+						</p>
+						
+						<p>
+							To further ease the implementation, the editing of the Wiki page is done on the server with the <code>trac-admin</code> command. That means the Gossip script has to run on the server too.
+							</p>
+							
+							<p>It would be swell if someone were to contribute a less hackish implementation.
+								</p>
+								<p>
+									To use this implementation, you have to set the following:
+								</p>
+				<ul>
+					<li><strong>trac-admin-path</strong>: The full path of the <code>trac-admin</code> program.</li>
+					<li><strong>trac-environment-path</strong>: The full path of the Trac environment you're using (such as <code>/home/user/trac_env1</code>).</li>
+					<li><strong>trac-page-name</strong>: The name of the wiki page to change.</li>
+					<li><strong>trac-content-file</strong>: The wiki page is changed by copying this file over its contents. Before the Trac crony does that, it puts the scandal and details at the beginning.</li>
+				</ul>
+				
+				<h2><a name="twitter">Twitter</a></h2>
+				<p>
+					Because <a href="http://twitter.com/home" title="Twitter">Twitter</a> is meant for short messages, only the scandal is sent:
+				</p>
+				<img class="center" src="images/twitter.png" />
+				
+				<p>
+					To use the <code>twitter</code> crony, you need a Twitter account. Messages are sent to that account for others to view. The configuration options are:
+				</p>
+				<ul>
+					<li><strong>twitter-login</strong></li>
+					<li><strong>twitter-password</strong></li>
+				</ul>
+				
+				<p style="text-align: center">
+					<a href="scripts.html">Next</a>: All scripts<br />
+				</p>
+				
+
+			</div>
+		</div>
+	</div>
+	
+	</body>
+</html>
+