diff options
author | Hubert Chathi <hubert@uhoreg.ca> | 2020-09-17 23:03:28 -0400 |
---|---|---|
committer | Hubert Chathi <hubert@uhoreg.ca> | 2020-09-18 08:48:53 -0400 |
commit | 13d238f798b570bddf79aa117c294fe1e4414881 (patch) | |
tree | a992b91d3e57976f27e9845afb683bad8e13c4af | |
parent | doc improvements (diff) |
update example and tutorials to new API
-rw-r--r-- | examples/history.exs | 9 | ||||
-rw-r--r-- | tutorial_echo.md | 26 | ||||
-rw-r--r-- | tutorial_welcome.md | 3 |
3 files changed, 25 insertions, 13 deletions
diff --git a/examples/history.exs b/examples/history.exs index 4b1488a..7e5c8a5 100644 --- a/examples/history.exs +++ b/examples/history.exs @@ -4,10 +4,13 @@ [access_token, room_id, limitStr] = System.argv {limit, _} = Integer.parse(limitStr) -client = %Polyjuice.Client{ - base_url: "http://localhost:8008", +{:ok, client_pid} = Polyjuice.Client.start_link( + "http://localhost:8008", access_token: access_token, -} + sync: false +) + +client = Polyjuice.Client.get_client(client_pid) # Get a minimal sync that just contains room messages. We need to get a sync so # we have a previous batch. diff --git a/tutorial_echo.md b/tutorial_echo.md index 27e7565..f1e7857 100644 --- a/tutorial_echo.md +++ b/tutorial_echo.md @@ -10,31 +10,39 @@ produce a working bot. ## Creating a client -We begin by starting a client: +We begin by starting a client process and obtaining a struct: - iex> client = Polyjuice.Client.start_link( + iex> {:ok, pid} = Polyjuice.Client.start_link( ...> "http://localhost:8008", ...> access_token: "access_token", ...> user_id: "@echobot:localhost", ...> storage: Polyjuice.Client.Storage.Ets.open(), ...> handler: self() ...> ) + iex> client = Polyjuice.Client.get_client(pid) The first parameter is the base URL to the homeserver that the bot will be using. `access_token` is an access token for the bot to use. The access token can be obtained by using `curl` to call the [login](https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-login) -endpoint on the homeserver, or by retrieving it from an already logged-in -client. `user_id` is the Matrix user ID of the bot. And `storage` provides -some persistent storage for the client library. In the example above, it is -using the [Erlang Term Storage](http://erlang.org/doc/man/ets.html), which does -not actually provide any persistence. This means that, for example, the bot -will forget where it was in the sync, and so it may produce duplicate responses -when it is restarted. If you wish to have persistence, you can use the +endpoint on the homeserver, by retrieving it from an already logged-in client, +or by using `mix polyjuice.login`. `user_id` is the Matrix user ID of the bot. +And `storage` provides some persistent storage for the client library. In the +example above, it is using the [Erlang Term +Storage](http://erlang.org/doc/man/ets.html), which does not actually provide +any persistence. This means that, for example, the bot will forget where it +was in the sync, and so it may produce duplicate responses when it is +restarted. If you wish to have persistence, you can use the `Polyjuice.Client.Storage.Dets` module instead, which will persist the term storage to disk. To use it, call `Polyjuice.Client.Storage.Dets.open/1` with the name of a file to use for storage. +If you use `Polyjuice.Client.Storage.Dets`, then you only need to specify he +`access_token` and `user_id` the first time the client is run. This +information will be stored in dets and will be retrieved on subsequent runs. +Alternatively, you can use `mix polyjuice.login` to log in and store the access +token and user ID. + The `handler` parameter tells the client how client events (such as Matrix messages) should be handled. By passing a PID (`self()`), Erlang messages will be sent to the given PID. diff --git a/tutorial_welcome.md b/tutorial_welcome.md index 3d91b0c..ffbf8f8 100644 --- a/tutorial_welcome.md +++ b/tutorial_welcome.md @@ -27,7 +27,7 @@ certain types of events, it will only include those event types. If we give it an empty list, it will give none of the events. iex> alias Polyjuice.Client.Filter - iex> client = Polyjuice.Client.start_link( + iex> {:ok, pid} = Polyjuice.Client.start_link( ...> "http://localhost:8008", ...> access_token: "access_token", ...> user_id: "@echobot:localhost", @@ -38,6 +38,7 @@ an empty list, it will give none of the events. ...> |> Filter.include_state_types(["m.room.member"]) ...> |> Filter.include_timeline_types(["m.room.member"]) ...> ) + iex> client = Polyjuice.Client.get_client(pid) Note that we include `m.room.member` events in both `state` and `timeline`. This is because these refer to different sections of the sync response, rather |