More docs

Changes

@@ -1,3 +1,5 @@
+    - Improve documentation.
+
 0.004
     - Changes to match up with Message::Passing 0.006
 

README

@@ -3,11 +3,11 @@ NAME
 
 SYNOPSIS
         # Terminal 1:
-        $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5558"}'
+        $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5552"}'
         {"data":{"some":"data"},"@metadata":"value"}
 
         # Terminal 2:
-        $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5558"}'
+        $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5552"}'
         {"data":{"some":"data"},"@metadata":"value"}
 
 DESCRIPTION
@@ -36,22 +36,33 @@ DESCRIPTION
 
 HOW TO USE
     In your application emitting messages, you can either use
-    Message::Passing::Output::ZeroMQ directly, of you can use it via
+    Message::Passing::Output::ZeroMQ directly, or you can use it via
     Log::Dispatch::Message::Passing.
 
-        # FIXME - Example code, including overriding IP to connect to here
+        use Log::Dispatch;
+        use Log::Dispatch::Message::Passing;
+        use Message::Passing::Output::ZeroMQ;
+        use Message::Passing::Filter::Encode::JSON;
+
+        my $log = Log::Dispatch->new;
+
+        $log->add(Log::Dispatch::Message::Passing->new(
+            name      => 'myapp_aggregate_log',
+            min_level => 'debug',
+            output    => Message::Passing::Filter::Encode::JSON->new(
+              output_to => Message::Passing::Output::ZeroMQ->new(
+                connect => 'tcp://192.168.0.1:5558',
+              )
+            ),
+        ));
+
+        $log->warn($_) for qw/ foo bar baz /;
 
     On your log aggregation server, just run the message-passing utility:
 
         message-passing --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5222"}' \
             --output File --output_options '{"filename":"/tmp/my_test.log"}'
 
-CONNECTION DIRECTION
-    Note that in ZeroMQ, the connection direction and the direction of
-    message flow can be entirely opposite. I.e. a client can connect to a
-    server and send messages to it, or receive messages from it (depending
-    on the direction of the socket types).
-
 SOCKET TYPES
     ZeroMQ supports multiple socket types, the only ones used in
     Message::Passing::ZeroMQ are:
@@ -73,6 +84,33 @@ SOCKET TYPES
     In Message::Passing terms, Message::Passing::Input::ZeroMQ is for PULL
     sockets, and Message::Passing::Output::ZeroMQ is for PUSH sockets.
 
