diff options
| -rw-r--r-- | bin/gen-doc.p6 | 46 | ||||
| -rw-r--r-- | docs/client.pod6 | 58 | ||||
| -rw-r--r-- | docs/requester.pod6 | 66 | ||||
| -rw-r--r-- | docs/responses.pod6 | 122 | ||||
| -rw-r--r-- | docs/usage.pod6 | 41 | ||||
| -rw-r--r-- | docs/x-matrix-response.pod6 | 23 | ||||
| -rw-r--r-- | templates/index.mustache | 82 | ||||
| -rw-r--r-- | templates/main.mustache | 69 |
8 files changed, 493 insertions, 14 deletions
diff --git a/bin/gen-doc.p6 b/bin/gen-doc.p6 new file mode 100644 index 0000000..1e41aa8 --- /dev/null +++ b/bin/gen-doc.p6 @@ -0,0 +1,46 @@ +use v6; +use Pygments; + +my %*POD2HTML-CALLBACKS; +%*POD2HTML-CALLBACKS<code> = sub (:$node, :&default) { + Pygments.highlight($node.contents.join('\n'), "perl6", + :style(Pygments.style('emacs'))) +}; + +use Pod::To::HTML; +use Pod::Load; +use Template::Mustache; + +sub git-version { + run('git', 'tag', '-l', :out).out.lines.first +} +sub pods { dir('./docs', :test( *.IO.extension eq 'pod'|'pod6' )) } + +my $sidebar = pods.sort.map( + -> $p { + my $f = $p.IO.extension('html').basename; + "<li><a href='$f'>{$f.split('.').first.tc}</a></li>" + }); + +sub MAIN(:o(:$output-dir)?) { + $output-dir.IO.add('index.html').spurt( + Template::Mustache.render('./templates/index.mustache'.IO.slurp, + {version => git-version()})); + + pods.map( + -> $pod { + say "Generating html for $pod"; + next if $pod.IO.extension ne 'pod'|'pod6'; + my $html = pod2html( + load($pod.IO), + :templates<templates> + ); + + my $filename = $pod.IO.extension('html'); + my $output = $output-dir.defined ?? + $output-dir.IO.add($filename.basename) !! + $filename; + + spurt $output, $html; + }); +} 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<https://matrix.org>, + :access-token<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<body>; + } + } + +=head1 DESCRIPTION + + Class Matrix::Client does Matrix::Client::Requester {} The main object in the module. The C<Matrix::Client> 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<X::Matrix::Response> exception. +On server errors, all methods will throw a L<X::Matrix::Response|x-matrix-response.html> exception. -=head1 Methods +=head1 METHODS =head2 new sub new(Str :$home-server, Str :$access-token?, Str :$device-id?) Creates a C<Matrix::Client> pointing to a home server. If no C<$access-token> is -passed to the constructor, the client needs to call L<login> 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<login> call, it will register that C<device-id> in the server invalidating any previously associated access token to this C<device-id>. Otherwise the home server will auto-generate one. -On a failed login attempt, a L<X::Matrix::Response> is raised with a code +On a failed login attempt, a L<X::Matrix::Response|x-matrix-response.html> is raised with a code of C<“M_FORBIDDEN”> =head2 logout @@ -51,7 +81,7 @@ Register a B<user> 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<X::Matrix::Response> is raised +In case there's an error with the registration, a L<X::Matrix::Response|x-matrix-response.html> is raised with one of the following C<code>s: =item C<M_USER_IN_USE> The desired user ID is already taken. @@ -63,7 +93,7 @@ with one of the following C<code>s: method profile(Str :$user-id?) Get the combined profile information for this user. With no C<$user-id> -L<profile> 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<Hash> that can contains C<avatar_url> and/or C<displayname>. @@ -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<Matrix::Response::Sync> with the initial snapshot or delta. +a L<Matrix::Response::Sync|responses.html#Sync> 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<next-batch> in the L<Matrix::Response::Sync>. +value is retrieved from the C<next-batch> in the L<Matrix::Response::Sync|responses.html#sync>. The C<sync-filter> is the filter that will be applied to the sync. It will encode it to a JSON string if it isn't a C<Str> already. For more information about @@ -217,11 +247,11 @@ L<Room events|https://matrix.org/docs/spec/client_server/r0.3.0.html#room-events method get-room-id($room-alias) Get the room id for an C<$room-alias>. The room alias must be in the form -C<localname:domain>, otherwise it will raise a L<X::Matrix::Response> with +C<localname:domain>, otherwise it will raise a L<X::Matrix::Response|x-matrix-response.html> with the proper message and C<M_UNKNOWN> error code. If there's no room with the C<$room-alias> in the server directory, it will -raise a L<L::Matrix::Response> with a C<M_NOT_FOUND> code. +raise a L<X::Matrix::Response|x-matrix-response.html> with a C<M_NOT_FOUND> 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<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. +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: diff --git a/docs/requester.pod6 b/docs/requester.pod6 new file mode 100644 index 0000000..6710948 --- /dev/null +++ b/docs/requester.pod6 @@ -0,0 +1,66 @@ +=begin pod + +=TITLE role Matrix::Client::Requester + +=SUBTITLE Role for HTTP requests + + + role Matrix::Client::Requester { } + +Role that gives the base API for objects that interacts to the matrix server. The +attributes that can be set can be: + +=head1 Attributes + +=head2 Str home-server + +The url of the home-server. + +=head2 Str access-token + +access token to make authorized calls to the matrix server. + +=head2 Str url-prefix + +Prefix to all the paths used in the methods. + +=head1 Methods + +=head2 get + + method get(Str $path, :$media = False, *%data) + +Do a GET to C<$path>. + +All the C<*%data> is used to build the query params for the url. + +=head2 post + + multi method post(Str $path, Str $params, :$media = False) + multi method post(Str $path, :$media = False, *%params) + +Do a POST to C<$path> with C<$params> as JSON body. With the +named C<*%params>, those are parameters are converted into JSON. + +=head2 post-bin + + method post-bin(Str $path, Buf $buf, :$content-type) + +Do a POST to C<$path> with binary data in the body. + +=head2 put + + +multi method put(Str $path, Str $params) +multi method put(Str $path, *%params) + +Do a PUT to C<$path> with C<$params> as JSON body. With the named +C<*%params>, those parameters are converted into JSON. + +=head2 delete + + method delete(Str $path) + +Do a DELETE to C<$path>. + +=end pod
\ No newline at end of file diff --git a/docs/responses.pod6 b/docs/responses.pod6 new file mode 100644 index 0000000..7515d39 --- /dev/null +++ b/docs/responses.pod6 @@ -0,0 +1,122 @@ +=begin pod + +=TITLE Matrix Responses + +=SUBTITLE Wrappers for HTTP responses + +=head1 Event + + + class Matrix::Response::Event { } + +Common contents of a response. + +=head2 Mapped keys + +=item content +=item type + +=head1 RoomEvent + + + class Matrix::Response::RoomEvent is Matrix::Response::Event { } + +A single event for a room + +=head2 Mapped keys + +=item sender +=item origin_server_ts +=item event_id +=item room_id + +=head2 Methods + +=head3 id + + method id + +Returns the event_id + +=head3 timestamp + + method timestamp + +Returns the origin_server_ts + +=head3 room-id + + method room-id + +returns the room_id + + +=head1 StateEvent + + + class Matrix::Response::StateEvent is Matrix::Response::RoomEvent { } + +=head2 Mapped keys + +=item C<prev_content> +=item C<state_key> + +=head1 Timeline + + + class Matrix::Response::Timeline { } + +=head2 Mapped keys + +=item events — Return a list of L<Matrix::Response::Event|#Event> +=item limited +=item prev-batch + + +=head1 RoomInfo + + + class Matrix::Response::RoomInfo { } + +=head2 Mapped keys + +=item room-id — Str with the room id +=item state — List of L<Matrix::Response::Event|#Event> +=item Timeine — A L<Matrix::Response::Timeline|#Timeline> + +=head1 InviteInfo + + + class Matrix::Response::InviteInfo { } + +=head2 Mapped keys + +=item room-id — Str with the room id +=item events — List of L<Matrix::Response::Event|#Event> + +=head1 Sync + + + class Matrix::Response::Sync { } + +=head2 Mapped keys + +=item next-batch — Str with the hash for the next sync batch +=item presence — List of L<Matrix::Response::Event|#Event> +=item joined-rooms — List of L<Matrix::Response::RoomInfo|#RoomInfo> +=item invited-rooms — List of L<Matrix::Response::InviteInfo|#InviteInfo> + + +=head1 Presence + + + class Matrix::Response::Presence { } + +=head2 Mapped keys + +=item presence +=item last-active-ago +=item status-message +=item currently-active + +=end pod
\ No newline at end of file diff --git a/docs/usage.pod6 b/docs/usage.pod6 new file mode 100644 index 0000000..03454d1 --- /dev/null +++ b/docs/usage.pod6 @@ -0,0 +1,41 @@ +=begin pod +=head1 Before we begin… + +This guide will be a port from L<this guide|https://matrix.org/docs/guides/usage-of-the-matrix-js-sdk> +by the Matrix team. + +=head1 Making a Matrix Client + +Let's explore how we would make a very simple Matrix client, with the only ability to perform an initial +sync, and get the member list and the timeline for rooms of our choice. + +This guide will cover: + +=item Login +=item Simple syncing +=item Listening for timeline events +=item Sending messages to rooms +=item How to respond to specific messages + +=head2 Preparing the project + +Before we start, make sure you have perl6 and zef installed. My sugestion is to install +L<rakudobrew|https://github.com/tadzik/rakudobrew> and follow the instructions. + +Once you're ready, the first thing is to install +L<Matrix::Client|https://github.com/matiaslina/perl6-matrix-client> with C<zef> + +=begin code +zef install Matrix::Client +=end code + +And now we can include it on our source exaclty as expected. + +=begin code +use Matrix::Client; +=end code + +=head2 Login with an access token + + +=end pod
\ No newline at end of file diff --git a/docs/x-matrix-response.pod6 b/docs/x-matrix-response.pod6 new file mode 100644 index 0000000..d93c263 --- /dev/null +++ b/docs/x-matrix-response.pod6 @@ -0,0 +1,23 @@ +=begin pod + +=TITLE X::Matrix::Response + +=SUBTITLE Error querying the matrix server + + + class X::Matrix::Response is Exception {} + +Error class when the matrix server returns an error code (4XX). + +=head1 METHODS + +=head2 code + +Returns the HTTP error code. + +=head2 error + +Returns a C<Str> with the matrix error. A full list of error codes can be +found in the L<matrix spec|https://matrix.org/docs/spec/client_server/r0.4.0.html#api-standards>. + +=end pod
\ No newline at end of file diff --git a/templates/index.mustache b/templates/index.mustache new file mode 100644 index 0000000..c3eec31 --- /dev/null +++ b/templates/index.mustache @@ -0,0 +1,82 @@ +<!doctype html> +<html lang="{{ lang }}"> + <head> + <title>Matrix::Client</title> + <meta charset="UTF-8" /> + <link rel="stylesheet" href="https://code.cdn.mozilla.net/fonts/fira.css"> + <style> + kbd { font-family: "Droid Sans Mono", "Luxi Mono", "Inconsolata", monospace } + samp { font-family: "Terminus", "Courier", "Lucida Console", monospace } + u { text-decoration: none } + .nested { + margin-left: 3em; + } + aside, u { opacity: 0.7 } + a[id^="fn-"]:target { background: #ff0 } + </style> + <link rel="stylesheet" href="https://deprecated.org/raw/s/styles.css"> + </head> + <body class="pod"> + <div id="___top"></div> + <div id="wrapper"> + <header class="header"> + <a class="box" href="/"> + <img src="https://deprecated.org/raw/i/perl6-matrix@100.png" alt='perl6-matrix' /> + <h1 id="title"> + Perl 6 Matrix Client + </h1> + </a> + + </header> + <aside class="menu"> + <nav> + <h3>Download</h3> + <p>Current version <b>{{ version }}</b></p> + <p>Get Matrix::Client from <a href="https://github.com/matiaslina/perl6-matrix-client">Github</a>, or install it with <a href="https://github.com/ugexe/zef">zef</a></p> + <div class="highlight"> + <pre style='font-size: 12px; '>zef install Matrix::Client</pre> + </div> + + <nav> + <h3>Documentation</h3> + <ul> + <li><a href="basics.html">Basics</a></li> + <li><a href="usage.html">Usage</a></li> + <li>API</li> + <ul> + <li><a href="client.html">Matrix::Client</a></li> + <li><a href="responses.html">Matrix::Responses</a></li> + <li><a href="room.html">Matrix::Client::Room</a></li> + <li><a href="x-matrix-response.html">X::Matrix</a></li> + <li><a href="requester.html">Matrix::Requester</a></li> + </ul> + </ul> + </nav> + </aside> + + <div class="content"> + <h1 class='title'>Welcome!</h1> + This is the home of Matrix::Client. It is a perl 6 client to interact with the + <a href="https://matrix.org">matrix</a> protocol. This library aims to deliver a full + coverage of the client-server api. + + Read more in the <a href="basics.html">Basic tutorial</a>. + + <h2>Contribute</h2> + <p>Development takes place on <a href="https://github.com/matiaslina/perl6-matrix-client">Github</a> where the repository, tickets and pull requests can be viewed.</p> + <p>If you want to make a contribution, found a bug, or just want to propose a feature, + just open a ticket on github. You can also send an e-mail to me or get in touch through matrix.</p> + + <h2>Author</h2> + <p>Matrix::Client is developed by <b>Matias Linares</b>. You can send an e-mail to + <i>matias AT deprecated DOT org</i> or send a message to + <a href="https://matrix.to/#/@matias:matrix.deprecated.org"><i>@matias:matrix.deprecated.org</i></a></p> + </div> + <footer> + + <a href="https://github.com/matiaslina/perl6-matrix-client"> + <img width=40 src="https://cdn1.iconfinder.com/data/icons/smallicons-logotypes/32/github-512.png" /> + </a> + </footer> + </body> +</html> diff --git a/templates/main.mustache b/templates/main.mustache new file mode 100644 index 0000000..78501f3 --- /dev/null +++ b/templates/main.mustache @@ -0,0 +1,69 @@ +<!doctype html> +<html lang="{{ lang }}"> + <head> + <title>{{{ title }}}</title> + <meta charset="UTF-8" /> + <link rel="stylesheet" href="https://code.cdn.mozilla.net/fonts/fira.css"> + <style> + kbd { font-family: "Droid Sans Mono", "Luxi Mono", "Inconsolata", monospace } + samp { font-family: "Terminus", "Courier", "Lucida Console", monospace } + u { text-decoration: none } + .nested { + margin-left: 3em; + } + aside, u { opacity: 0.7 } + a[id^="fn-"]:target { background: #ff0 } + </style> + <link rel="stylesheet" href="https://deprecated.org/raw/s/styles.css"> + {{# metadata }}{{{ metadata }}}{{/ metadata }} + {{{ head }}} + </head> + <body class="pod"> + <div id="___top"></div> + <div id="wrapper"> + <header class="header"> + <a class="box" href="/"> + <img src="https://deprecated.org/raw/i/perl6-matrix@100.png" alt='perl6-matrix' /> + <h1 id="title"> + Perl 6 Matrix Client + </h1> + </a> + </header> + + <aside class="menu"> + <nav><h3><a href="index.html">Home</a></h3></nav> + {{# toc }}{{{ toc }}}{{/ toc }} + <nav> + <h3>See also</h3> + <ul> + <li><a href="basics.html">Basics</a></li> + <li><a href="usage.html">Usage</a></li> + <li><b><u>API</u></b></li> + <ul> + <li><a href="client.html">Matrix::Client</a></li> + <li><a href="responses.html">Matrix::Responses</a></li> + <li><a href="room.html">Matrix::Client::Room</a></li> + <li><a href="x-matrix-response.html">X::Matrix</a></li> + <li><a href="requester.html">Matrix::Requester</a></li> + </ul> + </ul> + </nav> + </aside> + + <div class="content"> + {{# title }}<h1 class='title'>{{{ title }}}</h1>{{/ title }} + {{# subtitle }}<p class='subtitle'>{{{ subtitle }}}</p>{{/ subtitle }} + <div class="pod-body{{^ toc }} no-toc{{/ toc }}"> + {{# body }}{{{ . }}}{{/ body }} + </div> + {{# footnotes }}{{{ footnotes }}}{{/ footnotes }} + {{{ footer }}} + </div> + <footer> + <a href="https://github.com/matiaslina/perl6-matrix-client"> + <img width=40 src="https://cdn1.iconfinder.com/data/icons/smallicons-logotypes/32/github-512.png" /> + </a> + </footer> + </div> + </body> +</html> |