diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 51 |
1 files changed, 48 insertions, 3 deletions
@@ -20,9 +20,9 @@ luarocks install cepis Targets **Lua 5.4**. It also runs unmodified on 5.1, 5.2, 5.3 and LuaJIT — nothing here needs anything newer, so the compatibility was free. -> The rockspec points at `git+https://git.cep.is/lua.git` with tag `v0.1.0`. +> The rockspec points at `git+https://git.cep.is/lua.git` with tag `v0.2.0`. > That repository is not published yet, so `luarocks install cepis` will not -> resolve until it is. Until then, `luarocks make cepis-0.1.0-1.rockspec` from +> resolve until it is. Until then, `luarocks make cepis-0.2.0-1.rockspec` from > a clone works. Three rocks are needed, because Lua's standard library ships neither an HTTP @@ -198,7 +198,8 @@ Every expected failure is returned as `nil, err`. `error()` is raised only for programmer mistakes — a bad option table, a wrong argument type. An error is a table carrying `kind`, `message`, and whichever of `cep`, -`status` and `retry_after` apply. `tostring(err)` yields the message. The kinds +`status`, `retry_after` and `faixa` apply. `tostring(err)` yields the message. +The kinds split by **the decision you have to make**, not by the HTTP status that caused it: @@ -231,6 +232,50 @@ else a `nil, err` boundary might hand you. answering instead of it — a captive Wi-Fi portal, a corporate proxy, an HTML error page. Useful as a diagnosis: the problem is not in your code. +### Where a missing CEP would have been + +A `not_found` may carry `err.faixa`, naming the municipality the CEP would have +belonged to. A CEP that fails is rarely a random number: it is usually someone +who knows the city and guessed the digits, and the classic guess is the `-000` +that 957 municipalities never received. + +```lua +local address, err = cepis.lookup("25845-000") + +err.kind -- "not_found" it still does not exist +err.faixa:label() -- "Areal/RJ" +err.faixa.localidade -- "Areal" +err.faixa.uf -- "RJ" +err.faixa.ibge -- "3300225" +err.faixa.cep_ini -- "25845001" +err.faixa.cep_fim -- "25849899" +err.faixa.ceps -- 118 +``` + +**This is context for an error, not an address.** The lookup failed; `faixa` +only says where the CEP would have been. Never treat it as a successful +result. + +**`cep_ini` and `cep_fim` are the smallest and largest CEP that actually +exist** in that municipality — not the range the Correios publish. For Areal +the published range starts at `25845000`, which is exactly the CEP that just +failed. + +**The range is sparse.** Areal's 118 CEPs are spread over the roughly 4,900 +numbers between `25845001` and `25849899`, so the pair is an interval, never a +list of valid CEPs — that is what `ceps` is there to say. + +`err.faixa` is `nil` whenever the CEP falls in a band no municipality owns: the +API omits the field there rather than sending null. It is also `nil` if the +block arrives malformed — a broken piece of context must not turn a clean +not-found into a parse failure, so always test it before use: + +```lua +if err.kind == cepis.NOT_FOUND and err.faixa then + print("no such CEP — did you mean one in " .. err.faixa:label() .. "?") +end +``` + ## Development Everything runs through `make`: |