Propagate the new Reflex::Role usage to old users of Reflex::Util::Me…

…thods. I still don't like the function names, but they're good placeholders for now.

docs/intro/AfterAwhileRole.pm

@@ -1,27 +1,25 @@
 package AfterAwhileRole;
-use MooseX::Role::Parameterized;
-use Reflex::Util::Methods qw(method_name emit_an_event);
+use Reflex::Role;
 
-parameter name    => ( isa => 'Str', default => 'name' );
-parameter awhile  => ( isa => 'Str', default => 'awhile' );
-parameter cb      => method_name("on", "name", "done");
+attribute_parameter name    => "name";
+attribute_parameter awhile  => "awhile";
+callback_parameter  cb      => qw( on name done );
 
 role {
 	my $role_param = shift;
 
-	my $role_name = $role_param->name();
 	my $cb_done   = $role_param->cb();
 	my $awhile    = $role_param->awhile();
 
+	method_emit $cb_done => "done";
+
 	sub BUILD {}
 
 	after BUILD => sub {
 		my $self = shift;
 		sleep($self->$awhile());
 		$self->$cb_done();
 	};
-
-	method $cb_done => emit_an_event("done");
 };
 
 1;

docs/intro/AsyncAwhileRole.pm

@@ -1,12 +1,11 @@
 package AsyncAwhileRole;
-use MooseX::Role::Parameterized;
-use Reflex::Util::Methods qw(method_name emit_an_event);
+use Reflex::Role;
 use Reflex::Timer;
 use Reflex::Callbacks qw(cb_method);
 
-parameter name    => ( isa => 'Str', default => 'name' );
-parameter awhile  => ( isa => 'Str', default => 'awhile' );
-parameter cb      => method_name("on", "name", "done");
+attribute_parameter name    => "name";
+attribute_parameter awhile  => "awhile";
+callback_parameter  cb      => qw( on name done );
 
 role {
 	my $role_param = shift;
@@ -19,6 +18,8 @@ role {
 
 	has $timer_member => ( is => 'rw', isa => 'Reflex::Timer' );
 
+	method_emit $cb_done => "done";
+
 	sub BUILD {}
 
 	after BUILD => sub {
@@ -31,8 +32,6 @@ role {
 			)
 		);
 	};
-
-	method $cb_done => emit_an_event("done");
 };
 
 1;

docs/intro/intro.pod

@@ -6,22 +6,25 @@ Reflex::Doc - What is Reflex, and how do I use it?
 
 =head1 WHAT IS REFLEX?
 
-Reflex is a reactive programming library for Perl.  It uses Moose, a
-widely accepted standard for OO Perl, rather than concocting its own
-roles and classes.
+Reflex is a reactive programming library for Perl.  It provides the
+basic (and some advanced) building blocks for event driven modules and
+programs.
+
+Reflex uses Moose, a widely accepted standard for OO Perl, rather than
+concocting its own roles and classes.
 
 Reflex was designed to unify many forms of reactive programming.  It
 currently supports all of these, in the same program if necessary:
 
 =over 4
 
-=item plain old callbacks, using coderefs or methods
+=item * plain old callbacks, using coderefs or methods
 
-=item promises, which work in an inline imperative fashion
+=item * promises, which are used inline in an imperative fashion
 
-=item role-based composition of complex reactive classes
+=item * role-based composition of complex reactive classes
 
-=item class-based composition using inheritance.
+=item * class-based composition using inheritance.
 
 =back
 
@@ -60,29 +63,27 @@ That's a bit of work, but roles are generally the biggest Reflex
 modules.  The classes that use it are much smaller.
 
 	package AfterAwhileRole;
-	use MooseX::Role::Parameterized;
-	use Reflex::Util::Methods qw(method_name emit_an_event);
+	use Reflex::Role;
 
-	parameter name    => ( isa => 'Str', default => 'name' );
-	parameter awhile  => ( isa => 'Str', default => 'awhile' );
-	parameter cb      => method_name("on", "name", "done");
+	attribute_parameter name    => "name";
+	attribute_parameter awhile  => "awhile";
+	callback_parameter  cb      => qw( on name done );
 
 	role {
 		my $role_param = shift;
 
-		my $role_name = $role_param->name();
 		my $cb_done   = $role_param->cb();
 		my $awhile    = $role_param->awhile();
 
+		method_emit $cb_done => "done";
+
 		sub BUILD {}
 
 		after BUILD => sub {
 			my $self = shift;
 			sleep($self->$awhile());
 			$self->$cb_done();
 		};
-
-		method $cb_done => emit_an_event("done");
 	};
 
 	1;