+CONNECTION DIRECTION
+    Note that in ZeroMQ, the connection direction and the direction of
+    message flow can be entirely opposite. I.e. a client can connect to a
+    server and send messages to it, or receive messages from it (depending
+    on the direction of the socket types).
+
+CONNECTION ATTRIBUTES
+    Both Message::Passing::Input::ZeroMQ and
+    Message::Passing::Output::ZeroMQ support either binding a server or
+    connecting to a remote host, due to the fact that ZeroMQ connections can
+    be in any direction, as noted above.
+
+    Therefore, each input or output should have one (but not both!) of the
+    following attributes:
+
+  connect
+    Connects to a remote server, e.g. "tcp://192.168.0.1:5222"
+
+  socket_bind
+    Binds a server and waits for connections from clients, e.g.
+    "tcp://*:5222"
+
+  socket_type
+    This defaults to "SUB" for Message::Passing::Input::ZeroMQ and "PUB" for
+    Message::Passing::Output::ZeroMQ, however you can override it to
+    "PUSH"/"PULL" as appropriate for your use case if desired.
+
 MORE COMPLEX EXAMPLES
     With this in mind, we can easily create a system which aggregates
     messages from multiple publishers, and passes them out (in a round-robin
@@ -115,6 +153,7 @@ SEE ALSO
     Message::Passing
     ZeroMQ
     <http://www.zeromq.org/>
+    <http://zguide.zeromq.org/page:all>
 
 AUTHOR
     Tomas (t0m) Doran <bobtfish@bobtfish.net>

lib/Message/Passing/Input/ZeroMQ.pm

@@ -74,8 +74,21 @@ sub BUILD {
 
 Message::Passing::Input::ZeroMQ - input messages from ZeroMQ.
 
+=head1 SYNOPSIS
+
+    message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5552"}'
+
 =head1 DESCRIPTION
 
+A L<Message::Passing> ZeroMQ input class.
+
+Can be used as part of a chain of classes with the L<message-passing> utility, or directly as
+an input with L<Message::Passing::DSL>.
+
+=head1 ATTRIBUTES
+
+See L<Message::Passing::ZeroMQ/CONNECTION ATTRIBUTES>
+
 =head1 SEE ALSO
 
 =over

lib/Message/Passing/Output/ZeroMQ.pm

@@ -43,21 +43,28 @@ Message::Passing::Output::ZeroMQ - output messages to ZeroMQ.
     # simple logging.
 
     # Or use directly on command line:
-    message-passing --input STDIN --output ZeroMQ
+    message-passing --input STDIN --output ZeroMQ --output_options \
+        '{"connect":"tcp://192.168.0.1:5552"}'
     {"data":{"some":"data"},"@metadata":"value"}
 
 =head1 DESCRIPTION
 
-A L<Message::Passing> L<ZeroMQ> output class.
+A L<Message::Passing> ZeroMQ output class.
 
 Can be used as part of a chain of classes with the L<message-passing> utility, or directly as
 a logger in normal perl applications.
 
+=head1 ATTRIBUTES
+
+See L<Message::Passing::ZeroMQ/CONNECTION ATTRIBUTES>.
+
 =head1 METHODS
 
-=head2 consume
+=head2 consume ($msg)
 
-Sends a message.
+Sends a message, as-is. This means that you must have encoded the message to a string before
+sending it. The C<message-pass> utility will do this for you into JSON, or you can
+do it manually as shown in the example in L<Message::Passing::ZeroMQ>.
 
 =head1 SEE ALSO
 

lib/Message/Passing/ZeroMQ.pm

@@ -26,11 +26,11 @@ Message::Passing::ZeroMQ - input and output messages to ZeroMQ.
 =head1 SYNOPSIS
 
     # Terminal 1:
-    $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5558"}'
+    $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5552"}'
     {"data":{"some":"data"},"@metadata":"value"}
 
     # Terminal 2:
-    $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5558"}'
+    $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5552"}'
     {"data":{"some":"data"},"@metadata":"value"}
 
 =head1 DESCRIPTION
@@ -54,22 +54,33 @@ server) is significantly less acceptable than the loss of non-essential logging
 
 =head1 HOW TO USE
 
-In your application emitting messages, you can either use L<Message::Passing::Output::ZeroMQ> directly, of you can use
-it via L<Log::Dispatch::Message::Passing>.
+In your application emitting messages, you can either use L<Message::Passing::Output::ZeroMQ> directly, 
+or you can use it via L<Log::Dispatch::Message::Passing>.
 
-    # FIXME - Example code, including overriding IP to connect to here
+    use Log::Dispatch;
+    use Log::Dispatch::Message::Passing;
+    use Message::Passing::Output::ZeroMQ;
+    use Message::Passing::Filter::Encode::JSON;
+
+    my $log = Log::Dispatch->new;
+
+    $log->add(Log::Dispatch::Message::Passing->new(
+        name      => 'myapp_aggregate_log',
+        min_level => 'debug',
+        output    => Message::Passing::Filter::Encode::JSON->new(
+          output_to => Message::Passing::Output::ZeroMQ->new(
+            connect => 'tcp://192.168.0.1:5558',
+          )
+        ),
+    ));
+
+    $log->warn($_) for qw/ foo bar baz /;
 
 On your log aggregation server, just run the message-passing utility:
 
     message-passing --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5222"}' \
         --output File --output_options '{"filename":"/tmp/my_test.log"}'
 
-=head1 CONNECTION DIRECTION
-
-Note that in ZeroMQ, the connection direction and the direction of message flow can be
-entirely opposite. I.e. a client can connect to a server and send messages to it, or
-receive messages from it (depending on the direction of the socket types).
-
 =head1 SOCKET TYPES
 
 ZeroMQ supports multiple socket types, the only ones used in Message::Passing::ZeroMQ are:
@@ -93,6 +104,34 @@ a number of connecting clients (PULL)
 In Message::Passing terms, L<Message::Passing::Input::ZeroMQ> is for PULL sockets, and
 L<Message::Passing::Output::ZeroMQ> is for PUSH sockets.
 
+=head1 CONNECTION DIRECTION
+
+Note that in ZeroMQ, the connection direction and the direction of message flow can be
+entirely opposite. I.e. a client can connect to a server and send messages to it, or
+receive messages from it (depending on the direction of the socket types).
+
+=head1 CONNECTION ATTRIBUTES
+
+Both L<Message::Passing::Input::ZeroMQ> and L<Message::Passing::Output::ZeroMQ> support
+either binding a server or connecting to a remote host, due to the fact that ZeroMQ connections
+can be in any direction, as noted above.
+
+Therefore, each input or output should have one (but not both!) of the following attributes:
+
+=head2 connect
+
+Connects to a remote server, e.g. C<< tcp://192.168.0.1:5222 >>
+
+=head2 socket_bind
+
+Binds a server and waits for connections from clients, e.g. C<< tcp://*:5222 >>
+
+=head2 socket_type
+
+This defaults to C<SUB> for L<Message::Passing::Input::ZeroMQ> and C<PUB> for
+L<Message::Passing::Output::ZeroMQ>, however you can override it to C<PUSH>/C<PULL> as
+appropriate for your use case if desired.
+
 =head1 MORE COMPLEX EXAMPLES
 
 With this in mind, we can easily create a system which aggregates messages from
@@ -142,6 +181,8 @@ For more detailed information about ZeroMQ and how it works, please consult the
 
 =item L<http://www.zeromq.org/>
 
+=item L<http://zguide.zeromq.org/page:all>
+
 =back
 
 =head1 AUTHOR