Merge branch 'master' of ssh://deprecated.org:22333/var/www/cgit/perl6-matrix-client

3 files changed, 119 insertions, 0 deletions

diff --git a/docs/client.pod6 b/docs/client.pod6
index 6256cde..302e99b 100644
--- a/docs/client.pod6
+++ b/docs/client.pod6
@@ -242,4 +242,34 @@ the servers may choose to implement additional access control for this endpoint.
 
 Uploads a file to the server. It returns the MXC URI to the uploaded content.
 
+=head2 run
+
+    method run(Int :$sleep = 10, :$sync-filter? --> Supply)
+
+Returns a C<Supply> that emits L<Matrix::Response::StateEvent> with the last
+events. The C<$sleep> parameter is to sleep for that amount of seconds before
+making a L<sync> request again. The C<$sync-filter> is the same parameter that
+will be passed to L<sync> method to filter out the useful events.
+
+This can be useful to turn something like:
+
+    my $since;
+    loop {
+        $response = $client.sync(:$since);
+        $since = $response.next-batch;
+
+        for $response.joined-rooms -> $room {
+            for $room.timeline.event -> $event {
+                # Do something useful with $event
+            }
+        }
+    }
+
+into:
+
+    my $sup = $client.run();
+    react whenever $sup -> $event { 
+        # Do something useful with $event
+    }
+
 =end pod
diff --git a/docs/room.pod6 b/docs/room.pod6
new file mode 100644
index 0000000..1df8c84
--- /dev/null
+++ b/docs/room.pod6
@@ -0,0 +1,68 @@
+=begin pod
+
+=TITLE class Matrix::Client::Room
+
+=SUBTITLE Room requester
+
+    class Matrix::Client::Room does Matrix::Client::Requester {}
+
+The C<Matrix::Client::Room> is a shortcut to all the C</rooms/:id> endpoints. It
+does the role as L<Matrix::Client::Requester> so one can instantiate a Room with
+the one's access token and the room id to make requests directly to this room
+without the need for a L<Matrix::Client>.
+
+=head1 Example
+
+    my $room-id = "!pGOClvZafMH:matrix.server.com";
+    my $home-server = "https://matrix.server.com";
+    my $access-token = "…";
+
+    my Matrix::Client::Room $room .= new(
+        :$access-token,
+        :$home-server,
+        :id($room-id)
+    );
+
+    say $room.name;
+
+=head1 Methods
+
+=head2 name
+
+    method name(--> Str)
+
+Returns the name of the room. If no C<m.room.name> was emmited (i.e.: no name
+was set for this room), then an empty string is returned.
+
+=head2 send
+
+    method send(Str $body!, Str :$type? = "m.text")
+
+Sends a message to the room. It will return the C<event_id> for this message.
+
+=head2 state
+
+    multi method state(--> Seq)
+    multi method state(Str $event-type)
+
+Get the state events for the current state of a room. it will return a C<Seq>
+for every event on that room.
+
+If an C<$event-type> is passed, the return value will be the value of that
+single event.
+
+=head2 send-state
+
+    method send-state(Str:D $event-type, :$state-key = "", *%args --> Str)
+
+Send a state event to the server. The event will be overwritten if the
+C<$event-type>, C<$state-key> and the arguments all match with a state in the
+server.
+
+It will return the C<event_id> for this state change.
+
+=head2 leave
+
+    method leave()
+
+Leaves the room.
diff --git a/examples/run.p6 b/examples/run.p6
new file mode 100644
index 0000000..f78df16
--- /dev/null
+++ b/examples/run.p6
@@ -0,0 +1,21 @@
+#!/usr/bin/env perl6
+use v6;
+use lib <lib>;
+use Matrix::Client;
+
+sub MAIN(Str:D $username, Str:D $password, :$home-server = "https://matrix.deprecated.org") {
+    my Matrix::Client $client .= new: :$home-server;
+    $client.login($username, $password);
+
+    my $sup = $client.run(:sleep<5>);
+
+    signal(SIGINT).tap({
+        say "Bye";
+        $client.logout;
+        exit 0;
+    });
+
+    react whenever $sup -> $ev {
+        say $ev;
+    }
+}