forked from
anil.recoil.org/xdge
XDG library path support for OCaml via Eio capabilities
ocaml-linkedin: apply dune fmt
Pure formatting changes from `dune fmt`: doc comment placement moves
from above the binding to below it for `type`s, multi-line `match`
expressions collapse onto one line where they fit, and infix operator
applications pick up spaces (`Soup.($?)` -> `Soup.( $? )`). No
semantic changes.
+57
-15
+49
-13
README.md
+49
-13
README.md
···
40
40
## Usage
41
41
42
42
```ocaml
43
-
Eio_main.run @@ fun env ->
43
+
let () =
44
+
Eio_main.run @@ fun env ->
44
45
let xdg = Xdge.v env#fs "myapp" in
45
-
46
-
(* Access XDG directories as Eio paths *)
47
46
let config = Xdge.config_dir xdg in
48
47
let data = Xdge.data_dir xdg in
48
+
Fmt.pr "config: %a@." Eio.Path.pp config;
49
+
Fmt.pr "data: %a@." Eio.Path.pp data;
50
+
match Xdge.config_file xdg "settings.json" with
51
+
| Some path -> Fmt.pr "found settings.json at %a@." Eio.Path.pp path
52
+
| None -> Fmt.pr "no settings.json on the XDG search path@."
53
+
```
49
54
50
-
(* Search for files following XDG precedence *)
51
-
match Xdge.config_file xdg "settings.json" with
52
-
| Some path -> (* use path *)
53
-
| None -> (* use defaults *)
55
+
On a default Linux install with no XDG overrides the first three lines
56
+
print:
57
+
58
+
```
59
+
config: <fs>/home/alice/.config/myapp
60
+
data: <fs>/home/alice/.local/share/myapp
54
61
```
55
62
56
-
For CLI applications, xdge provides Cmdliner terms that handle environment
57
-
variable precedence and command-line overrides:
63
+
`Xdge.config_file` walks `$XDG_CONFIG_HOME`, then each entry of
64
+
`$XDG_CONFIG_DIRS` (defaulting to `/etc/xdg`), returning the first hit:
65
+
66
+
```
67
+
1. /home/alice/.config/myapp/settings.json
68
+
2. /etc/xdg/myapp/settings.json
69
+
```
70
+
71
+
Equivalent paths on macOS follow the same precedence rules with
72
+
`$HOME/Library/Application Support/myapp` as the user default. Override
73
+
any layer by setting `XDG_CONFIG_HOME`, `XDG_CONFIG_DIRS`, etc.
74
+
75
+
## Cmdliner integration
76
+
77
+
For CLI applications, xdge provides a Cmdliner term that exposes
78
+
`--config-dir`, `--data-dir`, `--cache-dir`, `--state-dir`, and
79
+
`--runtime-dir` flags, with precedence:
80
+
81
+
```
82
+
--config-dir (CLI) > MYAPP_CONFIG_DIR > XDG_CONFIG_HOME > default
83
+
```
58
84
59
85
```ocaml
60
86
let () =
61
87
Eio_main.run @@ fun env ->
62
-
let term = Xdge.Cmd.term "myapp" env#fs () in
63
-
(* Generates --config-dir, --data-dir, etc. flags *)
64
-
(* Respects MYAPP_CONFIG_DIR > XDG_CONFIG_HOME > default *)
88
+
let _term = Xdge.Cmd.term "myapp" env#fs () in
89
+
()
65
90
```
66
91
67
92
## Installation
68
93
94
+
Install with opam:
95
+
96
+
```sh
97
+
$ opam install xdge
69
98
```
70
-
opam install xdge
99
+
100
+
If opam cannot find the package, it may not yet be released in the public
101
+
`opam-repository`. Add the overlay repository, then install it:
102
+
103
+
```sh
104
+
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
105
+
$ opam update
106
+
$ opam install xdge
71
107
```
72
108
73
109
## Licence
+4
dune
+4
dune
+4
-2
xdge.opam
+4
-2
xdge.opam
···
7
7
authors: ["Anil Madhavapeddy"]
8
8
license: "ISC"
9
9
tags: ["org:blacksun" "eio" "system"]
10
-
homepage: "https://tangled.sh/@anil.recoil.org/xdge"
11
-
bug-reports: "https://tangled.sh/@anil.recoil.org/xdge/issues"
10
+
homepage: "https://tangled.org/anil.recoil.org/xdge"
11
+
bug-reports: "https://tangled.org/anil.recoil.org/xdge/issues"
12
12
depends: [
13
13
"dune" {>= "3.21"}
14
14
"ocaml" {>= "5.1.0"}
···
18
18
"xdg"
19
19
"eio_main" {with-test}
20
20
"odoc" {with-doc}
21
+
"mdx" {with-test}
21
22
"alcotest" {with-test & >= "1.7.0"}
22
23
]
24
+
dev-repo: "git+https://tangled.org/anil.recoil.org/xdge"
23
25
x-maintenance-intent: ["(latest)"]
24
26
build: [
25
27
[ "dune" "subst" ] {dev}