1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
//! Zig client for the public CEP API at [cep.is](https://cep.is). Official
//! Correios data (DNE), refreshed every two weeks.
//!
//! Zig has no ambient allocator and, since 0.16, no ambient I/O either, so
//! there is no module-level `lookup`: everything goes through a `Client` you
//! build with both. That is one extra line and it is the honest one.
//!
//! ```zig
//! const std = @import("std");
//! const cepis = @import("cepis");
//!
//! pub fn main() !void {
//! var debug: std.heap.DebugAllocator(.{}) = .init;
//! defer _ = debug.deinit();
//! const gpa = debug.allocator();
//!
//! var threaded: std.Io.Threaded = .init(gpa, .{});
//! defer threaded.deinit();
//!
//! var client: cepis.Client = try .init(gpa, threaded.io(), .{});
//! defer client.deinit();
//!
//! var address = try client.lookup("01001-000", .{});
//! defer address.deinit(gpa);
//!
//! std.debug.print("{s} {s}\n", .{ address.localidade, address.uf });
//! }
//! ```
//!
//! Pointing at a local instance (the API repo brings one up with `just up`)
//! is a matter of `base_url`:
//!
//! ```zig
//! var client: cepis.Client = try .init(gpa, io, .{ .base_url = "http://localhost:8080" });
//! ```
//!
//! Errors are one set, split by decision — whether retrying helps or not:
//!
//! ```zig
//! var diag: cepis.Diagnostics = .{};
//! const address = client.lookup(cep_from_form, .{ .diagnostics = &diag }) catch |err| switch (err) {
//! error.NotFound => return askForAnotherCep(),
//! else => if (cepis.isRetriable(err)) return reschedule() else return err,
//! };
//! ```
//!
//! After `error.NotFound`, `diag.faixa()` may name the municipality the CEP
//! would have belonged to. It is context for the failure and never an address —
//! see `Faixa`.
//!
//! Note on field names: the API surface is English, but the **data fields keep
//! the API's own Portuguese names** (`logradouro`, `bairro`, `localidade`).
//! What you read in the JSON is what you access on the value.
//!
//! Every value this library returns owns its memory and has a `deinit` taking
//! the allocator the `Client` was built with. Each type documents exactly what
//! it owns.
const client = @import("client.zig");
const errors = @import("errors.zig");
const model = @import("model.zig");
pub const Client = client.Client;
pub const Config = client.Config;
pub const CallOptions = client.CallOptions;
pub const InitError = client.InitError;
pub const normalizeCep = client.normalizeCep;
pub const freeAddresses = client.freeAddresses;
pub const default_url = client.default_url;
pub const default_user_agent = client.default_user_agent;
pub const max_batch = client.max_batch;
pub const retriable_status = client.retriable_status;
/// The version of this library, as sent in the `User-Agent`.
pub const version = client.version;
pub const Error = errors.Error;
pub const CepisError = errors.CepisError;
pub const Diagnostics = errors.Diagnostics;
pub const isRetriable = errors.isRetriable;
pub const Address = model.Address;
pub const Faixa = model.Faixa;
pub const Geo = model.Geo;
pub const Health = model.Health;
test {
@import("std").testing.refAllDecls(@This());
_ = @import("csv.zig");
_ = @import("retry.zig");
_ = client;
_ = errors;
_ = model;
}
|