GPS Exchange Format library/CLI in OCaml
anil.recoil.org
1(** {1 Eio API for GPX operations}
2
3 This module provides a direct-style API for GPX operations using Eio's
4 effects-based concurrent I/O system. It offers convenient functions
5 for common GPX operations while maintaining structured concurrency.
6
7 {2 Usage Example}
8
9 {[
10 open Gpx_eio
11
12 let main env =
13 let fs = Eio.Stdenv.fs env in
14
15 (* Create a GPX document *)
16 let lat = Gpx.Coordinate.latitude 37.7749 |> Result.get_ok in
17 let lon = Gpx.Coordinate.longitude (-122.4194) |> Result.get_ok in
18 let wpt = Gpx.Waypoint.make lat lon |> Gpx.Waypoint.with_name "San Francisco" in
19 let gpx = Gpx.make_gpx ~creator:"eio-example" |> Gpx.Doc.add_waypoint wpt in
20
21 (* Write with validation *)
22 write ~validate:true fs "output.gpx" gpx;
23
24 (* Read it back *)
25 let gpx2 = read ~validate:true fs "output.gpx" in
26 Printf.printf "Read %d waypoints\n" (List.length (Gpx.Doc.waypoints gpx2))
27
28 let () = Eio_main.run main
29 ]}
30
31 {2 Module Re-exports} *)
32
33(* I/O module *)
34module IO = Gpx_io
35
36(** {2 Convenience File Operations}
37
38 These functions provide simple file I/O with the filesystem from {!Eio.Stdenv.fs}. *)
39
40(** Read and parse GPX file.
41 @param fs Filesystem capability
42 @param path File path to read
43 @param ?validate Optional validation flag (default: false)
44 @return GPX document
45 @raises Gpx.Gpx_error on read or parse failure *)
46val read : ?validate:bool -> fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.t
47
48(** Write GPX to file.
49 @param fs Filesystem capability
50 @param path File path to write
51 @param gpx GPX document to write
52 @param ?validate Optional validation flag (default: false)
53 @raises Gpx.Gpx_error on write failure *)
54val write : ?validate:bool -> fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.t -> unit
55
56(** Write GPX to file with automatic backup.
57 @param fs Filesystem capability
58 @param path File path to write
59 @param gpx GPX document to write
60 @param ?validate Optional validation flag (default: false)
61 @return Backup file path (empty if no backup created)
62 @raises Gpx.Gpx_error on failure *)
63val write_with_backup : ?validate:bool -> fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.t -> string
64
65(** {2 Stream Operations}
66
67 Operations for reading/writing GPX from/to Eio flows. *)
68
69(** Read GPX from Eio source.
70 @param source Input flow
71 @param ?validate Optional validation flag (default: false)
72 @return GPX document
73 @raises Gpx.Gpx_error on read or parse failure *)
74val from_source : ?validate:bool -> [> Eio.Flow.source_ty ] Eio.Resource.t -> Gpx.t
75
76(** Write GPX to Eio sink.
77 @param sink Output flow
78 @param gpx GPX document
79 @param ?validate Optional validation flag (default: false)
80 @raises Gpx.Gpx_error on write failure *)
81val to_sink : ?validate:bool -> [> Eio.Flow.sink_ty ] Eio.Resource.t -> Gpx.t -> unit
82
83(** Print GPX statistics to sink.
84 @param sink Output sink
85 @param gpx GPX document *)
86val print_stats : [> Eio.Flow.sink_ty ] Eio.Resource.t -> Gpx.t -> unit