···

       
1
       
 
       
(executable

     

       
2
       
 
       
 (name karakeepe_cli)

     

       
3
       
 
       
 (public_name karakeepe)

     

       
4
       
-
       
 (libraries karakeepe keyeio xdge eiocmd eio eio_main cmdliner ptime))

     

···

       
1
       
 
       
(executable

     

       
2
       
 
       
 (name karakeepe_cli)

     

       
3
       
 
       
 (public_name karakeepe)

     

       
4
       
+
       
 (libraries karakeepe keyeio xdge eiocmd eio eio_main cmdliner ptime logs logs.fmt logs.cli))

     

···

       
13
       
 
       
        |> Option.value ~default:"https://hoard.recoil.org"

     

       
14
       
 
       
  in

     

       
15
       
 
       


     

       
16
       
-
       
  Printf.printf "Fetching bookmarks from %s...\n" base_url;

     

       
17
       
-
       


     

       
18
       
 
       
  try

     

       
19
       
 
       
    let bookmarks = Karakeepe.fetch_all_bookmarks

     

       
20
       
 
       
      ~sw ~env ~api_key

     

       
21
       
-
       
      ~page_size:limit

     

       
22
       
 
       
      ~include_content:true

     

       
23
       
 
       
      ?filter_tags:(if tags = [] then None else Some tags)

     

       
24
       
 
       
      base_url

     
···

       
183
       
 
       
    1

     

       
184
       
 
       
  end else begin

     

       
185
       
 
       
    try

     

       
186
       
-
       
      Printf.printf "Searching for bookmarks with tags: %s\n" (String.concat ", " tags);

     

       
187
       
-
       


     

       
188
       
 
       
      let bookmarks = Karakeepe.fetch_all_bookmarks

     

       
189
       
 
       
        ~sw ~env ~api_key

     

       
190
       
-
       
        ~page_size:limit

     

       
191
       
 
       
        ~filter_tags:tags

     

       
192
       
 
       
        ~include_content:true

     

       
193
       
 
       
        base_url

     

       
194
       
 
       
      in

     

       
195
       
 
       


     

       
196
       
-
       
      Printf.printf "Found %d bookmarks\n\n" (List.length bookmarks);

     

       
