aboutsummaryrefslogtreecommitdiff
path: root/docs/basics.rakudoc
diff options
context:
space:
mode:
authorMatias Linares <matiaslina@gmail.com>2021-01-11 22:19:00 -0300
committerMatias Linares <matiaslina@gmail.com>2021-01-11 22:19:00 -0300
commit9da9134f0b28c0e4c69537b54fd96dca3a66aaed (patch)
tree46a14da15beb95dd6f2c6b995b2dc6e7b6e94970 /docs/basics.rakudoc
parente5e5211aab9e6c579eeb6e78673015dcc03bb666 (diff)
downloadperl6-matrix-client-9da9134f0b28c0e4c69537b54fd96dca3a66aaed.tar.gz
[DOC] .pod6 -> .rakudoc extension & better layout
Diffstat (limited to 'docs/basics.rakudoc')
-rw-r--r--docs/basics.rakudoc103
1 files changed, 103 insertions, 0 deletions
diff --git a/docs/basics.rakudoc b/docs/basics.rakudoc
new file mode 100644
index 0000000..5770f4f
--- /dev/null
+++ b/docs/basics.rakudoc
@@ -0,0 +1,103 @@
+=begin pod
+
+=head1 Basic tutorial
+
+=head2 Client creation
+
+The first thing to do is create a C<Matrix::Client> pointing to
+the homeserver, and C<login> into it.
+
+ my Matrix::Client $client .= new:
+ :home-server<https://matrix.org>;
+ $client.login($username, $password);
+ say $client.access-token;
+
+In case you have an access-token, you can pass it as a parameter
+to C<new>. In this case is not necessary to call C<login>.
+
+ my Matrix::Client $client .= new:
+ :home-server<https://matrix.org>,
+ :access-token($access-token);
+
+ say $client.whoami; # @yourusername:home-server
+
+=head2 Syncing
+
+Calling sync will return a C<Matrix::Response::Sync> that abstract the
+response from the server. This structure should have all the information
+from the server like:
+
+=item presence
+=item joined rooms
+=item room invites
+
+Beware that the C<.next-batch> will have the C<:since> argument
+that is passed to the next C<sync>. If not provided, the response will have
+repeated data.
+
+ my $response = $client.sync;
+ my $since = $response.next-batch;
+
+ # print all messages
+ for $response.joined-rooms -> $room {
+ for $room.timeline.events
+ .grep(*.type eq 'm.room.message') -> $msg {
+ $msg.content<body>.say;
+ }
+ }
+
+ # Sync again with the since parameter
+ my $new-response = $client.sync(:$since);
+
+There's a C<filter> argument that you could use to filter the response. To
+see available parameters to the filter you can go L<here|https://matrix.org/docs/spec/client_server/r0.3.0.html#post-matrix-client-r0-user-userid-filter>.
+
+ # limit the messages per room to 1
+
+ # Passing a hash.
+ my $response = $client.sync(
+ sync-filter => { room => timeline => limit => 1}
+ );
+
+ # Passing a json as parameter
+ my $json-response = $client.sync(
+ sync-filter => '{"room":{"timeline":{ "limit": 1}}}'
+ );
+
+As for now, you can't send a filter_id of an already created filter.
+
+=head2 Sending events
+
+There's two ways to send events to a channel. The only event supported
+is C<m.room.message>
+
+
+=item C<.send($room-id, $message, :$type)> from C<Matrix::Client>
+=item C<.send($message, :$type)> from C<Matrix::Client::Room>
+
+Here's an example of the two:
+
+ my $room = $client.joined-rooms.first;
+ $client.send($room.id, 'Hello');
+ $room.send('hello');
+
+=head2 Async loop
+
+C<Matrix::Client> supports an async loop that can replace a C<loop { $client.sync; … }>
+since it's a common thing to do. It starts a new thread that runs that loop
+sending all the events through a C<Supplier>.
+
+ my $supply = $client.run();
+
+ react {
+ whenever $supply -> $s {
+ when $s ~~ Matrix::Response::InviteInfo {
+ say "Got an invite from {$s.room-id}";
+ }
+ when $s ~~ Matrix::Response::StateEvent {
+ say "Got a room event from {$s.room-id}";
+ }
+ }
+ }
+
+=end pod