From 837e71f9cdfb8115e2bdf90b40974f151fd2f79c Mon Sep 17 00:00:00 2001
From: dakkar <dakkar@thenautilus.net>
Date: Fri, 3 Feb 2017 19:11:59 +0000
Subject: POD for ::CmdLine

---
 lib/Sietima/CmdLine.pm | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

(limited to 'lib')

diff --git a/lib/Sietima/CmdLine.pm b/lib/Sietima/CmdLine.pm
index 6ca5615..ee054d5 100644
--- a/lib/Sietima/CmdLine.pm
+++ b/lib/Sietima/CmdLine.pm
@@ -8,18 +8,83 @@ use App::Spec;
 use Sietima::Runner;
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::CmdLine - run Sietima as a command-line application
+
+=head1 SYNOPSIS
+
+  use Sietima::CmdLine;
+
+  Sietima::CmdLine->new({
+    traits => [qw(SubjectTag)],
+    args => {
+      return_path => 'list@example.net',
+      subject_tag => 'Test',
+      subscribers => \@addresses,
+  })->run;
+
+=head1 DESCRIPTION
+
+This class simplifies the creation of a L<< C<Sietima> >> object, and
+uses L<< C<App::Spec> >> to provide a command-line interface to it.
+
+=head1 ATTRIBUTES
+
+=head2 C<sietima>
+
+Required, an instance of L<< C<Sietima> >>. You can either construct
+it yourself, or use the L<simplified building provided by the
+constructor|/new>.
+
+=cut
+
 has sietima => (
     is => 'ro',
     required => 1,
     isa => SietimaObj,
 );
 
+=head2 C<extra_spec>
+
+Optional hashref. Used inside L<< /C<app_spec> >>. If you're not
+familiar with L<< C<App::Spec> >>, you probably don't want to touch
+this.
+
+=cut
+
 has extra_spec => (
     is => 'ro',
     isa => HashRef,
     default => sub { +{} },
 );
 
+=head1 METHODS
+
+=head2 C<new>
+
+  my $cmdline = Sietima::CmdLine->new({
+    sietima => Sietima->with_traits(qw(SubjectTag))->new({
+      return_path => 'list@example.net',
+      subject_tag => 'Test',
+      subscribers => \@addresses,
+    }),
+  });
+
+  my $cmdline = Sietima::CmdLine->new({
+    traits => [qw(SubjectTag)],
+    args => {
+      return_path => 'list@example.net',
+      subject_tag => 'Test',
+      subscribers => \@addresses,
+  });
+
+The constructor. In alternative to passing a L<< C<Sietima> >>
+instance, you can pass C<traits> and C<args>, and the instance will be
+built for you. The two calls above are equivalent.
+
+=cut
+
 sub BUILDARGS($class,@args) {
     my $args = $class->next::method(@args);
     $args->{sietima} //= do {
@@ -30,6 +95,17 @@ sub BUILDARGS($class,@args) {
     return $args;
 }
 
+=head2 C<app_spec>
+
+Returns an instance of L<< C<App::Spec> >>, built from the
+specification returned by calling L<<
+C<command_line_spec>|Sietima/command_line_spec >> on the L<<
+/C<sietima> >> object, modified by the L<< /C<extra_spec> >>. This
+method, and the C<extra_spec> attribute, are probably only interesting
+to people who are doing weird extensions.
+
+=cut
+
 has app_spec => (
     is => 'lazy',
     init_arg => undef,
@@ -44,6 +120,20 @@ sub _build_app_spec($self) {
     });
 }
 
+=head2 C<runner>
+
+Returns an instance of L<< C<Sietima::Runner> >>, built from the L<<
+/C<app_spec> >>.
+
+=head2 C<run>
+
+Delegates to the L<< /C<runner> >>'s L<< C<run>|App::Spec::Run/run >> method.
+
+Parser the command line arguments from C<@ARGV> and executes the
+appropriate action.
+
+=cut
+
 has runner => (
     is => 'lazy',
     init_arg => undef,
-- 
cgit v1.2.3