0
       
 
       

     

       
197
       
 
       


     

       
198
       
 
       
      List.iteri (fun i (b : Karakeepe.bookmark) ->

     

       
199
       
 
       
        Printf.printf "%d. %s\n" (i + 1) b.url;

     

···

       
13
       
 
       
        |> Option.value ~default:"https://hoard.recoil.org"

     

       
14
       
 
       
  in

     

       
15
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
16
       
 
       
  try

     

       
17
       
 
       
    let bookmarks = Karakeepe.fetch_all_bookmarks

     

       
18
       
 
       
      ~sw ~env ~api_key

     

       
19
       
+
       
      ~max_bookmarks:limit

     

       
20
       
 
       
      ~include_content:true

     

       
21
       
 
       
      ?filter_tags:(if tags = [] then None else Some tags)

     

       
22
       
 
       
      base_url

     
···

       
181
       
 
       
    1

     

       
182
       
 
       
  end else begin

     

       
183
       
 
       
    try

     

       
0
       
 
       

     

       
0
       
 
       

     

       
184
       
 
       
      let bookmarks = Karakeepe.fetch_all_bookmarks

     

       
185
       
 
       
        ~sw ~env ~api_key

     

       
186
       
+
       
        ~max_bookmarks:limit

     

       
187
       
 
       
        ~filter_tags:tags

     

       
188
       
 
       
        ~include_content:true

     

       
189
       
 
       
        base_url

     

       
190
       
 
       
      in

     

       
191
       
 
       


     

       
192
       
+
       
      Printf.printf "Found %d bookmark%s\n\n" (List.length bookmarks)

     

       
193
       
+
       
        (if List.length bookmarks = 1 then "" else "s");

     

       
194
       
 
       


     

       
195
       
 
       
      List.iteri (fun i (b : Karakeepe.bookmark) ->

     

       
196
       
 
       
        Printf.printf "%d. %s\n" (i + 1) b.url;

     

···

       
1
       
 
       
(library

     

       
2
       
 
       
 (name karakeepe)

     

       
3
       
 
       
 (public_name karakeepe)

     

       
4
       
-
       
 (libraries bushel eio eio.core requests ezjsonm fmt ptime uri))

     

···

       
1
       
 
       
(library

     

       
2
       
 
       
 (name karakeepe)

     

       
3
       
 
       
 (public_name karakeepe)

     

       
4
       
+
       
 (libraries bushel eio eio.core requests ezjsonm fmt ptime uri logs logs.fmt))

     

···

       
2
       
 
       


     

       
3
       
 
       
module J = Ezjsonm

     

       
4
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
5
       
 
       
(** Type representing a Karakeep bookmark *)

     

       
6
       
 
       
type bookmark = {

     

       
7
       
 
       
  id: string;

     
···

       
63
       
 
       
  let id =

     

       
64
       
 
       
    try J.find json ["id"] |> J.get_string

     

       
65
       
 
       
    with e ->

     

       
66
       
-
       
      prerr_endline (Fmt.str "Error parsing bookmark ID: %s" (Printexc.to_string e));

     

       
67
       
-
       
      prerr_endline (Fmt.str "JSON: %s" (J.value_to_string json));

     

       
68
       
 
       
      failwith "Unable to parse bookmark ID"

     

       
69
       
 
       
  in

     

       
70
       
 
       


     
···

       
88
       
 
       
              | Some (`String id) -> "karakeep-asset://" ^ id

     

       
89
       
 
       
              | _ -> failwith "No URL or asset ID found in bookmark"))

     

       
90
       
 
       
      | _ ->

     

       
91
       
-
       
          prerr_endline (Fmt.str "Bookmark JSON structure: %s" (J.value_to_string json));

     

       
0
       
 
       

     

       
92
       
 
       
          failwith "No URL found in bookmark"

     

       
93
       
 
       
  in

     

       
94
       
 
       


     
···

       
152
       
 
       
  { id; title; url; note; created_at; updated_at; favourited; archived; tags;

     

       
153
       
 
       
    tagging_status; summary; content; assets }

     

       
154
       
 
       


     

       
155
       
-
       
(** Parse a Karakeep bookmark response *)

     

       
156
       
 
       
let parse_bookmark_response json =

     

       
157
       
-
       
  prerr_endline (Fmt.str "Full response JSON: %s" (J.value_to_string json));

     

       
158
       
 
       


     

       
159
       
-
       
  try

     

       
0
       
 
       

     

       
0
       
 
       

     

       
160
       
 
       
    let total = J.find json ["total"] |> J.get_int in

     

       
161
       
 
       
    let bookmarks_json = J.find json ["data"] in

     

       
162
       
-
       
    prerr_endline "Found bookmarks in data array";

     

       
163
       
 
       
    let data = J.get_list parse_bookmark bookmarks_json in

     

       
164
       
 
       
    let next_cursor =

     

       
165
       
 
       
      try Some (J.find json ["nextCursor"] |> J.get_string)

     

       
166
       
 
       
      with _ -> None

     

       
167
       
 
       
    in

     

       
0
       
 
       

     

       
168
       
 
       
    { total; data; next_cursor }

     

       
169
       
-
       
  with e1 ->

     

       
170
       
-
       
    prerr_endline (Fmt.str "First format parse error: %s" (Printexc.to_string e1));

     

       
171
       
-
       
    try

     

       
172
       
-
       
      let bookmarks_json = J.find json ["bookmarks"] in

     

       
173
       
-
       
      prerr_endline "Found bookmarks in bookmarks array";

     

       
174
       
-
       
      let data =

     

       
175
       
-
       
        try J.get_list parse_bookmark bookmarks_json

     

       
176
       
-
       
        with e ->

     

       
177
       
-
       
          prerr_endline (Fmt.str "Error parsing bookmarks array: %s" (Printexc.to_string e));

     

       
178
       
-
       
          []

     

       
179
       
-
       
      in

     

       
180
       
-
       
      let next_cursor =

     

       
181
       
-
       
        try Some (J.find json ["nextCursor"] |> J.get_string)

     

       
182
       
-
       
        with _ -> None

     

       
183
       
-
       
      in

     

       
184
       
-
       
      { total = List.length data; data; next_cursor }

     

       
185
       
-
       
    with e2 ->

     

       
186
       
-
       
      prerr_endline (Fmt.str "Second format parse error: %s" (Printexc.to_string e2));

     

       
187
       
-
       
      try

     

       
188
       
-
       
        let error = J.find json ["error"] |> J.get_string in

     

       
189
       
-
       
        let message =

     

       
190
       
-
       
          try J.find json ["message"] |> J.get_string

     

       
191
       
-
       
          with _ -> "Unknown error"

     

       
192
       
-
       
        in

     

       
193
       
-
       
        prerr_endline (Fmt.str "API Error: %s - %s" error message);

     

       
194
       
-
       
        { total = 0; data = []; next_cursor = None }

     

       
195
       
-
       
      with _ ->

     

       
196
       
-
       
        try

     

       
197
       
-
       
          prerr_endline "Trying alternate array format";

     

       
198
       
-
       
          prerr_endline (Fmt.str "JSON structure keys: %s"

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
199
       
 
       
            (match json with

     

       
200
       
-
       
             | `O fields -> String.concat ", " (List.map (fun (k, _) -> k) fields)

     

       
201
       
 
       
             | _ -> "not an object"));

     

       
202
       
-
       


     

       
203
       
-
       
          if J.find_opt json ["nextCursor"] <> None then begin

     

       
204
       
-
       
            prerr_endline "Found nextCursor, checking alternate structures";

     

       
205
       
-
       
            let bookmarks_json =

     

       
206
       
-
       
              try Some (J.find json ["data"])

     

       
207
       
-
       
              with _ -> None

     

       
208
       
-
       
            in

     

       
209
       
-
       
            match bookmarks_json with

     

       
210
       
-
       
            | Some json_array ->

     

       
211
       
-
       
                prerr_endline "Found bookmarks in data field";

     

       
212
       
-
       
                begin try

     

       
213
       
-
       
                  let data = J.get_list parse_bookmark json_array in

     

       
214
       
-
       
                  let next_cursor =

     

       
215
       
-
       
                    try Some (J.find json ["nextCursor"] |> J.get_string)

     

       
216
       
-
       
                    with _ -> None

     

       
217
       
-
       
                  in

     

       
218
       
-
       
                  { total = List.length data; data; next_cursor }

     

       
219
       
-
       
                with e ->

     

       
220
       
-
       
                  prerr_endline (Fmt.str "Error parsing bookmarks from data: %s" (Printexc.to_string e));

     

       
221
       
-
       
                  { total = 0; data = []; next_cursor = None }

     

       
222
       
-
       
                end

     

       
223
       
-
       
            | None ->

     

       
224
       
-
       
                prerr_endline "No bookmarks found in alternate structure";

     

       
225
       
-
       
                { total = 0; data = []; next_cursor = None }

     

       
226
       
-
       
          end

     

       
227
       
-
       
          else begin

     

       
228
       
-
       
            match json with

     

       
229
       
-
       
            | `A _ ->

     

       
230
       
-
       
                let data =

     

       
231
       
-
       
                  try J.get_list parse_bookmark json

     

       
232
       
-
       
                  with e ->

     

       
233
       
-
       
                    prerr_endline (Fmt.str "Error parsing root array: %s" (Printexc.to_string e));

     

       
234
       
-
       
                    []

     

       
235
       
-
       
                in

     

       
236
       
-
       
                { total = List.length data; data; next_cursor = None }

     

       
237
       
-
       
            | _ ->

     

       
238
       
-
       
                prerr_endline "Not an array at root level";

     

       
239
       
-
       
                { total = 0; data = []; next_cursor = None }

     

       
240
       
-
       
          end

     

       
241
       
-
       
        with e3 ->

     

       
242
       
-
       
          prerr_endline (Fmt.str "Third format parse error: %s" (Printexc.to_string e3));

     

       
243
       
 
       
          { total = 0; data = []; next_cursor = None }

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
244
       
 
       


     

       
245
       
 
       
(** Fetch bookmarks from a Karakeep instance with pagination support *)

     

       
246
       
 
       
let fetch_bookmarks ~sw ~env ~api_key ?(limit=50) ?(offset=0) ?cursor ?(include_content=false) ?filter_tags base_url =

     
···

       
259
       
 
       
          List.map (fun tag -> Uri.pct_encode ~component:`Query_key tag) tags

     

       
260
       
 
       
        in

     

       
261
       
 
       
        let tags_param = String.concat "," encoded_tags in

     

       
262
       
-
       
        prerr_endline (Fmt.str "Adding tags filter: %s" tags_param);

     

       
263
       
 
       
        url ^ "&tags=" ^ tags_param

     

       
264
       
 
       
    | _ -> url

     

       
265
       
 
       
  in

     
···

       
267
       
 
       
  let headers = Requests.Headers.empty

     

       
268
       
 
       
    |> Requests.Headers.set "Authorization" ("Bearer " ^ api_key) in

     

       
269
       
 
       


     

       
270
       
-
       
  prerr_endline (Fmt.str "Fetching bookmarks from: %s" url);

     

       
271
       
 
       


     

       
272
       
 
       
  try

     

       
273
       
 
       
    let response = Requests.One.get ~sw ~clock:env#clock ~net:env#net ~headers url in

     

       
274
       
 
       
    let status_code = Requests.Response.status_code response in

     

       
275
       
 
       
    if status_code = 200 then begin

     

       
276
       
 
       
      let body_str = Requests.Response.body response |> Eio.Flow.read_all in

     

       
277
       
-
       
      prerr_endline (Fmt.str "Received %d bytes of response data" (String.length body_str));

     

       
278
       
 
       


     

       
279
       
 
       
      try

     

       
280
       
 
       
        let json = J.from_string body_str in

     

       
281
       
 
       
        parse_bookmark_response json

     

       
282
       
 
       
      with e ->

     

       
283
       
-
       
        prerr_endline (Fmt.str "JSON parsing error: %s" (Printexc.to_string e));

     

       
284
       
-
       
        prerr_endline (Fmt.str "Response body (first 200 chars): %s"

     

       
285
       
 
       
          (if String.length body_str > 200 then String.sub body_str 0 200 ^ "..." else body_str));

     

       
286
       
 
       
        raise e

     

       
287
       
 
       
    end else begin

     

       
288
       
-
       
      prerr_endline (Fmt.str "HTTP error %d" status_code);

     

       
289
       
 
       
      failwith (Fmt.str "HTTP error: %d" status_code)

     

       
290
       
 
       
    end

     

       
291
       
 
       
  with e ->

     

       
292
       
-
       
    prerr_endline (Fmt.str "Network error: %s" (Printexc.to_string e));

     

       
293
       
 
       
    raise e

     

       
294
       
 
       


     

       
295
       
 
       
(** Fetch all bookmarks from a Karakeep instance using pagination *)

     

       
296
       
-
       
let fetch_all_bookmarks ~sw ~env ~api_key ?(page_size=50) ?max_pages ?filter_tags ?(include_content=false) base_url =

     

       
297
       
-
       
  let rec fetch_pages page_num cursor acc _total_count =

     

       
298
       
-
       
    let response =

     

       
299
       
-
       
      match cursor with

     

       
300
       
-
       
      | Some cursor_str -> fetch_bookmarks ~sw ~env ~api_key ~limit:page_size ~cursor:cursor_str ~include_content ?filter_tags base_url

     

       
301
       
-
       
      | None -> fetch_bookmarks ~sw ~env ~api_key ~limit:page_size ~offset:(page_num * page_size) ~include_content ?filter_tags base_url

     

       
0
       
 
       

     

       
0
       
 
       

     

       
302
       
 
       
    in

     

       
303
       
 
       


     

       
304
       
-
       
    let all_bookmarks = acc @ response.data in

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
305
       
 
       


     

       
306
       
-
       
    let more_available =

     

       
307
       
-
       
      match response.next_cursor with

     

       
308
       
-
       
      | Some _ -> true

     

       
309
       
-
       
      | None ->

     

       
310
       
-
       
          let fetched_count = (page_num * page_size) + List.length response.data in

     

       
311
       
-
       
          fetched_count < response.total

     

       
312
       
-
       
    in

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
313
       
 
       


     

       
314
       
-
       
    let under_max_pages = match max_pages with

     

       
315
       
-
       
      | None -> true

     

       
316
       
-
       
      | Some max -> page_num + 1 < max

     

       
317
       
-
       
    in

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
318
       
 
       


     

       
319
       
-
       
    if more_available && under_max_pages then

     

       
320
       
-
       
      fetch_pages (page_num + 1) response.next_cursor all_bookmarks response.total

     

       
321
       
-
       
    else

     

       
322
       
-
       
      all_bookmarks

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
323
       
 
       
  in

     

       
324
       
-
       
  fetch_pages 0 None [] 0

     

       
325
       
 
       


     

       
326
       
 
       
(** Fetch detailed information for a single bookmark by ID *)

     

       
327
       
 
       
let fetch_bookmark_details ~sw ~env ~api_key base_url bookmark_id =

     

···

       
2
       
 
       


     

       
3
       
 
       
module J = Ezjsonm

     

       
4
       
 
       


     

       
5
       
+
       
let src = Logs.Src.create "karakeepe" ~doc:"Karakeepe API client"

     

       
6
       
+
       
module Log = (val Logs.src_log src : Logs.LOG)

     

       
7
       
+
       


     

       
8
       
 
       
(** Type representing a Karakeep bookmark *)

     

       
9
       
 
       
type bookmark = {

     

       
10
       
 
       
  id: string;

     
···

       
66
       
 
       
  let id =

     

       
67
       
 
       
    try J.find json ["id"] |> J.get_string

     

       
68
       
 
       
    with e ->

     

       
69
       
+
       
      Log.err (fun m -> m "Error parsing bookmark ID: %s@.JSON: %s"

     

       
70
       
+
       
        (Printexc.to_string e) (J.value_to_string json));

     

       
71
       
 
       
      failwith "Unable to parse bookmark ID"

     

       
72
       
 
       
  in

     

       
73
       
 
       


     
···

       
91
       
 
       
              | Some (`String id) -> "karakeep-asset://" ^ id

     

       
92
       
 
       
              | _ -> failwith "No URL or asset ID found in bookmark"))

     

       
93
       
 
       
      | _ ->

     

       
94
       
+
       
          Log.err (fun m -> m "No URL found in bookmark@.JSON structure: %s"

     

       
95
       
+
       
            (J.value_to_string json));

     

       
96
       
 
       
          failwith "No URL found in bookmark"

     

       
97
       
 
       
  in

     

       
98
       
 
       


     
···

       
156
       
 
       
  { id; title; url; note; created_at; updated_at; favourited; archived; tags;

     

       
157
       
 
       
    tagging_status; summary; content; assets }

     

       
158
       
 
       


     

       
159
       
+
       
(** Parse a Karakeep bookmark response - handles multiple API response formats *)

     

       
160
       
 
       
let parse_bookmark_response json =

     

       
161
       
+
       
  Log.debug (fun m -> m "Parsing API response: %s" (J.value_to_string json));

     

       
162
       
 
       


     

       
163
       
+
       
  (* Try format 1: {total: int, data: [...], nextCursor?: string} *)

     

       
164
       
+
       
  let try_format1 () =

     

       
165
       
+
       
    Log.debug (fun m -> m "Trying format 1: {total, data, nextCursor}");

     

       
166
       
 
       
    let total = J.find json ["total"] |> J.get_int in

     

       
167
       
 
       
    let bookmarks_json = J.find json ["data"] in

     

       
0
       
 
       

     

       
168
       
 
       
    let data = J.get_list parse_bookmark bookmarks_json in

     

       
169
       
 
       
    let next_cursor =

     

       
170
       
 
       
      try Some (J.find json ["nextCursor"] |> J.get_string)

     

       
171
       
 
       
      with _ -> None

     

       
172
       
 
       
    in

     

       
173
       
+
       
    Log.debug (fun m -> m "Successfully parsed format 1: %d bookmarks" (List.length data));

     

       
174
       
 
       
    { total; data; next_cursor }

     

       
175
       
+
       
  in

     

       
176
       
+
       


     

       
177
       
+
       
  (* Try format 2: {bookmarks: [...], nextCursor?: string} - no total field *)

     

       
178
       
+
       
  let try_format2 () =

     

       
179
       
+
       
    Log.debug (fun m -> m "Trying format 2: {bookmarks, nextCursor}");

     

       
180
       
+
       
    let bookmarks_json = J.find json ["bookmarks"] in

     

       
181
       
+
       
    let data = J.get_list parse_bookmark bookmarks_json in

     

       
182
       
+
       
    let next_cursor =

     

       
183
       
+
       
      try Some (J.find json ["nextCursor"] |> J.get_string)

     

       
184
       
+
       
      with _ -> None

     

       
185
       
+
       
    in

     

       
186
       
+
       
    (* Calculate total from data length when total field is missing *)

     

       
187
       
+
       
    let total = List.length data in

     

       
188
       
+
       
    Log.debug (fun m -> m "Successfully parsed format 2: %d bookmarks" total);

     

       
189
       
+
       
    { total; data; next_cursor }

     

       
190
       
+
       
  in

     

       
191
       
+
       


     

       
192
       
+
       
  (* Try format 3: API error response {error: string, message?: string} *)

     

       
193
       
+
       
  let try_error_format () =

     

       
194
       
+
       
    Log.debug (fun m -> m "Checking for API error response");

     

       
195
       
+
       
    let error = J.find json ["error"] |> J.get_string in

     

       
196
       
+
       
    let message =

     

       
197
       
+
       
      try J.find json ["message"] |> J.get_string

     

       
198
       
+
       
      with _ -> "Unknown error"

     

       
199
       
+
       
    in

     

       
200
       
+
       
    Log.err (fun m -> m "API returned error: %s - %s" error message);

     

       
201
       
+
       
    { total = 0; data = []; next_cursor = None }

     

       
202
       
+
       
  in

     

       
203
       
+
       


     

       
204
       
+
       
  (* Try format 4: Plain array at root level *)

     

       
205
       
+
       
  let try_array_format () =

     

       
206
       
+
       
    Log.debug (fun m -> m "Trying format 4: array at root");

     

       
207
       
+
       
    match json with

     

       
208
       
+
       
    | `A _ ->

     

       
209
       
+
       
        let data = J.get_list parse_bookmark json in

     

       
210
       
+
       
        Log.debug (fun m -> m "Successfully parsed array format: %d bookmarks" (List.length data));

     

       
211
       
+
       
        { total = List.length data; data; next_cursor = None }

     

       
212
       
+
       
    | _ -> raise Not_found

     

       
213
       
+
       
  in

     

       
214
       
+
       


     

       
215
       
+
       
  (* Try each format in order *)

     

       
216
       
+
       
  try try_format1 ()

     

       
217
       
+
       
  with _ -> (

     

       
218
       
+
       
    try try_format2 ()

     

       
219
       
+
       
    with _ -> (

     

       
220
       
+
       
      try try_error_format ()

     

       
221
       
+
       
      with _ -> (

     

       
222
       
+
       
        try try_array_format ()

     

       
223
       
+
       
        with _ ->

     

       
224
       
+
       
          Log.err (fun m -> m "Failed to parse response in any known format");

     

       
225
       
+
       
          Log.debug (fun m -> m "JSON keys: %s"

     

       
226
       
 
       
            (match json with

     

       
227
       
+
       
             | `O fields -> String.concat ", " (List.map fst fields)

     

       
228
       
 
       
             | _ -> "not an object"));

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
229
       
 
       
          { total = 0; data = []; next_cursor = None }

     

       
230
       
+
       
      )

     

       
231
       
+
       
    )

     

       
232
       
+
       
  )

     

       
233
       
 
       


     

       
234
       
 
       
(** Fetch bookmarks from a Karakeep instance with pagination support *)

     

       
235
       
 
       
let fetch_bookmarks ~sw ~env ~api_key ?(limit=50) ?(offset=0) ?cursor ?(include_content=false) ?filter_tags base_url =

     
···

       
248
       
 
       
          List.map (fun tag -> Uri.pct_encode ~component:`Query_key tag) tags

     

       
249
       
 
       
        in

     

       
250
       
 
       
        let tags_param = String.concat "," encoded_tags in

     

       
251
       
+
       
        Log.debug (fun m -> m "Adding tags filter: %s" tags_param);

     

       
252
       
 
       
        url ^ "&tags=" ^ tags_param

     

       
253
       
 
       
    | _ -> url

     

       
254
       
 
       
  in

     
···

       
256
       
 
       
  let headers = Requests.Headers.empty

     

       
257
       
 
       
    |> Requests.Headers.set "Authorization" ("Bearer " ^ api_key) in

     

       
258
       
 
       


     

       
259
       
+
       
  Log.debug (fun m -> m "Fetching bookmarks from: %s" url);

     

       
260
       
 
       


     

       
261
       
 
       
  try

     

       
262
       
 
       
    let response = Requests.One.get ~sw ~clock:env#clock ~net:env#net ~headers url in

     

       
263
       
 
       
    let status_code = Requests.Response.status_code response in

     

       
264
       
 
       
    if status_code = 200 then begin

     

       
265
       
 
       
      let body_str = Requests.Response.body response |> Eio.Flow.read_all in

     

       
266
       
+
       
      Log.debug (fun m -> m "Received %d bytes of response data" (String.length body_str));

     

       
267
       
 
       


     

       
268
       
 
       
      try

     

       
269
       
 
       
        let json = J.from_string body_str in

     

       
270
       
 
       
        parse_bookmark_response json

     

       
271
       
 
       
      with e ->

     

       
272
       
+
       
        Log.err (fun m -> m "JSON parsing error: %s" (Printexc.to_string e));

     

       
273
       
+
       
        Log.debug (fun m -> m "Response body (first 200 chars): %s"

     

       
274
       
 
       
          (if String.length body_str > 200 then String.sub body_str 0 200 ^ "..." else body_str));

     

       
275
       
 
       
        raise e

     

       
276
       
 
       
    end else begin

     

       
277
       
+
       
      Log.err (fun m -> m "HTTP error %d" status_code);

     

       
278
       
 
       
      failwith (Fmt.str "HTTP error: %d" status_code)

     

       
279
       
 
       
    end

     

       
280
       
 
       
  with e ->

     

       
281
       
+
       
    Log.err (fun m -> m "Network error: %s" (Printexc.to_string e));

     

       
282
       
 
       
    raise e

     

       
283
       
 
       


     

       
284
       
 
       
(** Fetch all bookmarks from a Karakeep instance using pagination *)

     

       
285
       
+
       
let fetch_all_bookmarks ~sw ~env ~api_key ?(page_size=50) ?max_pages ?max_bookmarks ?filter_tags ?(include_content=false) base_url =

     

       
286
       
+
       
  let rec fetch_pages page_num cursor acc =

     

       
287
       
+
       
    (* Check if we've reached the max_bookmarks limit *)

     

       
288
       
+
       
    let reached_limit = match max_bookmarks with

     

       
289
       
+
       
      | Some max when List.length acc >= max ->

     

       
290
       
+
       
          Log.debug (fun m -> m "Reached max_bookmarks limit (%d)" max);

     

       
291
       
+
       
          true

     

       
292
       
+
       
      | _ -> false

     

       
293
       
 
       
    in

     

       
294
       
 
       


     

       
295
       
+
       
    if reached_limit then

     

       
296
       
+
       
      acc

     

       
297
       
+
       
    else begin

     

       
298
       
+
       
      Log.debug (fun m -> m "Fetching page %d" page_num);

     

       
299
       
+
       
      let response =

     

       
300
       
+
       
        match cursor with

     

       
301
       
+
       
        | Some cursor_str -> fetch_bookmarks ~sw ~env ~api_key ~limit:page_size ~cursor:cursor_str ~include_content ?filter_tags base_url

     

       
302
       
+
       
        | None -> fetch_bookmarks ~sw ~env ~api_key ~limit:page_size ~offset:(page_num * page_size) ~include_content ?filter_tags base_url

     

       
303
       
+
       
      in

     

       
304
       
 
       


     

       
305
       
+
       
      let all_bookmarks = acc @ response.data in

     

       
306
       
+
       
      Log.debug (fun m -> m "Fetched %d bookmarks this page, %d total so far"

     

       
307
       
+
       
        (List.length response.data) (List.length all_bookmarks));

     

       
308
       
+
       


     

       
309
       
+
       
      (* Truncate to max_bookmarks if needed *)

     

       
310
       
+
       
      let all_bookmarks = match max_bookmarks with

     

       
311
       
+
       
        | Some max when List.length all_bookmarks > max ->

     

       
312
       
+
       
            Log.debug (fun m -> m "Truncating to max_bookmarks (%d)" max);

     

       
313
       
+
       
            List.filteri (fun i _ -> i < max) all_bookmarks

     

       
314
       
+
       
        | _ -> all_bookmarks

     

       
315
       
+
       
      in

     

       
316
       
+
       


     

       
317
       
+
       
      (* Determine if more pages are available:

     

       
318
       
+
       
         - If next_cursor is present, there are definitely more pages

     

       
319
       
+
       
         - If no next_cursor and we got fewer items than page_size, we're done

     

       
320
       
+
       
         - If no next_cursor and total is reliable (> current count), there may be more *)

     

       
321
       
+
       
      let more_available =

     

       
322
       
+
       
        match response.next_cursor with

     

       
323
       
+
       
        | Some _ ->

     

       
324
       
+
       
            Log.debug (fun m -> m "More pages available (next_cursor present)");

     

       
325
       
+
       
            true

     

       
326
       
+
       
        | None ->

     

       
327
       
+
       
            let current_count = List.length all_bookmarks in

     

       
328
       
+
       
            let got_full_page = List.length response.data = page_size in

     

       
329
       
+
       
            let total_indicates_more = response.total > current_count in

     

       
330
       
+
       
            (* If we got a full page and total indicates more, continue *)

     

       
331
       
+
       
            let has_more = got_full_page && total_indicates_more in

     

       
332
       
+
       
            if has_more then

     

       
333
       
+
       
              Log.debug (fun m -> m "More pages likely available (%d fetched < %d total)"

     

       
334
       
+
       
                current_count response.total)

     

       
335
       
+
       
            else

     

       
336
       
+
       
              Log.debug (fun m -> m "No more pages (got %d items, total=%d)"

     

       
337
       
+
       
                (List.length response.data) response.total);

     

       
338
       
+
       
            has_more

     

       
339
       
+
       
      in

     

       
340
       
 
       


     

       
341
       
+
       
      let under_max_pages = match max_pages with

     

       
342
       
+
       
        | None -> true

     

       
343
       
+
       
        | Some max -> page_num + 1 < max

     

       
344
       
+
       
      in

     

       
345
       
+
       


     

       
346
       
+
       
      let under_max_bookmarks = match max_bookmarks with

     

       
347
       
+
       
        | None -> true

     

       
348
       
+
       
        | Some max -> List.length all_bookmarks < max

     

       
349
       
+
       
      in

     

       
350
       
 
       


     

       
351
       
+
       
      if more_available && under_max_pages && under_max_bookmarks then

     

       
352
       
+
       
        fetch_pages (page_num + 1) response.next_cursor all_bookmarks

     

       
353
       
+
       
      else begin

     

       
354
       
+
       
        Log.debug (fun m -> m "Pagination complete: fetched %d total bookmarks" (List.length all_bookmarks));

     

       
355
       
+
       
        all_bookmarks

     

       
356
       
+
       
      end

     

       
357
       
+
       
    end

     

       
358
       
 
       
  in

     

       
359
       
+
       
  fetch_pages 0 None []

     

       
360
       
 
       


     

       
361
       
 
       
(** Fetch detailed information for a single bookmark by ID *)

     

       
362
       
 
       
let fetch_bookmark_details ~sw ~env ~api_key base_url bookmark_id =

     

···

       
59
       
 
       
    @param api_key API key for authentication

     

       
60
       
 
       
    @param page_size Number of bookmarks to fetch per page (default: 50)

     

       
61
       
 
       
    @param max_pages Maximum number of pages to fetch (None for all pages)

     

       
0
       
 
       

     

       
62
       
 
       
    @param filter_tags Optional list of tags to filter by

     

       
63
       
 
       
    @param include_content Whether to include full content (default: false)

     

       
64
       
 
       
    @param base_url Base URL of the Karakeep instance

     
···

       
69
       
 
       
  api_key:string ->

     

       
70
       
 
       
  ?page_size:int ->

     

       
71
       
 
       
  ?max_pages:int ->

     

       
0
       
 
       

     

       
72
       
 
       
  ?filter_tags:string list ->

     

       
73
       
 
       
  ?include_content:bool ->

     

       
74
       
 
       
  string ->

     

···

       
59
       
 
       
    @param api_key API key for authentication

     

       
60
       
 
       
    @param page_size Number of bookmarks to fetch per page (default: 50)

     

       
61
       
 
       
    @param max_pages Maximum number of pages to fetch (None for all pages)

     

       
62
       
+
       
    @param max_bookmarks Maximum total number of bookmarks to return (None for all)

     

       
63
       
 
       
    @param filter_tags Optional list of tags to filter by

     

       
64
       
 
       
    @param include_content Whether to include full content (default: false)

     

       
65
       
 
       
    @param base_url Base URL of the Karakeep instance

     
···

       
70
       
 
       
  api_key:string ->

     

       
71
       
 
       
  ?page_size:int ->

     

       
72
       
 
       
  ?max_pages:int ->

     

       
73
       
+
       
  ?max_bookmarks:int ->

     

       
74
       
 
       
  ?filter_tags:string list ->

     

       
75
       
 
       
  ?include_content:bool ->

     

       
76
       
 
       
  string ->

     

···

       
87
       
 
       
      (* config is now <fs:$HOME/.config/myapp> or the overridden path *)

     

       
88
       
 
       
    ]}

     

       
89
       
 
       
    

     

       
90
       
-
       
    {b Note:} All directories are created with permissions 0o755 if they don't exist,

     

       
91
       
 
       
    except for runtime directories which are created with 0o700 permissions and

     

       
92
       
 
       
    validated according to the XDG specification.

     

       
93
       
 
       
    

     
···

       
114
       
 
       
    - [XDG_CONFIG_HOME]: XDG standard variable

     

       
115
       
 
       
    - Default: [$HOME/.config/{app_name}]

     

       
116
       
 
       
    

     

       
117
       
-
       
    {b Example Files:}

     

       
118
       
-
       
    - Application settings (e.g., [config.toml], [settings.json])

     

       
119
       
-
       
    - User preferences

     

       
120
       
-
       
    - UI customizations

     

       
121
       
-
       
    

     

       
122
       
 
       
    @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> XDG_CONFIG_HOME specification *)

     

       
123
       
 
       
val config_dir : t -> Eio.Fs.dir_ty Eio.Path.t

     

       
124
       
 
       


     
···

       
159
       
 
       
    - Network response caches

     

       
160
       
 
       
    - Temporary computation results

     

       
161
       
 
       
    

     

       
162
       
-
       
    {b Note:} Users may clear cache directories to free disk space, so

     

       
163
       
 
       
    always check for cache validity and be prepared to regenerate data.

     

       
164
       
 
       
    

     

       
165
       
 
       
    @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> XDG_CACHE_HOME specification *)

     
···

       
214
       
 
       
    - Lock files

     

       
215
       
 
       
    - Small process communication files

     

       
216
       
 
       
    

     

       
217
       
-
       
    {b Important:} This may return [None] if no suitable runtime directory

     

       
218
       
 
       
    is available. Applications should handle this gracefully, perhaps by

     

       
219
       
 
       
    falling back to [/tmp] with appropriate security measures.

     

       
220
       
 
       
    

     
···

       
239
       
 
       
    precedence over later ones. When looking for a configuration file,

     

       
240
       
 
       
    search {!config_dir} first, then each directory in this list.

     

       
241
       
 
       
    

     

       
242
       
-
       
    {b Example Usage:}

     

       
243
       
-
       
    - System-wide default configurations

     

       
244
       
-
       
    - Distribution-provided settings

     

       
245
       
-
       
    - Site-wide customizations

     

       
246
       
-
       
    

     

       
247
       
 
       
    @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> XDG_CONFIG_DIRS specification *)

     

       
248
       
 
       
val config_dirs : t -> Eio.Fs.dir_ty Eio.Path.t list

     

       
249
       
 
       


     
···

       
290
       
 
       
    1. User config directory ({!config_dir})

     

       
291
       
 
       
    2. System config directories ({!config_dirs}) in preference order

     

       
292
       
 
       
    

     

       
293
       
-
       
    {b Example:}

     

       
294
       
-
       
    {[

     

       
295
       
-
       
      match Xdge.find_config_file xdg "myapp.conf" with

     

       
296
       
-
       
      | Some path -> Printf.printf "Found config at: %s\n" (Eio.Path.native_exn path)

     

       
297
       
-
       
      | None -> Printf.printf "No config file found\n"

     

       
298
       
-
       
    ]} *)

     

       
299
       
 
       
val find_config_file : t -> string -> Eio.Fs.dir_ty Eio.Path.t option

     

       
300
       
 
       


     

       
301
       
 
       
(** [find_data_file t filename] searches for a data file following XDG precedence.

     
···

       
313
       
 
       
    1. User data directory ({!data_dir})

     

       
314
       
 
       
    2. System data directories ({!data_dirs}) in preference order

     

       
315
       
 
       
    

     

       
316
       
-
       
    {b Example:}

     

       
317
       
-
       
    {[

     

       
318
       
-
       
      match Xdge.find_data_file xdg "templates/default.txt" with

     

       
319
       
-
       
      | Some path -> (* read from path *)

     

       
320
       
-
       
      | None -> (* use built-in default *)

     

       
321
       
-
       
    ]} *)

     

       
322
       
 
       
val find_data_file : t -> string -> Eio.Fs.dir_ty Eio.Path.t option

     

       
323
       
 
       


     

       
324
       
 
       
(** {1 Pretty Printing} *)

     
···

       
336
       
 
       
    - Normal: Multi-line detailed view of all directories

     

       
337
       
 
       
    - Brief: Single line showing app name and key directories

     

       
338
       
 
       
    - With sources: Adds annotations showing where each path came from

     

       
339
       
-
       
    

     

       
340
       
-
       
    {b Example:}

     

       
341
       
-
       
    {[

     

       
342
       
-
       
      (* Normal output *)

     

       
343
       
-
       
      Format.printf "%a" Xdge.pp xdg

     

       
344
       
-
       
      

     

       
345
       
-
       
      (* Brief output *)

     

       
346
       
-
       
      Format.printf "%a" (Xdge.pp ~brief:true) xdg

     

       
347
       
-
       
      

     

       
348
       
-
       
      (* Show sources *)

     

       
349
       
-
       
      Format.printf "%a" (Xdge.pp ~sources:true) xdg

     

       
350
       
-
       
    ]} *)

     

       
351
       
 
       
val pp : ?brief:bool -> ?sources:bool -> Format.formatter -> t -> unit

     

       
352
       
 
       


     

       
353
       
 
       
(** {1 Cmdliner Integration} *)

     
···

       
357
       
 
       
  type xdg_t = t

     

       
358
       
 
       
  (** Cmdliner integration for XDG directory configuration.

     

       
359
       
 
       
      

     

       
360
       
-
       
      This module provides seamless integration with the Cmdliner library,

     

       
361
       
 
       
      allowing XDG directories to be configured via command-line arguments

     

       
362
       
-
       
      while respecting the precedence of environment variables.

     

       
363
       
-
       
      

     

       
364
       
-
       
      {b Features:}

     

       
365
       
-
       
      - Automatic command-line flag generation for each directory type

     

       
366
       
-
       
      - Environment variable detection and precedence handling

     

       
367
       
-
       
      - Source tracking for debugging configuration issues

     

       
368
       
-
       
      - Pretty printing of configuration for --help output *)

     

       
369
       
 
       


     

       
370
       
-
       
  (** Complete XDG configuration gathered from command-line and environment.

     

       
371
       
 
       
      

     

       
372
       
 
       
      This contains all XDG directory paths along with their sources,

     

       
373
       
 
       
      as determined by command-line arguments and environment variables. *)

     
···

       
398
       
 
       
      + Application-specific variable (e.g., [MYAPP_CONFIG_DIR])

     

       
399
       
 
       
      + XDG standard variable (e.g., [XDG_CONFIG_HOME])

     

       
400
       
 
       
      + Default value

     

       
401
       
-
       


     

       
402
       
-
       
      {b Example - All directories:}

     

       
403
       
-
       
      {[

     

       
404
       
-
       
        let open Cmdliner in

     

       
405
       
-
       
        let xdg_term = Cmd.term "myapp" env#fs () in

     

       
406
       
-
       
        let main_term = Term.(const main $ xdg_term $ other_args) in

     

       
407
       
-
       
        (* ... *)

     

       
408
       
-
       
      ]}

     

       
409
       
-
       


     

       
410
       
-
       
      {b Example - Only cache directory:}

     

       
411
       
-
       
      {[

     

       
412
       
-
       
        let open Cmdliner in

     

       
413
       
-
       
        let xdg_term = Cmd.term "myapp" env#fs ~dirs:[`Cache] () in

     

       
414
       
-
       
        let main_term = Term.(const main $ xdg_term $ other_args) in

     

       
415
       
-
       
        (* ... *)

     

       
416
       
-
       
      ]} *)

     

       
