open.source/magic-wormhole
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

new idea on code-input helper API

Browse Source
This commit is contained in:
Brian Warner 2017-03-11 10:03:05 +01:00
parent 4bd9d3579c
commit 299f89c01f
1 changed files with 35 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/api.md
View File

@ -176,33 +176,47 @@ for consistency.
The code-entry Helper object has the following API: The code-entry Helper object has the following API:
* `d = h.get_nameplates()`: returns a Deferred that fires with a list of * `update_nameplates()`: requests an updated list of nameplates from the
(string) nameplates. These form the first portion of the wormhole code Rendezvous Server. These form the first portion of the wormhole code (e.g.
(e.g. "4" in "4-purple-sausages"). The list is requested from the server "4" in "4-purple-sausages"). Note that they are unicode strings (so "4",
when `w.input_code()` is first called, and if the response arrives before not 4). The Helper will get the response in the background, and calls to
`h.get_nameplates()` is called, it will be used without delay. All `complete_nameplate()` after the response will use the new list.
subsequent calls to `h.get_nameplates()` will provoke a fresh request to * `completions = h.complete_nameplate(prefix)`: returns (synchronously) a
the server, so hitting Tab too early won't condemn the client to using a list of suffixes for the given nameplate prefix. For example, if the server
stale list. reports nameplates 1, 12, 13, 24, and 170 are in use,
* `h.set_nameplate(nameplate)`: commit to using a specific nameplate. Once `complete_nameplate("1")` will return `["", "2", "3", "70"]`. Raises
this is called, `h.get_nameplates()` will raise an immediate exception `AlreadyClaimedNameplateError` if called after `h.claim_nameplate`.
* `completions = h.get_completions_for(prefix)`: given a prefix like "su", * `d = h.claim_nameplate(nameplate)`: accepts a string with the chosen
this returns (synchronously) a list of strings which are appropriate to nameplate. May only be called once, after which `OnlyOneNameplateError` is
raised. Returns a Deferred that fires (with None) when the nameplate's
wordlist is known (which happens after the nameplate is claimed, requiring
a roundtrip to the server).
* `completions = h.complete_words(prefix)`: return (synchronously) a list of
suffixes for the given words prefix. The possible completions depend upon
the wordlist in use for the previously-claimed nameplate, so calling this
before `claim_nameplate` will raise `MustClaimNameplateFirstError`. Given a
prefix like "su", this returns a list of strings which are appropriate to
append to the prefix (e.g. `["pportive", "rrender", "spicious"]`, for append to the prefix (e.g. `["pportive", "rrender", "spicious"]`, for
expansion into "supportive", "surrender", and "suspicious". The prefix expansion into "supportive", "surrender", and "suspicious". The prefix
should not include the nameplate, but *should* include whatever words and should not include the nameplate, but *should* include whatever words and
hyphens have been typed so far (the default wordlist uses alternate lists, hyphens have been typed so far (the default wordlist uses alternate lists,
where even numbered words have three syllables, and odd numbered words have where even numbered words have three syllables, and odd numbered words have
two, so the completions depend upon how many words are present, not just two, so the completions depend upon how many words are present, not just
the partial last word). E.g. `get_completions_for("pr")` will return the partial last word). E.g. `complete_words("pr")` will return
`["ocessor", "ovincial", "oximate"]`, while `["ocessor", "ovincial", "oximate"]`, while `complete_words("opulent-pr")`
`get_completions_for("opulent-pr")` will return `["eclude", "efer", will return `["eclude", "efer", "eshrunk", "inter", "owler"]`.
"eshrunk", "inter", "owler"]`. If the wordlist is not yet known (i.e. the Deferred from `claim_nameplate`
* `h.set_words(suffix)`: this accepts a string (e.g. "purple-sausages"), and has not yet fired), this returns an empty list. It will also return an
commits to the code. `h.set_nameplate()` must be called before this, and no empty list if the prefix is complete (the last word matches something in
other methods may be called afterwards. Calling this causes the the completion list, and there are no longer extension words), although the
`w.when_code()` Deferred or corresponding delegate callback to fire, and code may not yet be complete if there are additional words. The completions
triggers the wormhole connection process. will never include a hyphen: the UI frontend must supply these if desired.
* `h.submit_words(words)`: call this when the user is finished typing in the
code. It does not return anything, but will cause the Wormhole's
`w.when_code()` (or corresponding delegate) to fire, and triggers the
wormhole connection process. This accepts a string like "purple-sausages",
without the nameplate. It must be called after `h.claim_nameplate()` or
`MustClaimNameplateFirstError` will be raised.
The `rlcompleter` wrapper is a function that knows how to use the code-entry The `rlcompleter` wrapper is a function that knows how to use the code-entry
helper to do tab completion of wormhole codes: helper to do tab completion of wormhole codes: