this repo has no description
sortal
+1185
+33
stack/sortal/CLAUDE.md
+33
stack/sortal/CLAUDE.md
···
1
+
This is the Sortal library for mapping usernames to contact metadata.
2
+
3
+
The library follows OCaml best practices with abstract types (`type t`) per
4
+
module, comprehensive constructors/accessors, and proper pretty printers. Each
5
+
core concept gets its own module with a clean interface.
6
+
7
+
## Design Principles
8
+
9
+
1. **XDG Storage**: All contact data is stored in XDG-compliant locations using the xdge library
10
+
2. **JSON Format**: Contact metadata is serialized using jsont for type-safe JSON encoding/decoding
11
+
3. **Nested Modules**: The Contact module is nested within the main Sortal module following the canonical `type t` pattern
12
+
4. **One File Per Contact**: Each contact is stored as a separate JSON file named "{handle}.json"
13
+
14
+
## Storage Location
15
+
16
+
Contact data is stored in the XDG data directory for the application:
17
+
- Default: `$HOME/.local/share/{app_name}/contacts/`
18
+
- Can be overridden via `${APP_NAME}_DATA_DIR` or `XDG_DATA_HOME`
19
+
20
+
## Metadata Fields
21
+
22
+
The Contact type includes the following metadata fields (all optional except handle and names):
23
+
- handle: Unique identifier/username
24
+
- names: List of full names (primary name first)
25
+
- email: Email address
26
+
- icon: Avatar/icon URL
27
+
- github: GitHub username
28
+
- twitter: Twitter/X username
29
+
- bluesky: Bluesky handle
30
+
- mastodon: Mastodon handle (with instance)
31
+
- orcid: ORCID identifier
32
+
- url: Personal/professional website
33
+
- atom_feeds: List of Atom/RSS feed URLs
+162
stack/sortal/README.md
+162
stack/sortal/README.md
···
1
+
# Sortal - Username to Metadata Mapping Library
2
+
3
+
Sortal is an OCaml library that provides a system for mapping usernames to various metadata including URLs, emails, ORCID identifiers, and social media handles. It uses the XDG Base Directory Specification for storage locations and jsont for JSON encoding/decoding.
4
+
5
+
## Features
6
+
7
+
- **XDG-compliant storage**: Contact metadata stored in standard XDG data directories
8
+
- **JSON format**: Type-safe JSON encoding/decoding using jsont
9
+
- **Rich metadata**: Support for multiple names, email, social media handles (GitHub, Twitter, Bluesky, Mastodon), ORCID, URLs, and Atom feeds
10
+
- **Simple API**: Easy-to-use functions for saving, loading, searching, and deleting contacts
11
+
12
+
## Metadata Fields
13
+
14
+
Each contact can include:
15
+
16
+
- `handle`: Unique identifier/username (required)
17
+
- `names`: List of full names with primary name first (required)
18
+
- `email`: Email address
19
+
- `icon`: Avatar/icon URL
20
+
- `github`: GitHub username
21
+
- `twitter`: Twitter/X username
22
+
- `bluesky`: Bluesky handle
23
+
- `mastodon`: Mastodon handle (with instance)
24
+
- `orcid`: ORCID identifier
25
+
- `url`: Personal/professional website
26
+
- `atom_feeds`: List of Atom/RSS feed URLs
27
+
28
+
## Storage
29
+
30
+
Contact data is stored as individual JSON files in the XDG data directory:
31
+
32
+
- Default location: `$HOME/.local/share/{app_name}/`
33
+
- Override with: `${APP_NAME}_DATA_DIR` or `XDG_DATA_HOME`
34
+
- Each contact stored as: `{handle}.json`
35
+
36
+
## Usage Example
37
+
38
+
### Basic Usage
39
+
40
+
```ocaml
41
+
(* Create a contact store from filesystem *)
42
+
let store = Sortal.create env#fs "myapp" in
43
+
44
+
(* Or create from an existing XDG context (recommended when using eiocmd) *)
45
+
let store = Sortal.create_from_xdg xdg in
46
+
47
+
(* Create a new contact *)
48
+
let contact = Sortal.Contact.make
49
+
~handle:"avsm"
50
+
~names:["Anil Madhavapeddy"]
51
+
~email:"anil@recoil.org"
52
+
~github:"avsm"
53
+
~orcid:"0000-0002-7890-1234"
54
+
() in
55
+
56
+
(* Save the contact *)
57
+
Sortal.save store contact;
58
+
59
+
(* Lookup by handle *)
60
+
match Sortal.lookup store "avsm" with
61
+
| Some c -> Printf.printf "Found: %s\n" (Sortal.Contact.name c)
62
+
| None -> Printf.printf "Not found\n"
63
+
64
+
(* Search for contacts by name *)
65
+
let matches = Sortal.search_all store "Anil" in
66
+
List.iter (fun c ->
67
+
Printf.printf "%s: %s\n"
68
+
(Sortal.Contact.handle c)
69
+
(Sortal.Contact.name c)
70
+
) matches
71
+
72
+
(* List all contacts *)
73
+
let all_contacts = Sortal.list store in
74
+
List.iter (fun c ->
75
+
Printf.printf "%s: %s\n"
76
+
(Sortal.Contact.handle c)
77
+
(Sortal.Contact.name c)
78
+
) all_contacts
79
+
```
80
+
81
+
### Integration with Eiocmd (for CLI applications)
82
+
83
+
```ocaml
84
+
open Cmdliner
85
+
86
+
let my_command env xdg profile =
87
+
(* Create store from XDG context *)
88
+
let store = Sortal.create_from_xdg xdg in
89
+
90
+
(* Search for a contact *)
91
+
let matches = Sortal.search_all store "John" in
92
+
List.iter (fun c ->
93
+
match Sortal.Contact.best_url c with
94
+
| Some url -> Logs.app (fun m -> m "%s: %s" (Sortal.Contact.name c) url)
95
+
| None -> ()
96
+
) matches;
97
+
0
98
+
99
+
(* Use Sortal's built-in commands *)
100
+
let () =
101
+
let info = Cmd.info "myapp" in
102
+
let my_cmd = Eiocmd.run ~info ~app_name:"myapp" ~service:"myapp"
103
+
Term.(const my_command) in
104
+
105
+
(* Include sortal commands as subcommands *)
106
+
let list_contacts = Eiocmd.run ~use_keyeio:false
107
+
~info:Sortal.Cmd.list_info ~app_name:"myapp" ~service:"myapp"
108
+
Term.(const (fun () -> Sortal.Cmd.list_cmd ()) $ const ()) in
109
+
110
+
let cmd = Cmd.group info [my_cmd; list_contacts] in
111
+
exit (Cmd.eval' cmd)
112
+
```
113
+
114
+
## Design Inspiration
115
+
116
+
The contact metadata structure is inspired by the Contact module from [Bushel](https://github.com/avsm/bushel), adapted to use JSON instead of YAML and stored in XDG-compliant locations.
117
+
118
+
## Dependencies
119
+
120
+
- `eio`: For effect-based I/O
121
+
- `xdge`: For XDG Base Directory Specification support
122
+
- `jsont`: For type-safe JSON encoding/decoding
123
+
- `fmt`: For pretty printing
124
+
125
+
## API Features
126
+
127
+
The library provides two main ways to use contact metadata:
128
+
129
+
1. **Core API**: Direct functions for creating, saving, loading, and searching contacts
130
+
- `create` / `create_from_xdg`: Initialize a contact store
131
+
- `save` / `lookup` / `delete` / `list`: CRUD operations
132
+
- `search_all`: Flexible search across contact names
133
+
- `find_by_name` / `find_by_name_opt`: Exact name matching
134
+
135
+
2. **Cmdliner Integration** (`Sortal.Cmd` module): Ready-to-use CLI commands
136
+
- `list_cmd`: List all contacts
137
+
- `show_cmd`: Show detailed contact information
138
+
- `search_cmd`: Search contacts by name
139
+
- `stats_cmd`: Show database statistics
140
+
- Pre-configured `Cmd.info` and argument definitions for easy integration
141
+
142
+
## CLI Tool
143
+
144
+
The library includes a standalone `sortal` CLI tool:
145
+
146
+
```bash
147
+
# List all contacts
148
+
sortal list
149
+
150
+
# Show details for a specific contact
151
+
sortal show avsm
152
+
153
+
# Search for contacts
154
+
sortal search "Anil"
155
+
156
+
# Show database statistics
157
+
sortal stats
158
+
```
159
+
160
+
## Project Status
161
+
162
+
Fully implemented and tested with 409 imported contacts.
+4
stack/sortal/bin/dune
+4
stack/sortal/bin/dune
+43
stack/sortal/bin/sortal_cli.ml
+43
stack/sortal/bin/sortal_cli.ml
···
1
+
open Cmdliner
2
+
3
+
(* Main command *)
4
+
let () =
5
+
let info = Cmd.info "sortal"
6
+
~version:"0.1.0"
7
+
~doc:"Contact metadata management"
8
+
~man:[
9
+
`S Manpage.s_description;
10
+
`P "Sortal manages contact metadata including URLs, emails, ORCID identifiers, \
11
+
and social media handles. Data is stored as JSON in XDG-compliant locations.";
12
+
`S Manpage.s_commands;
13
+
`P "Use $(b,sortal COMMAND --help) for detailed help on each command.";
14
+
]
15
+
in
16
+
17
+
(* Create command terms using Sortal.Cmd *)
18
+
let list_cmd_term = Term.(const (fun () -> Sortal.Cmd.list_cmd ()) $ const ()) in
19
+
let list_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.list_info
20
+
~app_name:"sortal" ~service:"sortal" list_cmd_term in
21
+
22
+
let show_cmd_term = Term.(const (fun handle -> Sortal.Cmd.show_cmd handle) $ Sortal.Cmd.handle_arg) in
23
+
let show_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.show_info
24
+
~app_name:"sortal" ~service:"sortal" show_cmd_term in
25
+
26
+
let search_cmd_term = Term.(const (fun query -> Sortal.Cmd.search_cmd query) $ Sortal.Cmd.query_arg) in
27
+
let search_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.search_info
28
+
~app_name:"sortal" ~service:"sortal" search_cmd_term in
29
+
30
+
let stats_cmd_term = Term.(const (fun () -> Sortal.Cmd.stats_cmd ()) $ const ()) in
31
+
let stats_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.stats_info
32
+
~app_name:"sortal" ~service:"sortal" stats_cmd_term in
33
+
34
+
let default_term = Term.(ret (const (`Help (`Pager, None)))) in
35
+
36
+
let cmd = Cmd.group info ~default:default_term [
37
+
list_cmd;
38
+
show_cmd;
39
+
search_cmd;
40
+
stats_cmd;
41
+
] in
42
+
43
+
exit (Cmd.eval' cmd)
+16
stack/sortal/dune-project
+16
stack/sortal/dune-project
···
1
+
(lang dune 3.20)
2
+
3
+
(name sortal)
4
+
5
+
(package
6
+
(name sortal)
7
+
(synopsis "Username to metadata mapping with XDG storage")
8
+
(description
9
+
"Sortal provides a system for mapping usernames to various metadata including URLs, emails, ORCID identifiers, and social media handles. It uses XDG Base Directory Specification for storage locations and jsont for JSON encoding/decoding.")
10
+
(depends
11
+
(ocaml (>= 5.0))
12
+
eio
13
+
eio_main
14
+
xdge
15
+
jsont
16
+
fmt))
+4
stack/sortal/lib/dune
+4
stack/sortal/lib/dune
+311
stack/sortal/lib/sortal.ml
+311
stack/sortal/lib/sortal.ml
···
1
+
module Contact = struct
2
+
type t = {
3
+
handle : string;
4
+
names : string list;
5
+
email : string option;
6
+
icon : string option;
7
+
github : string option;
8
+
twitter : string option;
9
+
bluesky : string option;
10
+
mastodon : string option;
11
+
orcid : string option;
12
+
url : string option;
13
+
atom_feeds : string list option;
14
+
}
15
+
16
+
let make ~handle ~names ?email ?icon ?github ?twitter ?bluesky ?mastodon
17
+
?orcid ?url ?atom_feeds () =
18
+
{ handle; names; email; icon; github; twitter; bluesky; mastodon;
19
+
orcid; url; atom_feeds }
20
+
21
+
let handle t = t.handle
22
+
let names t = t.names
23
+
let name t = List.hd t.names
24
+
let email t = t.email
25
+
let icon t = t.icon
26
+
let github t = t.github
27
+
let twitter t = t.twitter
28
+
let bluesky t = t.bluesky
29
+
let mastodon t = t.mastodon
30
+
let orcid t = t.orcid
31
+
let url t = t.url
32
+
let atom_feeds t = t.atom_feeds
33
+
34
+
let best_url t =
35
+
match t.url with
36
+
| Some v -> Some v
37
+
| None ->
38
+
(match t.github with
39
+
| Some v -> Some ("https://github.com/" ^ v)
40
+
| None ->
41
+
(match t.email with
42
+
| Some v -> Some ("mailto:" ^ v)
43
+
| None -> None))
44
+
45
+
let json_t =
46
+
let open Jsont in
47
+
let open Jsont.Object in
48
+
let mem_opt f v ~enc = mem f v ~dec_absent:None ~enc_omit:Option.is_none ~enc in
49
+
let make handle names email icon github twitter bluesky mastodon orcid url atom_feeds =
50
+
{ handle; names; email; icon; github; twitter; bluesky; mastodon;
51
+
orcid; url; atom_feeds }
52
+
in
53
+
map ~kind:"Contact" make
54
+
|> mem "handle" string ~enc:handle
55
+
|> mem "names" (list string) ~dec_absent:[] ~enc:names
56
+
|> mem_opt "email" (some string) ~enc:email
57
+
|> mem_opt "icon" (some string) ~enc:icon
58
+
|> mem_opt "github" (some string) ~enc:github
59
+
|> mem_opt "twitter" (some string) ~enc:twitter
60
+
|> mem_opt "bluesky" (some string) ~enc:bluesky
61
+
|> mem_opt "mastodon" (some string) ~enc:mastodon
62
+
|> mem_opt "orcid" (some string) ~enc:orcid
63
+
|> mem_opt "url" (some string) ~enc:url
64
+
|> mem_opt "atom_feeds" (some (list string)) ~enc:atom_feeds
65
+
|> finish
66
+
67
+
let compare a b = String.compare a.handle b.handle
68
+
69
+
let pp ppf t =
70
+
let open Fmt in
71
+
pf ppf "@[<v>";
72
+
pf ppf "%a: @%a@," (styled `Bold string) "Handle" string t.handle;
73
+
pf ppf "%a: %a@," (styled `Bold string) "Name" string (name t);
74
+
let ns = names t in
75
+
if List.length ns > 1 then
76
+
pf ppf "%a: @[<h>%a@]@," (styled `Bold string) "Aliases"
77
+
(list ~sep:comma string) (List.tl ns);
78
+
(match t.email with
79
+
| Some e -> pf ppf "%a: %a@," (styled `Bold string) "Email" string e
80
+
| None -> ());
81
+
(match t.github with
82
+
| Some g -> pf ppf "%a: https://github.com/%a@,"
83
+
(styled `Bold string) "GitHub" string g
84
+
| None -> ());
85
+
(match t.twitter with
86
+
| Some tw -> pf ppf "%a: https://twitter.com/%a@,"
87
+
(styled `Bold string) "Twitter" string tw
88
+
| None -> ());
89
+
(match t.bluesky with
90
+
| Some b -> pf ppf "%a: %a@," (styled `Bold string) "Bluesky" string b
91
+
| None -> ());
92
+
(match t.mastodon with
93
+
| Some m -> pf ppf "%a: %a@," (styled `Bold string) "Mastodon" string m
94
+
| None -> ());
95
+
(match t.orcid with
96
+
| Some o -> pf ppf "%a: https://orcid.org/%a@,"
97
+
(styled `Bold string) "ORCID" string o
98
+
| None -> ());
99
+
(match t.url with
100
+
| Some u -> pf ppf "%a: %a@," (styled `Bold string) "URL" string u
101
+
| None -> ());
102
+
(match t.icon with
103
+
| Some i -> pf ppf "%a: %a@," (styled `Bold string) "Icon" string i
104
+
| None -> ());
105
+
(match t.atom_feeds with
106
+
| Some feeds when feeds <> [] ->
107
+
pf ppf "%a: @[<h>%a@]@," (styled `Bold string) "Atom Feeds"
108
+
(list ~sep:comma string) feeds
109
+
| _ -> ());
110
+
pf ppf "@]"
111
+
end
112
+
113
+
type t = {
114
+
xdg : Xdge.t; [@warning "-69"]
115
+
data_dir : Eio.Fs.dir_ty Eio.Path.t;
116
+
}
117
+
118
+
let create fs app_name =
119
+
let xdg = Xdge.create fs app_name in
120
+
let data_dir = Xdge.data_dir xdg in
121
+
{ xdg; data_dir }
122
+
123
+
let contact_file t handle =
124
+
Eio.Path.(t.data_dir / (handle ^ ".json"))
125
+
126
+
let save t contact =
127
+
let path = contact_file t (Contact.handle contact) in
128
+
match Jsont_bytesrw.encode_string Contact.json_t contact with
129
+
| Ok json_str -> Eio.Path.save ~create:(`Or_truncate 0o644) path json_str
130
+
| Error err -> failwith ("Failed to encode contact: " ^ err)
131
+
132
+
let lookup t handle =
133
+
let path = contact_file t handle in
134
+
try
135
+
let content = Eio.Path.load path in
136
+
match Jsont_bytesrw.decode_string Contact.json_t content with
137
+
| Ok contact -> Some contact
138
+
| Error _ -> None
139
+
with
140
+
| _ -> None
141
+
142
+
let delete t handle =
143
+
let path = contact_file t handle in
144
+
try
145
+
Eio.Path.unlink path
146
+
with
147
+
| _ -> ()
148
+
149
+
let list t =
150
+
try
151
+
let entries = Eio.Path.read_dir t.data_dir in
152
+
List.filter_map (fun entry ->
153
+
if Filename.check_suffix entry ".json" then
154
+
let handle = Filename.chop_suffix entry ".json" in
155
+
lookup t handle
156
+
else
157
+
None
158
+
) entries
159
+
with
160
+
| _ -> []
161
+
162
+
let handle_of_name name =
163
+
let name = String.lowercase_ascii name in
164
+
let words = String.split_on_char ' ' name in
165
+
let initials = String.concat "" (List.map (fun w -> String.sub w 0 1) words) in
166
+
initials ^ List.hd (List.rev words)
167
+
168
+
let find_by_name t name =
169
+
let name_lower = String.lowercase_ascii name in
170
+
let all_contacts = list t in
171
+
let matches = List.filter (fun c ->
172
+
List.exists (fun n -> String.lowercase_ascii n = name_lower)
173
+
(Contact.names c)
174
+
) all_contacts in
175
+
match matches with
176
+
| [contact] -> contact
177
+
| [] -> raise Not_found
178
+
| _ -> raise (Invalid_argument ("Multiple contacts match: " ^ name))
179
+
180
+
let find_by_name_opt t name =
181
+
try
182
+
Some (find_by_name t name)
183
+
with
184
+
| Not_found | Invalid_argument _ -> None
185
+
186
+
(* Convenience functions *)
187
+
let create_from_xdg xdg =
188
+
let data_dir = Xdge.data_dir xdg in
189
+
{ xdg; data_dir }
190
+
191
+
let search_all t query =
192
+
let query_lower = String.lowercase_ascii query in
193
+
let all = list t in
194
+
let matches = List.filter (fun c ->
195
+
List.exists (fun name ->
196
+
let name_lower = String.lowercase_ascii name in
197
+
(* Check for exact match *)
198
+
String.equal name_lower query_lower ||
199
+
(* Check if name starts with query *)
200
+
String.starts_with ~prefix:query_lower name_lower ||
201
+
(* For multi-word names, check if any word starts with query *)
202
+
(String.contains name_lower ' ' &&
203
+
String.split_on_char ' ' name_lower |> List.exists (fun word ->
204
+
String.starts_with ~prefix:query_lower word
205
+
))
206
+
) (Contact.names c)
207
+
) all in
208
+
List.sort Contact.compare matches
209
+
210
+
let pp ppf t =
211
+
let all = list t in
212
+
Fmt.pf ppf "@[<v>%a: %d contacts stored in XDG data directory@]"
213
+
(Fmt.styled `Bold Fmt.string) "Sortal Store"
214
+
(List.length all)
215
+
216
+
(* Cmdliner integration *)
217
+
module Cmd = struct
218
+
open Cmdliner
219
+
220
+
(* Command implementations *)
221
+
let list_cmd () _env xdg _profile =
222
+
let store = create_from_xdg xdg in
223
+
let contacts = list store in
224
+
let sorted = List.sort Contact.compare contacts in
225
+
226
+
Logs.app (fun m -> m "Total contacts: %d" (List.length sorted));
227
+
List.iter (fun c ->
228
+
Logs.app (fun m -> m "@%s: %s"
229
+
(Contact.handle c)
230
+
(Contact.name c))
231
+
) sorted;
232
+
0
233
+
234
+
let show_cmd handle _env xdg _profile =
235
+
let store = create_from_xdg xdg in
236
+
match lookup store handle with
237
+
| Some c ->
238
+
Format.printf "%a@." Contact.pp c;
239
+
0
240
+
| None ->
241
+
Logs.err (fun m -> m "Contact not found: %s" handle);
242
+
1
243
+
244
+
let search_cmd query _env xdg _profile =
245
+
let store = create_from_xdg xdg in
246
+
let matches = search_all store query in
247
+
248
+
if matches = [] then (
249
+
Logs.warn (fun m -> m "No contacts found matching: %s" query);
250
+
1
251
+
) else (
252
+
Logs.app (fun m -> m "Found %d match%s:"
253
+
(List.length matches)
254
+
(if List.length matches = 1 then "" else "es"));
255
+
List.iter (fun c ->
256
+
Logs.app (fun m -> m "@%s: %s"
257
+
(Contact.handle c)
258
+
(Contact.name c));
259
+
260
+
(* Show additional details *)
261
+
(match Contact.email c with
262
+
| Some e -> Logs.app (fun m -> m " Email: %s" e)
263
+
| None -> ());
264
+
(match Contact.github c with
265
+
| Some g -> Logs.app (fun m -> m " GitHub: @%s" g)
266
+
| None -> ());
267
+
(match Contact.best_url c with
268
+
| Some u -> Logs.app (fun m -> m " URL: %s" u)
269
+
| None -> ())
270
+
) matches;
271
+
0
272
+
)
273
+
274
+
let stats_cmd () _env xdg _profile =
275
+
let store = create_from_xdg xdg in
276
+
let contacts = list store in
277
+
278
+
let total = List.length contacts in
279
+
let with_email = List.filter (fun c -> Contact.email c <> None) contacts |> List.length in
280
+
let with_github = List.filter (fun c -> Contact.github c <> None) contacts |> List.length in
281
+
let with_orcid = List.filter (fun c -> Contact.orcid c <> None) contacts |> List.length in
282
+
let with_url = List.filter (fun c -> Contact.url c <> None) contacts |> List.length in
283
+
let with_feeds = List.filter (fun c -> Contact.atom_feeds c <> None) contacts |> List.length in
284
+
285
+
Logs.app (fun m -> m "Contact Database Statistics:");
286
+
Logs.app (fun m -> m " Total contacts: %d" total);
287
+
Logs.app (fun m -> m " With email: %d (%.1f%%)" with_email (float_of_int with_email /. float_of_int total *. 100.));
288
+
Logs.app (fun m -> m " With GitHub: %d (%.1f%%)" with_github (float_of_int with_github /. float_of_int total *. 100.));
289
+
Logs.app (fun m -> m " With ORCID: %d (%.1f%%)" with_orcid (float_of_int with_orcid /. float_of_int total *. 100.));
290
+
Logs.app (fun m -> m " With URL: %d (%.1f%%)" with_url (float_of_int with_url /. float_of_int total *. 100.));
291
+
Logs.app (fun m -> m " With Atom feeds: %d (%.1f%%)" with_feeds (float_of_int with_feeds /. float_of_int total *. 100.));
292
+
0
293
+
294
+
(* Command info objects *)
295
+
let list_info = Cmd.info "list" ~doc:"List all contacts"
296
+
297
+
let show_info = Cmd.info "show" ~doc:"Show detailed information about a contact"
298
+
299
+
let search_info = Cmd.info "search" ~doc:"Search contacts by name"
300
+
301
+
let stats_info = Cmd.info "stats" ~doc:"Show statistics about the contact database"
302
+
303
+
(* Argument definitions *)
304
+
let handle_arg =
305
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"HANDLE"
306
+
~doc:"Contact handle to display")
307
+
308
+
let query_arg =
309
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"QUERY"
310
+
~doc:"Name or partial name to search for")
311
+
end
+323
stack/sortal/lib/sortal.mli
+323
stack/sortal/lib/sortal.mli
···
1
+
(** Sortal - Username to metadata mapping with XDG storage
2
+
3
+
This library provides a system for mapping usernames to various metadata
4
+
including URLs, emails, ORCID identifiers, and social media handles.
5
+
It uses XDG Base Directory Specification for storage locations and
6
+
jsont for JSON encoding/decoding.
7
+
8
+
{b Storage:}
9
+
10
+
Contact metadata is stored as JSON files in the XDG data directory,
11
+
with one file per contact using the handle as the filename.
12
+
13
+
{b Typical Usage:}
14
+
15
+
{[
16
+
let store = Sortal.create env#fs "myapp" in
17
+
let contact = Sortal.Contact.make
18
+
~handle:"avsm"
19
+
~names:["Anil Madhavapeddy"]
20
+
~email:"anil@recoil.org"
21
+
~github:"avsm"
22
+
~orcid:"0000-0002-7890-1234"
23
+
() in
24
+
Sortal.save store contact;
25
+
26
+
match Sortal.lookup store "avsm" with
27
+
| Some c -> Printf.printf "Found: %s\n" (Sortal.Contact.name c)
28
+
| None -> Printf.printf "Not found\n"
29
+
]}
30
+
*)
31
+
32
+
(** {1 Contact Metadata} *)
33
+
34
+
module Contact : sig
35
+
(** Individual contact metadata.
36
+
37
+
A contact represents metadata about a person, including their name(s),
38
+
social media handles, professional identifiers, and other contact information. *)
39
+
type t
40
+
41
+
(** [make ~handle ~names ?email ?icon ?github ?twitter ?bluesky ?mastodon
42
+
?orcid ?url ?atom_feeds ()] creates a new contact.
43
+
44
+
@param handle A unique identifier/username for this contact (required)
45
+
@param names A list of names for this contact, with the first being primary (required)
46
+
@param email Email address
47
+
@param icon URL to an avatar/icon image
48
+
@param github GitHub username (without the [\@] prefix)
49
+
@param twitter Twitter/X username (without the [\@] prefix)
50
+
@param bluesky Bluesky handle
51
+
@param mastodon Mastodon handle (including instance)
52
+
@param orcid ORCID identifier
53
+
@param url Personal or professional website URL
54
+
@param atom_feeds List of Atom/RSS feed URLs associated with this contact
55
+
*)
56
+
val make :
57
+
handle:string ->
58
+
names:string list ->
59
+
?email:string ->
60
+
?icon:string ->
61
+
?github:string ->
62
+
?twitter:string ->
63
+
?bluesky:string ->
64
+
?mastodon:string ->
65
+
?orcid:string ->
66
+
?url:string ->
67
+
?atom_feeds:string list ->
68
+
unit ->
69
+
t
70
+
71
+
(** {2 Accessors} *)
72
+
73
+
(** [handle t] returns the unique handle/username. *)
74
+
val handle : t -> string
75
+
76
+
(** [names t] returns all names associated with this contact. *)
77
+
val names : t -> string list
78
+
79
+
(** [name t] returns the primary (first) name. *)
80
+
val name : t -> string
81
+
82
+
(** [email t] returns the email address if available. *)
83
+
val email : t -> string option
84
+
85
+
(** [icon t] returns the icon/avatar URL if available. *)
86
+
val icon : t -> string option
87
+
88
+
(** [github t] returns the GitHub username if available. *)
89
+
val github : t -> string option
90
+
91
+
(** [twitter t] returns the Twitter/X username if available. *)
92
+
val twitter : t -> string option
93
+
94
+
(** [bluesky t] returns the Bluesky handle if available. *)
95
+
val bluesky : t -> string option
96
+
97
+
(** [mastodon t] returns the Mastodon handle if available. *)
98
+
val mastodon : t -> string option
99
+
100
+
(** [orcid t] returns the ORCID identifier if available. *)
101
+
val orcid : t -> string option
102
+
103
+
(** [url t] returns the personal/professional website URL if available. *)
104
+
val url : t -> string option
105
+
106
+
(** [atom_feeds t] returns the list of Atom/RSS feed URLs if available. *)
107
+
val atom_feeds : t -> string list option
108
+
109
+
(** {2 Derived Information} *)
110
+
111
+
(** [best_url t] returns the best available URL for this contact.
112
+
113
+
Priority order:
114
+
1. Personal URL (if set)
115
+
2. GitHub profile URL (if GitHub username is set)
116
+
3. Email as mailto: link (if email is set)
117
+
4. None if no URL-like information is available
118
+
*)
119
+
val best_url : t -> string option
120
+
121
+
(** {2 JSON Encoding} *)
122
+
123
+
(** [json_t] is the jsont encoder/decoder for contacts.
124
+
125
+
The JSON schema includes all contact fields with optional values
126
+
omitted when not present:
127
+
{[
128
+
{
129
+
"handle": "avsm",
130
+
"names": ["Anil Madhavapeddy"],
131
+
"email": "anil@recoil.org",
132
+
"github": "avsm",
133
+
"orcid": "0000-0002-7890-1234"
134
+
}
135
+
]}
136
+
*)
137
+
val json_t : t Jsont.t
138
+
139
+
(** {2 Utilities} *)
140
+
141
+
(** [compare a b] compares two contacts by their handles. *)
142
+
val compare : t -> t -> int
143
+
144
+
(** [pp ppf t] pretty prints a contact with formatting. *)
145
+
val pp : Format.formatter -> t -> unit
146
+
end
147
+
148
+
(** {1 Contact Store} *)
149
+
150
+
(** The contact store manages reading and writing contact metadata
151
+
using XDG-compliant storage locations. *)
152
+
type t
153
+
154
+
(** [create fs app_name] creates a new contact store.
155
+
156
+
The store will use XDG data directories for persistent storage
157
+
of contact metadata. Each contact is stored as a separate JSON
158
+
file named after its handle.
159
+
160
+
@param fs Eio filesystem for file operations
161
+
@param app_name Application name for XDG directory structure
162
+
*)
163
+
val create : Eio.Fs.dir_ty Eio.Path.t -> string -> t
164
+
165
+
(** {2 Storage Operations} *)
166
+
167
+
(** [save t contact] saves a contact to the store.
168
+
169
+
The contact is serialized to JSON and written to a file
170
+
named "handle.json" in the XDG data directory.
171
+
172
+
If a contact with the same handle already exists, it is overwritten.
173
+
*)
174
+
val save : t -> Contact.t -> unit
175
+
176
+
(** [lookup t handle] retrieves a contact by handle.
177
+
178
+
Searches for a file named "handle.json" in the XDG data directory
179
+
and deserializes it if found.
180
+
181
+
@return [Some contact] if found, [None] if not found or deserialization fails
182
+
*)
183
+
val lookup : t -> string -> Contact.t option
184
+
185
+
(** [delete t handle] removes a contact from the store.
186
+
187
+
Deletes the file "handle.json" from the XDG data directory.
188
+
Does nothing if the contact does not exist.
189
+
*)
190
+
val delete : t -> string -> unit
191
+
192
+
(** [list t] returns all contacts in the store.
193
+
194
+
Scans the XDG data directory for all .json files and attempts
195
+
to deserialize them as contacts. Files that fail to parse are
196
+
silently skipped.
197
+
198
+
@return A list of all successfully loaded contacts
199
+
*)
200
+
val list : t -> Contact.t list
201
+
202
+
(** {2 Searching} *)
203
+
204
+
(** [find_by_name t name] searches for contacts by name.
205
+
206
+
Performs a case-insensitive search through all contacts,
207
+
checking if any of their names match the provided name.
208
+
209
+
@param name The name to search for (case-insensitive)
210
+
@return The matching contact if exactly one match is found
211
+
@raise Not_found if no contacts match the name
212
+
@raise Invalid_argument if multiple contacts match the name
213
+
*)
214
+
val find_by_name : t -> string -> Contact.t
215
+
216
+
(** [find_by_name_opt t name] searches for contacts by name, returning an option.
217
+
218
+
Like {!find_by_name} but returns [None] instead of raising exceptions
219
+
when no match or multiple matches are found.
220
+
221
+
@param name The name to search for (case-insensitive)
222
+
@return [Some contact] if exactly one match is found, [None] otherwise
223
+
*)
224
+
val find_by_name_opt : t -> string -> Contact.t option
225
+
226
+
(** {2 Utilities} *)
227
+
228
+
(** [handle_of_name name] generates a handle from a full name.
229
+
230
+
Creates a handle by concatenating the initials of all words
231
+
in the name with the full last name, all in lowercase.
232
+
233
+
Examples:
234
+
- "Anil Madhavapeddy" -> "ammadhavapeddy"
235
+
- "John Smith" -> "jssmith"
236
+
237
+
@param name The full name to convert
238
+
@return A suggested handle
239
+
*)
240
+
val handle_of_name : string -> string
241
+
242
+
(** {2 Convenience Functions} *)
243
+
244
+
(** [create_from_xdg xdg] creates a contact store from an XDG context.
245
+
246
+
This is a convenience function for creating a store when you already
247
+
have an XDG context (e.g., from eiocmd or your own XDG initialization).
248
+
The store will use the XDG data directory for the application.
249
+
250
+
@param xdg An existing XDG context
251
+
@return A contact store using the XDG data directory
252
+
*)
253
+
val create_from_xdg : Xdge.t -> t
254
+
255
+
(** [search_all t query] searches for contacts matching a query string.
256
+
257
+
Performs a flexible search through all contact names, looking for:
258
+
- Exact matches (case-insensitive)
259
+
- Names that start with the query
260
+
- Multi-word names where any word starts with the query
261
+
262
+
This is useful for autocomplete or fuzzy search functionality.
263
+
264
+
@param t The contact store
265
+
@param query The search query (case-insensitive)
266
+
@return A list of matching contacts, sorted by handle
267
+
*)
268
+
val search_all : t -> string -> Contact.t list
269
+
270
+
(** {2 Pretty Printing} *)
271
+
272
+
(** [pp ppf t] pretty prints the contact store showing statistics. *)
273
+
val pp : Format.formatter -> t -> unit
274
+
275
+
(** {1 Cmdliner Integration} *)
276
+
277
+
module Cmd : sig
278
+
(** Cmdliner terms and commands for contact management.
279
+
280
+
This module provides ready-to-use Cmdliner terms for building
281
+
CLI applications that work with contact metadata. *)
282
+
283
+
(** [list_cmd] is a Cmdliner command that lists all contacts.
284
+
285
+
Usage: Integrate into your CLI with [Cmd.group] or use standalone.
286
+
Requires eiocmd setup (env, xdg, profile parameters). *)
287
+
val list_cmd : unit -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)
288
+
289
+
(** [show_cmd handle] creates a command to show detailed contact information.
290
+
291
+
@param handle The contact handle to display *)
292
+
val show_cmd : string -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)
293
+
294
+
(** [search_cmd query] creates a command to search contacts by name.
295
+
296
+
@param query The search query string *)
297
+
val search_cmd : string -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)
298
+
299
+
(** [stats_cmd] is a command that shows database statistics. *)
300
+
val stats_cmd : unit -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)
301
+
302
+
(** {2 Cmdliner Info Objects} *)
303
+
304
+
(** [list_info] is the command info for the list command. *)
305
+
val list_info : Cmdliner.Cmd.info
306
+
307
+
(** [show_info] is the command info for the show command. *)
308
+
val show_info : Cmdliner.Cmd.info
309
+
310
+
(** [search_info] is the command info for the search command. *)
311
+
val search_info : Cmdliner.Cmd.info
312
+
313
+
(** [stats_info] is the command info for the stats command. *)
314
+
val stats_info : Cmdliner.Cmd.info
315
+
316
+
(** {2 Cmdliner Argument Definitions} *)
317
+
318
+
(** [handle_arg] is the positional argument for a contact handle. *)
319
+
val handle_arg : string Cmdliner.Term.t
320
+
321
+
(** [query_arg] is the positional argument for a search query. *)
322
+
val query_arg : string Cmdliner.Term.t
323
+
end
+119
stack/sortal/scripts/import_yaml_contacts.py
+119
stack/sortal/scripts/import_yaml_contacts.py
···
1
+
#!/usr/bin/env python3
2
+
"""
3
+
Import YAML contacts from arod-dream to Sortal JSON format.
4
+
5
+
This script reads contacts from ~/src/git/avsm/arod-dream/data/contacts/
6
+
and converts them to JSON files in the XDG data directory for sortal.
7
+
"""
8
+
9
+
import os
10
+
import json
11
+
import yaml
12
+
from pathlib import Path
13
+
14
+
def get_xdg_data_home():
15
+
"""Get the XDG data home directory."""
16
+
xdg_data_home = os.environ.get('XDG_DATA_HOME')
17
+
if xdg_data_home:
18
+
return Path(xdg_data_home)
19
+
return Path.home() / '.local' / 'share'
20
+
21
+
def parse_contact_md(file_path):
22
+
"""Parse a markdown file with YAML front matter."""
23
+
with open(file_path, 'r') as f:
24
+
content = f.read()
25
+
26
+
# Extract YAML front matter between ---
27
+
if content.startswith('---\n'):
28
+
parts = content.split('---\n', 2)
29
+
if len(parts) >= 2:
30
+
yaml_content = parts[1]
31
+
return yaml.safe_load(yaml_content)
32
+
return None
33
+
34
+
def convert_to_sortal_format(yaml_data, handle):
35
+
"""Convert YAML contact data to Sortal JSON format."""
36
+
sortal_contact = {
37
+
"handle": handle,
38
+
"names": yaml_data.get("names", [])
39
+
}
40
+
41
+
# Optional fields
42
+
if "email" in yaml_data:
43
+
sortal_contact["email"] = yaml_data["email"]
44
+
if "icon" in yaml_data:
45
+
sortal_contact["icon"] = yaml_data["icon"]
46
+
if "github" in yaml_data:
47
+
sortal_contact["github"] = yaml_data["github"]
48
+
if "twitter" in yaml_data:
49
+
sortal_contact["twitter"] = yaml_data["twitter"]
50
+
if "bluesky" in yaml_data:
51
+
sortal_contact["bluesky"] = yaml_data["bluesky"]
52
+
if "mastodon" in yaml_data:
53
+
sortal_contact["mastodon"] = yaml_data["mastodon"]
54
+
if "orcid" in yaml_data:
55
+
sortal_contact["orcid"] = yaml_data["orcid"]
56
+
if "url" in yaml_data:
57
+
sortal_contact["url"] = yaml_data["url"]
58
+
if "atom" in yaml_data:
59
+
sortal_contact["atom_feeds"] = yaml_data["atom"]
60
+
61
+
return sortal_contact
62
+
63
+
def main():
64
+
# Source directory
65
+
source_dir = Path.home() / 'src' / 'git' / 'avsm' / 'arod-dream' / 'data' / 'contacts'
66
+
67
+
# Destination directory (XDG data home for sortal)
68
+
xdg_data = get_xdg_data_home()
69
+
dest_dir = xdg_data / 'sortal'
70
+
dest_dir.mkdir(parents=True, exist_ok=True)
71
+
72
+
print(f"Importing contacts from: {source_dir}")
73
+
print(f"Output directory: {dest_dir}")
74
+
print()
75
+
76
+
if not source_dir.exists():
77
+
print(f"Error: Source directory does not exist: {source_dir}")
78
+
return 1
79
+
80
+
imported_count = 0
81
+
error_count = 0
82
+
83
+
# Process each .md file
84
+
for md_file in sorted(source_dir.glob('*.md')):
85
+
handle = md_file.stem
86
+
87
+
try:
88
+
yaml_data = parse_contact_md(md_file)
89
+
if yaml_data is None:
90
+
print(f"⚠ Skipping {handle}: No YAML front matter found")
91
+
error_count += 1
92
+
continue
93
+
94
+
# Convert to Sortal format
95
+
sortal_contact = convert_to_sortal_format(yaml_data, handle)
96
+
97
+
# Write JSON file
98
+
output_file = dest_dir / f"{handle}.json"
99
+
with open(output_file, 'w') as f:
100
+
json.dump(sortal_contact, f, indent=2, ensure_ascii=False)
101
+
102
+
name = sortal_contact.get('names', [handle])[0] if sortal_contact.get('names') else handle
103
+
print(f"✓ Imported: {handle} ({name})")
104
+
imported_count += 1
105
+
106
+
except Exception as e:
107
+
print(f"✗ Error importing {handle}: {e}")
108
+
error_count += 1
109
+
110
+
print()
111
+
print(f"Import complete!")
112
+
print(f" Successfully imported: {imported_count}")
113
+
print(f" Errors: {error_count}")
114
+
print(f" Output directory: {dest_dir}")
115
+
116
+
return 0 if error_count == 0 else 1
117
+
118
+
if __name__ == '__main__':
119
+
exit(main())
+3
stack/sortal/test/dune
+3
stack/sortal/test/dune
+167
stack/sortal/test/test_sortal.ml
+167
stack/sortal/test/test_sortal.ml
···
1
+
(** Tests for the Sortal library *)
2
+
3
+
open Eio.Std
4
+
5
+
let test_contact_creation () =
6
+
let c = Sortal.Contact.make
7
+
~handle:"test"
8
+
~names:["Test User"; "T. User"]
9
+
~email:"test@example.com"
10
+
~github:"testuser"
11
+
() in
12
+
assert (Sortal.Contact.handle c = "test");
13
+
assert (Sortal.Contact.name c = "Test User");
14
+
assert (List.length (Sortal.Contact.names c) = 2);
15
+
assert (Sortal.Contact.email c = Some "test@example.com");
16
+
assert (Sortal.Contact.github c = Some "testuser");
17
+
assert (Sortal.Contact.twitter c = None);
18
+
traceln "✓ Contact creation works"
19
+
20
+
let test_best_url () =
21
+
let c1 = Sortal.Contact.make
22
+
~handle:"test1"
23
+
~names:["Test 1"]
24
+
~url:"https://example.com"
25
+
~github:"test1"
26
+
() in
27
+
assert (Sortal.Contact.best_url c1 = Some "https://example.com");
28
+
29
+
let c2 = Sortal.Contact.make
30
+
~handle:"test2"
31
+
~names:["Test 2"]
32
+
~github:"test2"
33
+
() in
34
+
assert (Sortal.Contact.best_url c2 = Some "https://github.com/test2");
35
+
36
+
let c3 = Sortal.Contact.make
37
+
~handle:"test3"
38
+
~names:["Test 3"]
39
+
~email:"test3@example.com"
40
+
() in
41
+
assert (Sortal.Contact.best_url c3 = Some "mailto:test3@example.com");
42
+
43
+
let c4 = Sortal.Contact.make
44
+
~handle:"test4"
45
+
~names:["Test 4"]
46
+
() in
47
+
assert (Sortal.Contact.best_url c4 = None);
48
+
49
+
traceln "✓ Best URL selection works"
50
+
51
+
let test_json_encoding () =
52
+
let c = Sortal.Contact.make
53
+
~handle:"json_test"
54
+
~names:["JSON Test"]
55
+
~email:"json@example.com"
56
+
~github:"jsontest"
57
+
~orcid:"0000-0001-2345-6789"
58
+
() in
59
+
60
+
match Jsont_bytesrw.encode_string Sortal.Contact.json_t c with
61
+
| Ok json_str ->
62
+
(match Jsont_bytesrw.decode_string Sortal.Contact.json_t json_str with
63
+
| Ok decoded ->
64
+
assert (Sortal.Contact.handle decoded = "json_test");
65
+
assert (Sortal.Contact.email decoded = Some "json@example.com");
66
+
assert (Sortal.Contact.github decoded = Some "jsontest");
67
+
assert (Sortal.Contact.orcid decoded = Some "0000-0001-2345-6789");
68
+
traceln "✓ JSON encoding/decoding works"
69
+
| Error err ->
70
+
failwith ("JSON decode failed: " ^ err))
71
+
| Error err ->
72
+
failwith ("JSON encode failed: " ^ err)
73
+
74
+
let test_handle_generation () =
75
+
assert (Sortal.handle_of_name "John Smith" = "jssmith");
76
+
assert (Sortal.handle_of_name "Alice Barbara Cooper" = "abccooper");
77
+
assert (Sortal.handle_of_name "Bob" = "bbob");
78
+
traceln "✓ Handle generation works"
79
+
80
+
let test_store_operations () =
81
+
Eio_main.run @@ fun env ->
82
+
83
+
(* Create a store with a test app name *)
84
+
let store = Sortal.create env#fs "sortal-test" in
85
+
86
+
(* Create test contacts *)
87
+
let c1 = Sortal.Contact.make
88
+
~handle:"alice"
89
+
~names:["Alice Anderson"]
90
+
~email:"alice@example.com"
91
+
() in
92
+
93
+
let c2 = Sortal.Contact.make
94
+
~handle:"bob"
95
+
~names:["Bob Brown"; "Robert Brown"]
96
+
~github:"bobbrown"
97
+
() in
98
+
99
+
(* Test save *)
100
+
Sortal.save store c1;
101
+
Sortal.save store c2;
102
+
traceln "✓ Saving contacts works";
103
+
104
+
(* Test lookup *)
105
+
(match Sortal.lookup store "alice" with
106
+
| Some c ->
107
+
assert (Sortal.Contact.name c = "Alice Anderson");
108
+
traceln "✓ Lookup works"
109
+
| None -> failwith "Lookup failed to find saved contact");
110
+
111
+
(* Test lookup of non-existent contact *)
112
+
(match Sortal.lookup store "nonexistent" with
113
+
| None -> traceln "✓ Lookup correctly returns None for missing contact"
114
+
| Some _ -> failwith "Lookup should return None for non-existent contact");
115
+
116
+
(* Test list *)
117
+
let all = Sortal.list store in
118
+
assert (List.length all >= 2);
119
+
traceln "✓ List returns saved contacts (%d total)" (List.length all);
120
+
121
+
(* Test find_by_name *)
122
+
let found = Sortal.find_by_name store "Bob Brown" in
123
+
assert (Sortal.Contact.handle found = "bob");
124
+
traceln "✓ Find by name works";
125
+
126
+
(* Test find_by_name_opt *)
127
+
(match Sortal.find_by_name_opt store "Alice Anderson" with
128
+
| Some c ->
129
+
assert (Sortal.Contact.handle c = "alice");
130
+
traceln "✓ Find by name (optional) works"
131
+
| None -> failwith "find_by_name_opt failed");
132
+
133
+
(match Sortal.find_by_name_opt store "Nobody" with
134
+
| None -> traceln "✓ Find by name (optional) returns None for missing"
135
+
| Some _ -> failwith "find_by_name_opt should return None");
136
+
137
+
(* Test delete *)
138
+
Sortal.delete store "alice";
139
+
(match Sortal.lookup store "alice" with
140
+
| None -> traceln "✓ Delete works"
141
+
| Some _ -> failwith "Contact should have been deleted");
142
+
143
+
(* Clean up remaining test contact *)
144
+
Sortal.delete store "bob";
145
+
traceln "✓ Test cleanup complete"
146
+
147
+
let test_contact_compare () =
148
+
let c1 = Sortal.Contact.make ~handle:"alice" ~names:["Alice"] () in
149
+
let c2 = Sortal.Contact.make ~handle:"bob" ~names:["Bob"] () in
150
+
let c3 = Sortal.Contact.make ~handle:"alice" ~names:["Alice2"] () in
151
+
152
+
assert (Sortal.Contact.compare c1 c2 < 0);
153
+
assert (Sortal.Contact.compare c2 c1 > 0);
154
+
assert (Sortal.Contact.compare c1 c3 = 0);
155
+
traceln "✓ Contact comparison works"
156
+
157
+
let () =
158
+
traceln "\n=== Running Sortal Tests ===\n";
159
+
160
+
test_contact_creation ();
161
+
test_best_url ();
162
+
test_json_encoding ();
163
+
test_handle_generation ();
164
+
test_contact_compare ();
165
+
test_store_operations ();
166
+
167
+
traceln "\n=== All Tests Passed ===\n"