417
       
 
       
  val term : string -> Eio.Fs.dir_ty Eio.Path.t ->

     

       
418
       
 
       
    ?dirs:dir list ->

     

       
419
       
 
       
    unit -> (xdg_t * t) Cmdliner.Term.t

     
···

       
435
       
 
       
      + Application-specific variable (e.g., [MYAPP_CACHE_DIR])

     

       
436
       
 
       
      + XDG standard variable ([XDG_CACHE_HOME])

     

       
437
       
 
       
      + Default value ([$HOME/.cache/{app_name}])

     

       
438
       
-
       


     

       
439
       
-
       
      {b Example:}

     

       
440
       
-
       
      {[

     

       
441
       
-
       
        let cache_dir_term = Xdge.Cmd.cache_term "myapp" in

     

       
442
       
-
       
        let main cache_dir other_args =

     

       
443
       
-
       
          (* use cache_dir as a string path *)

     

       
444
       
-
       
        in

     

       
445
       
-
       
        let main_term = Term.(const main $ cache_dir_term $ other_args) in

     

       
446
       
-
       
      ]} *)

     

       
447
       
 
       
  val cache_term : string -> string Cmdliner.Term.t

     

       
448
       
 
       


     

       
449
       
 
       
  (** [env_docs app_name] generates documentation for environment variables.

     
···

       
460
       
 
       
      - Application-specific environment variables

     

       
461
       
 
       
      - XDG standard environment variables

     

       
462
       
 
       
      - Default values for each directory type

     

       
463
       
-
       
      

     

       
464
       
-
       
      {b Example:}

     

       
465
       
-
       
      {[

     

       
466
       
-
       
        let env_section = Cmdliner.Cmd.Env.info (env_docs "myapp")

     

       
467
       
-
       
      ]} *)

     

       