@@ -243,14 +244,13 @@ Reflex::Timer object.  Later we'll introduce magic to make it more
 concise.
 
 	package AsyncAwhileRole;
-	use MooseX::Role::Parameterized;
-	use Reflex::Util::Methods qw(method_name emit_an_event);
+	use Reflex::Role;
 	use Reflex::Timer;
 	use Reflex::Callbacks qw(cb_method);
 
-	parameter name    => ( isa => 'Str', default => 'name' );
-	parameter awhile  => ( isa => 'Str', default => 'awhile' );
-	parameter cb      => method_name("on", "name", "done");
+	attribute_parameter name    => "name";
+	attribute_parameter awhile  => "awhile";
+	callback_parameter  cb      => qw( on name done );
 
 	role {
 		my $role_param = shift;
@@ -259,9 +259,12 @@ concise.
 		my $cb_done   = $role_param->cb();
 		my $awhile    = $role_param->awhile();
 
-		my $timer_member  = "_${role_name}_timer";
+		my $timer_member = "_${role_name}_timer";
+
 		has $timer_member => ( is => 'rw', isa => 'Reflex::Timer' );
 
+		method_emit $cb_done => "done";
+
 		sub BUILD {}
 
 		after BUILD => sub {
@@ -274,8 +277,6 @@ concise.
 				)
 			);
 		};
-
-		method $cb_done => emit_an_event("done");
 	};
 
 	1;

eg/eg-39-signals.pl

@@ -4,18 +4,18 @@
 use strict;
 use lib qw(../lib);
 
-use Reflex::SigCatcher;
+use Reflex::Signal;
 use Reflex::Callbacks qw(cb_coderef);
 use ExampleHelpers qw(eg_say);
 
 eg_say("Process $$ is waiting for SIGUSR1 and SIGUSR2.");
 
