patrick.sirref.org
1(** {1 GPX Eio - High-level Eio API for GPX operations}
2
3 This module provides a high-level 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 Key Features}
8
9 - Effects-based I/O using Eio
10 - Structured concurrency compatible
11 - Resource-safe operations
12 - Exception-based error handling (raises [Gpx.Gpx_error])
13 - Concurrent processing capabilities
14
15 {2 Usage Example}
16
17 {[
18 open Gpx_eio
19
20 let main env =
21 let fs = Eio.Stdenv.fs env in
22
23 (* Create a GPX document *)
24 let lat = Gpx.latitude 37.7749 |> Result.get_ok in
25 let lon = Gpx.longitude (-122.4194) |> Result.get_ok in
26 let wpt = make_waypoint fs ~lat:(Gpx.latitude_to_float lat) ~lon:(Gpx.longitude_to_float lon) ~name:"San Francisco" () in
27 let gpx = Gpx.make_gpx ~creator:"eio-example" in
28 let gpx = { gpx with waypoints = [wpt] } in
29
30 (* Write with validation *)
31 write_validated fs "output.gpx" gpx;
32
33 (* Read it back *)
34 let gpx2 = read_validated fs "output.gpx" in
35 Printf.printf "Read %d waypoints\n" (List.length gpx2.waypoints)
36
37 let () = Eio_main.run main
38 ]}
39
40 {2 Module Re-exports} *)
41
42(* I/O module *)
43module IO = Gpx_io
44
45(** {2 Convenience File Operations}
46
47 These functions provide simple file I/O with the filesystem from [Eio.Stdenv.fs]. *)
48
49(** Read and parse GPX file.
50 @param fs Filesystem capability
51 @param path File path to read
52 @return GPX document
53 @raises Gpx.Gpx_error on read or parse failure *)
54val read : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.gpx
55
56(** Read and parse GPX file with validation.
57 @param fs Filesystem capability
58 @param path File path to read
59 @return Valid GPX document
60 @raises Gpx.Gpx_error on validation failure *)
61val read_validated : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.gpx
62
63(** Write GPX to file.
64 @param fs Filesystem capability
65 @param path File path to write
66 @param gpx GPX document to write
67 @raises Gpx.Gpx_error on write failure *)
68val write : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.gpx -> unit
69
70(** Write GPX to file with validation.
71 @param fs Filesystem capability
72 @param path File path to write
73 @param gpx GPX document to write
74 @raises Gpx.Gpx_error on validation or write failure *)
75val write_validated : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.gpx -> unit
76
77(** Write GPX to file with automatic backup.
78 @param fs Filesystem capability
79 @param path File path to write
80 @param gpx GPX document to write
81 @return Backup file path (empty if no backup created)
82 @raises Gpx.Gpx_error on failure *)
83val write_with_backup : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> string -> Gpx.gpx -> string
84
85(** {2 Stream Operations}
86
87 Operations for reading/writing GPX from/to Eio flows. *)
88
89(** Read GPX from Eio source.
90 @param source Input flow
91 @return GPX document
92 @raises Gpx.Gpx_error on read or parse failure *)
93val from_source : [> Eio.Flow.source_ty ] Eio.Resource.t -> Gpx.gpx
94
95(** Write GPX to Eio sink.
96 @param sink Output flow
97 @param gpx GPX document
98 @raises Gpx.Gpx_error on write failure *)
99val to_sink : [> Eio.Flow.sink_ty ] Eio.Resource.t -> Gpx.gpx -> unit
100
101(** Read GPX from Eio source with validation.
102 @param source Input flow
103 @return Valid GPX document
104 @raises Gpx.Gpx_error on validation failure *)
105val from_source_validated : [> Eio.Flow.source_ty ] Eio.Resource.t -> Gpx.gpx
106
107(** Write GPX to Eio sink with validation.
108 @param sink Output flow
109 @param gpx GPX document
110 @raises Gpx.Gpx_error on validation failure *)
111val to_sink_validated : [> Eio.Flow.sink_ty ] Eio.Resource.t -> Gpx.gpx -> unit
112
113(** {2 Utility Functions} *)
114
115(** Create simple waypoint with coordinates.
116 @param fs Filesystem capability (unused, for API consistency)
117 @param lat Latitude in degrees
118 @param lon Longitude in degrees
119 @param ?name Optional waypoint name
120 @param ?desc Optional waypoint description
121 @return Waypoint data
122 @raises Gpx.Gpx_error on invalid coordinates *)
123val make_waypoint : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> lat:float -> lon:float -> ?name:string -> ?desc:string -> unit -> Gpx.waypoint_data
124
125(** Create track from coordinate list.
126 @param fs Filesystem capability (unused, for API consistency)
127 @param name Track name
128 @param coords List of (latitude, longitude) pairs
129 @return Track with single segment
130 @raises Gpx.Gpx_error on invalid coordinates *)
131val make_track_from_coords : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> name:string -> (float * float) list -> Gpx.track
132
133(** Create route from coordinate list.
134 @param fs Filesystem capability (unused, for API consistency)
135 @param name Route name
136 @param coords List of (latitude, longitude) pairs
137 @return Route
138 @raises Gpx.Gpx_error on invalid coordinates *)
139val make_route_from_coords : fs:[> Eio.Fs.dir_ty ] Eio.Path.t -> name:string -> (float * float) list -> Gpx.route
140
141(** Extract coordinates from waypoint.
142 @param wpt Waypoint data
143 @return (latitude, longitude) as floats *)
144val waypoint_coords : Gpx.waypoint_data -> float * float
145
146(** Extract coordinates from track.
147 @param track Track
148 @return List of (latitude, longitude) pairs *)
149val track_coords : Gpx.track -> (float * float) list
150
151(** Extract coordinates from route.
152 @param route Route
153 @return List of (latitude, longitude) pairs *)
154val route_coords : Gpx.route -> (float * float) list
155
156(** Count total points in GPX document.
157 @param gpx GPX document
158 @return Total number of waypoints, route points, and track points *)
159val count_points : Gpx.gpx -> int
160
161(** GPX statistics record *)
162type gpx_stats = {
163 waypoint_count : int; (** Number of waypoints *)
164 route_count : int; (** Number of routes *)
165 track_count : int; (** Number of tracks *)
166 total_points : int; (** Total geographic points *)
167 has_elevation : bool; (** Document contains elevation data *)
168 has_time : bool; (** Document contains time data *)
169}
170
171(** Get GPX document statistics.
172 @param gpx GPX document
173 @return Statistics summary *)
174val get_stats : Gpx.gpx -> gpx_stats
175
176(** Print GPX statistics to stdout.
177 @param gpx GPX document *)
178val print_stats : Gpx.gpx -> unit