468
       
 
       
  val env_docs : string -> string

     

       
469
       
 
       


     

       
470
       
 
       
  (** [pp ppf config] pretty prints a Cmdliner configuration.

     
···

       
474
       
 
       
      issues or displaying the current configuration to users.

     

       
475
       
 
       
      

     

       
476
       
 
       
      @param ppf The formatter to print to

     

       
477
       
-
       
      @param config The configuration to print

     

       
478
       
-
       
      

     

       
479
       
-
       
      {b Output Format:}

     

       
480
       
-
       
      Shows each directory with its path (if set) and source annotation

     

       
481
       
-
       
      in a color-coded format for easy reading. *)

     

       
482
       
 
       
  val pp : Format.formatter -> t -> unit

     

       
483
       
 
       
end

     

···

       
87
       
 
       
      (* config is now <fs:$HOME/.config/myapp> or the overridden path *)

     

       
88
       
 
       
    ]}

     

       
89
       
 
       
    

     

       
90
       
+
       
    All directories are created with permissions 0o755 if they don't exist,

     

       
91
       
 
       
    except for runtime directories which are created with 0o700 permissions and

     

       
92
       
 
       
    validated according to the XDG specification.

     

       
93
       
 
       
    

     
···

       
114
       
 
       
    - [XDG_CONFIG_HOME]: XDG standard variable

     

       
