From 086e9d2e9cc4ec743248fb08ddeed688dc8a9129 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Sun, 30 Jan 2022 17:28:38 +0100
Subject: Document new_p

---
 lib/Travel/Status/DE/IRIS.pm | 57 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/lib/Travel/Status/DE/IRIS.pm b/lib/Travel/Status/DE/IRIS.pm
index 79e96d9..7bd180b 100644
--- a/lib/Travel/Status/DE/IRIS.pm
+++ b/lib/Travel/Status/DE/IRIS.pm
@@ -928,6 +928,8 @@ Travel::Status::DE::IRIS - Interface to IRIS based web departure monitors.
 
 =head1 SYNOPSIS
 
+Blocking variant:
+
     use Travel::Status::DE::IRIS;
     use Travel::Status::DE::IRIS::Stations;
 
@@ -943,6 +945,30 @@ Travel::Status::DE::IRIS - Interface to IRIS based web departure monitors.
         );
     }
 
+Non-blocking variant:
+
+    use Mojo::Promise;
+    use Mojo::UserAgent;
+    use Travel::Status::DE::IRIS;
+    use Travel::Status::DE::IRIS::Stations;
+
+    # Get station code for "Essen Hbf" (-> "EE")
+    my $station = (Travel::Status::DE::IRIS::Stations::get_station_by_name(
+        'Essen Hbf'))[0][0];
+    
+    Travel::Status::DE::IRIS->new_p(station => $station,
+            promise => 'Mojo::Promise', user_agent => Mojo::UserAgent->new,
+            get_station => \&Travel::Status::DE::IRIS::Stations::get_station,
+            meta => Travel::Status::DE::IRIS::Stations::get_meta())->then(sub {
+        my ($status) = @_;
+        for my $r ($status->results) {
+            printf(
+                "%s %s +%-3d %10s -> %s\n",
+                $r->date, $r->time, $r->delay || 0, $r->line, $r->destination
+            );
+        }
+    })->wait;
+
 =head1 VERSION
 
 version 1.63
@@ -1055,6 +1081,37 @@ departures for all related stations.
 
 =back
 
+=item my $promise = Travel::Status::DE::IRIS->new_p(I<%opt>)
+
+Return a promise yielding a Travel::Status::DE::IRIS instance (C<< $status >>)
+on success, or an error message (same as C<< $status->errstr >>) on failure.
+
+In addition to the arguments of B<new>, the following mandatory arguments must
+be set:
+
+=over
+
+=item B<promise> => I<promises module>
+
+Promises implementation to use for internal promises as well as B<new_p> return
+value. Recommended: Mojo::Promise(3pm).
+
+=item B<get_station> => I<get_station ref>
+
+Reference to Travel::Status::DE::IRIS::Stations::get_station().
+
+=item B<meta> => I<meta dict>
+
+The dictionary returned by Travel::Status::DE::IRIS::Stations::get_meta().
+
+=item B<user_agent> => I<user agent>
+
+User agent instance to use for asynchronous requests. The object must support
+promises (i.e., it must implement a C<< get_p >> function). Recommended:
+Mojo::UserAgent(3pm).
+
+=back
+
 =item $status->errstr
 
 In case of a fatal HTTP request or IRIS error, returns a string describing it.
-- 
cgit v1.2.3