From 8fe108196f3e9d6a7fc6ffda35f3943a506ea018 Mon Sep 17 00:00:00 2001 From: Matias Linares Date: Sat, 5 Jan 2019 10:40:06 -0300 Subject: Update documentation --- docs/client.pod6 | 58 ++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 14 deletions(-) (limited to 'docs/client.pod6') diff --git a/docs/client.pod6 b/docs/client.pod6 index 302e99b..ba1f2e1 100644 --- a/docs/client.pod6 +++ b/docs/client.pod6 @@ -2,25 +2,55 @@ =TITLE class Matrix::Client -=SUBTITLE Client API for Matrix +=SUBTITLE matrix.org client - class Matrix::Client does Matrix::Client::Requester {} +=head1 NAME + +Matrix::Client — Client API for Matrix.org + +=head1 SYNOPSIS + + use Matrix::Client; + + my Matrix::Client $client .= new( + :home-server, + :access-token + ); + + my $room = $client.joined-rooms.first; + $room.send("Hello from Matrix::Client"); + + + my $sync = $client.sync; + + for $response.joined-rooms -> $room { + say "Messages from {$room.name}" + for $room.timeline + .events + .grep(*.type eq 'm.room.message') -> $msg { + say $msg.content; + } + } + +=head1 DESCRIPTION + + Class Matrix::Client does Matrix::Client::Requester {} The main object in the module. The C is used to talk to a Matrix home server abstracting the HTTP requests. The client is used for example to join rooms, receive/send messages, etc. -On server errors, all methods will throw a L exception. +On server errors, all methods will throw a L exception. -=head1 Methods +=head1 METHODS =head2 new sub new(Str :$home-server, Str :$access-token?, Str :$device-id?) Creates a C pointing to a home server. If no C<$access-token> is -passed to the constructor, the client needs to call L to make authorized +passed to the constructor, the client needs to call L<#login> to make authorized calls to the API. =head2 login @@ -33,7 +63,7 @@ before the C call, it will register that C in the server invalidating any previously associated access token to this C. Otherwise the home server will auto-generate one. -On a failed login attempt, a L is raised with a code +On a failed login attempt, a L is raised with a code of C<“M_FORBIDDEN”> =head2 logout @@ -51,7 +81,7 @@ Register a B account in the home server. If C<$bind-email> is true, the server binds the email used for authentication to the Matrix ID with the ID Server. -In case there's an error with the registration, a L is raised +In case there's an error with the registration, a L is raised with one of the following Cs: =item C The desired user ID is already taken. @@ -63,7 +93,7 @@ with one of the following Cs: method profile(Str :$user-id?) Get the combined profile information for this user. With no C<$user-id> -L will provide the profile data associated with the client +L<#profile> will provide the profile data associated with the client account. It returns a C that can contains C and/or C. @@ -125,10 +155,10 @@ must be C<“online”>, C<“offline”> or C<“unavailable”>. multi method sync(Hash :$sync-filter is copy, :$since = "") Gets the client's state with the latest state on the server. It returns -a L with the initial snapshot or delta. +a L with the initial snapshot or delta. C<$since> is necessary to get the incremental deltas to the states. The C<$since> -value is retrieved from the C in the L. +value is retrieved from the C in the L. The C is the filter that will be applied to the sync. It will encode it to a JSON string if it isn't a C already. For more information about @@ -217,11 +247,11 @@ L. The room alias must be in the form -C, otherwise it will raise a L with +C, otherwise it will raise a L with the proper message and C error code. If there's no room with the C<$room-alias> in the server directory, it will -raise a L with a C code. +raise a L with a C code. =head2 add-room-alias @@ -248,8 +278,8 @@ Uploads a file to the server. It returns the MXC URI to the uploaded content. Returns a C that emits L with the last events. The C<$sleep> parameter is to sleep for that amount of seconds before -making a L request again. The C<$sync-filter> is the same parameter that -will be passed to L method to filter out the useful events. +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: -- cgit v1.2.3-70-g09d2