115
       
 
       
    - Default: [$HOME/.config/{app_name}]

     

       
116
       
 
       
    

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
117
       
 
       
    @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> XDG_CONFIG_HOME specification *)

     

       
118
       
 
       
val config_dir : t -> Eio.Fs.dir_ty Eio.Path.t

     

       
119
       
 
       


     
···

       
154
       
 
       
    - Network response caches

     

       
155
       
 
       
    - Temporary computation results

     

       
156
       
 
       
    

     

       
157
       
+
       
    Users may clear cache directories to free disk space, so

     

       
158
       
 
       
    always check for cache validity and be prepared to regenerate data.

     

       
159
       
 
       
    

     

       
160
       
 
       
    @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> XDG_CACHE_HOME specification *)

     
···

       
209
       
 
       
    - Lock files

     

       
210
       
 
       
    - Small process communication files

     

       
211
       
 
       
    

     

       
212
       
+
       
    This may return [None] if no suitable runtime directory

     

       
213
       
 
       
    is available. Applications should handle this gracefully, perhaps by

     

       
214
       
 
       
    falling back to [/tmp] with appropriate security measures.

     

       
215
       
 
       
    

     
···

       
234
       
 
       
    precedence over later ones. When looking for a configuration file,

     

       
235
       
 
       
    search {!config_dir} first, then each directory in this list.

     

       
