fix a few small inconsistencies and update Changes

mojolicious · Apr 4, 2017 · 8b60d3a · 8b60d3a
1 parent 19b8d66
commit 8b60d3a
Show file tree

Hide file tree

Showing 7 changed files with 67 additions and 45 deletions.
diff --git a/Changes b/Changes
@@ -1,5 +1,12 @@
 
-7.30  2017-03-15
+7.30  2017-04-04
+  - Deprecated Mojo::Server::Morbo::watch in favor of
+    Mojo::Server::Morbo::Backend::Poll::watch. (marcus)
+  - Added support for pluggable Morbo backends. (marcus)
+  - Added Mojo::Server::Morbo::Backend and Mojo::Server::Morbo::Backend::Poll
+    modules. (marcus)
+  - Added backend attribute to Mojo::Server::Morbo. (marcus)
+  - Added -b option to Morbo. (marcus)
 
 7.29  2017-03-12
   - Added support for overriding configuration files in applications tested with

diff --git a/lib/Mojo/Server/Morbo.pm b/lib/Mojo/Server/Morbo.pm
@@ -10,12 +10,11 @@ use Mojo::Util 'deprecated';
 use POSIX 'WNOHANG';
 
 has backend => sub {
-  my $backend
-    = 'Mojo::Server::Morbo::Backend::' . ($ENV{MOJO_MORBO_BACKEND} || 'Poll');
-  return $backend->new unless my $e = load_class($backend);
-  die ref $e
-    ? $e
-    : qq{Can't find Morbo backend class "$backend" in \@INC. (@INC)\n};
+  my $backend = $ENV{MOJO_MORBO_BACKEND} || 'Poll';
+  $backend = "Mojo::Server::Morbo::Backend::$backend";
+  return $backend->new unless my $e = load_class $backend;
+  die $e if ref $e;
+  die qq{Can't find Morbo backend class "$backend" in \@INC. (@INC)\n};
 };
 has daemon => sub { Mojo::Server::Daemon->new };
 
@@ -39,7 +38,8 @@ sub run {
 
 # DEPRECATED!
 sub watch {
-  deprecated 'watch is deprecated in favor of backend->watch';
+  deprecated 'Mojo::Server::Morbo::watch is DEPRECATED'
+    . ' in favor of Mojo::Server::Morbo::Backend::Poll::watch';
   shift->backend->watch(@_);
 }
 
@@ -132,10 +132,9 @@ L<Mojo::Server::Morbo> implements the following attributes.
 =head2 backend
 
   my $backend = $morbo->backend;
-  $backend    = $morbo->backend(Mojo::Server::Morbo::Backend::Poll->new);
+  $morbo      = $morbo->backend(Mojo::Server::Morbo::Backend::Poll->new);
 
-L<Mojo::Server::Morbo::Backend> object responsible for watching the source for
-changes.
+Backend, usually a L<Mojo::Server::Morbo::Backend::Poll> object.
 
 =head2 daemon
 

diff --git a/lib/Mojo/Server/Morbo/Backend.pm b/lib/Mojo/Server/Morbo/Backend.pm
@@ -4,7 +4,7 @@ use Mojo::Base -base;
 use Carp 'croak';
 
 has watch => sub { [qw(lib templates)] };
-has watch_timeout => sub { $ENV{MORBO_BACKEND_TIMEOUT} || 1 };
+has watch_timeout => sub { $ENV{MOJO_MORBO_TIMEOUT} || 1 };
 
 sub modified_files {
   croak 'Method "modified_files" not implemented by subclass';
@@ -27,9 +27,8 @@ Mojo::Server::Morbo::Backend - Morbo backend base class
 
 =head1 DESCRIPTION
 
-L<Mojo::Server::Morbo::Backend> is an abstract base class for the morbo
-auto-reloader backend. The default included with Mojo is
-L<Mojo::Server::Morbo::Backend::Poll>.
+L<Mojo::Server::Morbo::Backend> is an abstract base class for Morbo backends,
+like L<Mojo::Server::Morbo::Backend::Poll>.
 
 =head1 ATTRIBUTES
 
@@ -46,11 +45,12 @@ directory.
 
 =head2 watch_timeout
 
-  my $watch_timeout = $backend->watch_timeout;
-  $backend          = $backend->watch_timeout(10);
+  my $timeout = $backend->watch_timeout;
+  $backend    = $backend->watch_timeout(10);
 
-Backends should not block longer than this many seconds to wait for events. Defaults
-to 1 or the MORBO_BACKEND_TIMEOUT environment variable.
+Maximum amount of time in seconds a backend may block when waiting for files to
+change, defaults to the value of the C<MOJO_MORBO_TIMEOUT> environment variable
+or C<1>.
 
 =head1 METHODS
 
@@ -62,14 +62,12 @@ implements the following new ones.
   my $files = $backend->modified_files;
 
 Check if files from L</"watch"> have been modified since the last check and
-return an array reference with the results.
+return an array reference with the results. Meant to be overloaded in a
+subclass.
 
   # All files that have been modified
   say for @{$backend->modified_files};
 
-Meant to be implemented in a subclass. Make sure your implementation uses
-the L</"watch_timeout"> attribute to return for signal handling.
-
 =head1 SEE ALSO
 
 L<Mojolicious>, L<Mojolicious::Guides>, L<http://mojolicious.org>.

diff --git a/lib/Mojo/Server/Morbo/Backend/Poll.pm b/lib/Mojo/Server/Morbo/Backend/Poll.pm
@@ -29,27 +29,41 @@ sub _list { path(shift)->list_tree->map('to_string')->each }
 
 =head1 NAME
 
-Mojo::Server::Morbo::Backend::Poll - Morbo default backend class
+Mojo::Server::Morbo::Backend::Poll - Morbo default backend
 
 =head1 SYNOPSIS
 
+  use Mojo::Server::Morbo::Backend::Poll;
+
   my $backend = Mojo::Server::Morbo::Backend::Poll->new;
-  if ($backend->modified_files) {...}
+  if (my $files = $backend->modified_files) {
+    ...
+  }
 
 =head1 DESCRIPTION
 
-L<Mojo::Server::Morbo::Backend:Poll> is the default reloader backend for
+L<Mojo::Server::Morbo::Backend:Poll> is the default backend for
 L<Mojo::Server::Morbo>.
 
+=head1 ATTRIBUTES
+
+L<Mojo::Server::Morbo::Backend::Poll> inherits all attributes from
+L<Mojo::Server::Morbo::Backend>.
+
 =head1 METHODS
 
 L<Mojo::Server::Morbo::Backend::Poll> inherits all methods from
-L<Mojo::Server::Morbo::Backend>.
+L<Mojo::Server::Morbo::Backend> and implements the following new ones.
 
 =head2 modified_files
 
-Checks the mtime timestamp for all the watched files and returns
-an array reference with any modified files.
+  my $files = $backend->modified_files;
+
+Check file size and mtime to determine which files have changed, this is not
+particularly efficient, but very portable.
+
+  # All files that have been modified
+  say for @{$backend->modified_files};
 
 =head1 SEE ALSO
 

diff --git a/lib/Mojolicious/Guides.pod b/lib/Mojolicious/Guides.pod
@@ -347,6 +347,14 @@ This is the class hierarchy of the L<Mojolicious> distribution.
 
 =item * L<Mojo::Server::Morbo>
 
+=item * L<Mojo::Server::Morbo::Backend>
+
+=over 2
+
+=item * L<Mojo::Server::Morbo::Backend::Poll>
+
+=back
+
 =item * L<Mojo::Template>
 
 =item * L<Mojo::URL>

diff --git a/script/morbo b/script/morbo
@@ -35,9 +35,8 @@ morbo - Morbo HTTP and WebSocket development server
     morbo -w /usr/local/lib -w public -w myapp.conf ./myapp.pl
 
   Options:
-    -b, --backend <name>           Morbo backend to use for the reloader
-                                   defaults to 'Poll'
-                                   (Mojo::Server::Morbo::Backend::Poll)
+    -b, --backend <name>           Morbo backend to use for reloading, defaults
+                                   to "Poll"
     -h, --help                     Show this message
     -l, --listen <location>        One or more locations you want to listen on,
                                    defaults to the value of MOJO_LISTEN or

diff --git a/t/mojo/morbo.t b/t/mojo/morbo.t
@@ -140,6 +140,16 @@ SKIP: {
 kill 'INT', $pid;
 sleep 1 while _port($port);
 
+# Custom backend
+{
+  local $ENV{MOJO_MORBO_BACKEND} = 'TestBackend';
+  my $test_morbo = Mojo::Server::Morbo->new;
+  isa_ok $test_morbo->backend, 'Mojo::Server::Morbo::Backend::TestBackend',
+    'right backend';
+  is_deeply $test_morbo->backend->modified_files, ['always_changed'],
+    'always changes';
+}
+
 # SO_REUSEPORT
 SKIP: {
   skip 'SO_REUSEPORT support required!', 2 unless eval { _reuse_port() };
@@ -172,17 +182,4 @@ sub _reuse_port {
   );
 }
 
-
-{
-  local $ENV{MOJO_MORBO_BACKEND} = 'TestBackend';
-  my $test_morbo = Mojo::Server::Morbo->new;
-  isa_ok(
-    $test_morbo->backend,
-    'Mojo::Server::Morbo::Backend::TestBackend',
-    'right backend'
-  );
-  is_deeply($test_morbo->backend->modified_files,
-    ['always_changed'], 'Correct response');
-}
-
 done_testing();