-my $usr1 = Reflex::SigCatcher->new(
+my $usr1 = Reflex::Signal->new(
 	signal    => "USR1",
 	on_signal => cb_coderef { eg_say("Got SIGUSR1.") },
 );
 
-my $usr2 = Reflex::SigCatcher->new( signal => "USR2" );
+my $usr2 = Reflex::Signal->new( signal => "USR2" );
 while ($usr2->next()) {
 	eg_say("Got SIGUSR2.");
 }

lib/Reflex.pm

@@ -339,16 +339,6 @@ observable object attributes.
 
 =back
 
-=head2 Generic Utilities
-
-Miscellaneous helper functions.
-
-=over 2
-
-=item Reflex::Util::Methods - helper functions to generate methods
-
-=back
-
 =head1 ASSISTANCE
 
 Thank you for volunteering to assist with this project.  You can find

lib/Reflex/Role.pm

@@ -11,7 +11,7 @@ use Moose::Exporter;
 Moose::Exporter->setup_import_methods(
 	with_caller => [ qw(
 		attribute_parameter method_parameter callback_parameter
-		method_emit_and_stop
+		method_emit_and_stop method_emit
 	) ],
 	also => 'MooseX::Role::Parameterized',
 );
@@ -45,6 +45,8 @@ sub method_parameter {
 
 	my ($name, $prefix, $member, $suffix) = @_;
 
+	# TODO - $member must have been declared as an attribute_parameter.
+
 	$meta->add_parameter(
 		$name,
 		(
@@ -70,6 +72,28 @@ sub method_emit_and_stop {
 
 		my ($method_name, $event_name) = @_;
 
+    my $method = $meta->method_metaclass->wrap(
+        package_name => $caller,
+        name         => $method_name,
+        body         => sub {
+					my ($self, $args) = @_;
+					$self->emit(event => $event_name, args => $args);
+					$self->stopped();
+				},
+    );
+
+    $meta->add_method($method_name => $method);
+}
+
+sub method_emit {
+    my $caller = shift;
+    my $meta   = (
+			MooseX::Role::Parameterized::current_metaclass() ||
+			Class::MOP::class_of($caller)
+		);
+
+		my ($method_name, $event_name) = @_;
+
     my $method = $meta->method_metaclass->wrap(
         package_name => $caller,
         name         => $method_name,
@@ -85,6 +109,10 @@ sub method_emit_and_stop {
 # Aliased here.
 # TODO - Find out how Moose::Exporter might export method_parameter()
 # as both names.
+#
+# TODO - Default emit methods (method_emit and method_emit_and_stop)
+# are common for callback parameters.  We could include callback
+# parameter flags to automatically generate those methods.
 BEGIN { *callback_parameter = *method_parameter; }
 
 1;

lib/Reflex/Role/Accepting.pm

@@ -1,17 +1,13 @@
 package Reflex::Role::Accepting;
-use MooseX::Role::Parameterized;
-use Reflex::Util::Methods qw(emit_an_event emit_and_stopped method_name);
+use Reflex::Role;
 
-parameter listener => (
-	isa     => 'Str',
-	default => 'listener',
-);
+attribute_parameter listener => "listener";
 
-parameter cb_accept     => method_name("on", "listener", "accept");
-parameter cb_error      => method_name("on", "listener", "error");
-parameter method_pause  => method_name("pause", "listener", undef);
-parameter method_resume => method_name("resume", "listener", undef);
-parameter method_stop   => method_name("stop", "listener", undef);
+callback_parameter  cb_accept     => qw( on listener accept );
+callback_parameter  cb_error      => qw( on listener error );
+method_parameter    method_pause  => qw( pause listener _ );
+method_parameter    method_resume => qw( resume listener _ );
+method_parameter    method_stop   => qw( stop listener _ );
 
 role {
 	my $p = shift;
@@ -48,8 +44,8 @@ role {
 		return;
 	};
 
-	method $cb_accept => emit_an_event("accept");
-	method $cb_error  => emit_an_event("error");  # TODO - Retryable ones.
+	method_emit $cb_accept  => "accept";
+	method_emit $cb_error   => "error";   # TODO - Retryable ones.
 
 	with 'Reflex::Role::Readable' => {
 		handle        => $listener,

lib/Reflex/Role/Connecting.pm

@@ -1,27 +1,15 @@
 package Reflex::Role::Connecting;
-use MooseX::Role::Parameterized;
-use Reflex::Util::Methods qw(emit_an_event emit_and_stopped method_name);
+use Reflex::Role;
 
 use Errno qw(EWOULDBLOCK EINPROGRESS);
 use Socket qw(SOL_SOCKET SO_ERROR inet_aton pack_sockaddr_in);
 
-parameter socket => (
-	isa     => 'Str',
-	default => 'socket',
-);
+attribute_parameter socket  => "socket";
+attribute_parameter address => "address";
+attribute_parameter port    => "port";
 
-parameter address => (
-	isa     => 'Str',
-	default => 'address',
-);
-
-parameter port => (
-	isa       => 'Str',
-	default   => 'port',
-);
-
-parameter cb_success  => method_name("on", "socket", "success");
-parameter cb_error    => method_name("on", "socket", "error");
+callback_parameter  cb_success  => qw( on socket success );
+callback_parameter  cb_error    => qw( on socket error );
 
 role {
 	my $p = shift;
@@ -115,8 +103,8 @@ role {
 		return;
 	};
 
-	method $cb_success  => emit_an_event("success");
-	method $cb_error    => emit_an_event("error");
+	method_emit $cb_success => "success";
+	method_emit $cb_error   => "error";
 
 	with 'Reflex::Role::Writable' => {
 		handle  => $socket,

lib/Reflex/Role/Reading.pm

@@ -1,18 +1,16 @@
 package Reflex::Role::Reading;
-use MooseX::Role::Parameterized;
-use Reflex::Util::Methods qw(emit_an_event emit_and_stopped method_name);
+use Reflex::Role;
 
-parameter handle => (
-	isa     => 'Str',
-	default => 'handle',
-);
+attribute_parameter handle    => "handle";
 
-parameter cb_data     => method_name("on", "handle", "data");
-parameter cb_error    => method_name("on", "handle", "error");
-parameter cb_closed   => method_name("on", "handle", "closed");
+callback_parameter cb_data    => qw( on handle data );
+callback_parameter cb_error   => qw( on handle error );
+callback_parameter cb_closed  => qw( on handle closed );
 
 # Matches Reflex::Role::Readable's default callback.
-parameter method_read => method_name("on", "handle", "readable");
+# TODO - Any way we can coordinate this so it's obvious in the code
+# but not too verbose?
+method_parameter  method_read => qw( on handle readable );
 
 role {
 	my $p = shift;
@@ -53,8 +51,8 @@ role {
 	};
 
 	# Default callbacks that re-emit their parameters.
-	method $cb_data   => emit_an_event("data");
-	method $cb_closed => emit_and_stopped("closed");
+	method_emit           $cb_data    => "data";
+	method_emit_and_stop  $cb_closed  => "closed";
 };
 
 1;