236
       
 
       
    

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
237
       
 
       
    @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> XDG_CONFIG_DIRS specification *)

     

       
238
       
 
       
val config_dirs : t -> Eio.Fs.dir_ty Eio.Path.t list

     

       
239
       
 
       


     
···

       
280
       
 
       
    1. User config directory ({!config_dir})

     

       
281
       
 
       
    2. System config directories ({!config_dirs}) in preference order

     

       
282
       
 
       
    

     

       
283
       
+
       
    *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
284
       
 
       
val find_config_file : t -> string -> Eio.Fs.dir_ty Eio.Path.t option

     

       
285
       
 
       


     

       
286
       
 
       
(** [find_data_file t filename] searches for a data file following XDG precedence.

     
···

       
298
       
 
       
    1. User data directory ({!data_dir})

     

       
299
       
 
       
    2. System data directories ({!data_dirs}) in preference order

     

       
300
       
 
       
    

     

       
301
       
+
       
    *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
302
       
 
       
val find_data_file : t -> string -> Eio.Fs.dir_ty Eio.Path.t option

     

       
303
       
 
       


     

       
304
       
 
       
(** {1 Pretty Printing} *)

     
···

       
316
       
 
       
    - Normal: Multi-line detailed view of all directories

     

       
317
       
 
       
    - Brief: Single line showing app name and key directories

     

       
318
       
 
       
    - With sources: Adds annotations showing where each path came from

     

       
319
       
+
       
    *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
320
       
 
       
val pp : ?brief:bool -> ?sources:bool -> Format.formatter -> t -> unit

     

       
321
       
 
       


     

       
322
       
 
       
(** {1 Cmdliner Integration} *)

     
···

       
326
       
 
       
  type xdg_t = t

     

       
327
       
 
       
  (** Cmdliner integration for XDG directory configuration.

     

       
328
       
 
       
      

     

       
329
       
+
       
      This module provides integration with the Cmdliner library,

     

       
330
       
 
       
      allowing XDG directories to be configured via command-line arguments

     

       
331
       
+
       
      while respecting the precedence of environment variables. *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
332
       
 
       


     

       
333
       
+
       
  (** Type of XDG configuration gathered from command-line and environment.

     

       
334
       
 
       
      

     

       
335
       
 
       
      This contains all XDG directory paths along with their sources,

     

       
336
       
 
       
      as determined by command-line arguments and environment variables. *)

     
···

       
361
       
 
       
      + Application-specific variable (e.g., [MYAPP_CONFIG_DIR])

     

       
362
       
 
       
      + XDG standard variable (e.g., [XDG_CONFIG_HOME])

     

       
363
       
 
       
      + Default value

     

       
364
       
+
       
      *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
365
       
 
       
  val term : string -> Eio.Fs.dir_ty Eio.Path.t ->

     

       
366
       
 
       
    ?dirs:dir list ->

     

       
367
       
 
       
    unit -> (xdg_t * t) Cmdliner.Term.t

     
···

       
383
       
 
       
      + Application-specific variable (e.g., [MYAPP_CACHE_DIR])

     

       
384
       
 
       
      + XDG standard variable ([XDG_CACHE_HOME])

     

       
385
       
 
       
      + Default value ([$HOME/.cache/{app_name}])

     

       
386
       
+
       
      *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
387
       
 
       
  val cache_term : string -> string Cmdliner.Term.t

     

       
388
       
 
       


     

       
389
       
 
       
  (** [env_docs app_name] generates documentation for environment variables.

     
···

       
400
       
 
       
      - Application-specific environment variables

     

       
401
       
 
       
      - XDG standard environment variables

     

       
402
       
 
       
      - Default values for each directory type

     

       
403
       
+
       
      *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
404
       
 
       
  val env_docs : string -> string

     

       
405
       
 
       


     

       
406
       
 
       
  (** [pp ppf config] pretty prints a Cmdliner configuration.

     
···

       
410
       
 
       
      issues or displaying the current configuration to users.

     

       
411
       
 
       
      

     

       
412
       
 
       
      @param ppf The formatter to print to

     

       
413
       
+
       
      @param config The configuration to print *)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
414
       
 
       
  val pp : Format.formatter -> t -> unit

     

       
415
       
 
       
end