aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBen Burwell <ben@benburwell.com>2020-02-06 15:04:34 -0500
committerBen Burwell <ben@benburwell.com>2020-02-06 15:04:34 -0500
commit8e1d9f44b2b2bc4031693855478f7201a7681053 (patch)
tree02e42178a5cbc42dacea9a47e79bff685a60011d
parent6baa9b5f53393171afdf3ebff7e6f4e505b0f57b (diff)
improve docsHEADmaster
-rw-r--r--README.md91
-rw-r--r--cmd/metar.go17
-rw-r--r--doc/wx.1.scd62
3 files changed, 156 insertions, 14 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a5a8e7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# `wx` - a command line interface for aviation weather
+
+`wx` fetches weather data from the NOAA Aviation Weather Center's Text Data
+Server (TDS).
+
+## Installation from source
+
+1. Clone the repository
+2. Run `sudo make install`
+
+## Usage
+
+Currently, we support fetching METARs in a variety of methods. When fetching
+METARs, a time constraint must be supplied. A time constraint can either be in
+the form "past x" or "between x and y".
+
+ $ wx metar --past 3h
+ $ wx metar --since 2020-01-01T00:00:00 --until 2020-01-02T00:00:00
+
+The `--past` argument defaults to `1h`, so if none of `--past`, `--since`, or
+`--until` are specified, METARs from the past hour will be fetched.
+
+Note that the TDS only stores METARs from the past three days, so the `wx`
+command cannot effectively be used to pull historical data.
+
+### For a set of stations
+
+You can fetch METARs from a set of stations by their full or partial ICAO IDs:
+
+ $ wx metar kbos
+ $ wx metar kbos ksea
+ $ wx metar kb
+
+### For stations in a region
+
+You can fetch METARs from all stations within a rectangular or radial region.
+Rectangular regions are specified by a `minLat,minLon,maxLat,maxLon` tuple:
+
+ $ wx metar --rect 39,-70,40,-71
+
+Radial regions are specified as a radius in statute miles around a center point
+as a `dist,lat,lon` tuple:
+
+ $ wx metar --radial 5.5,40,-70
+
+### For stations along a flight path
+
+You can fetch weather for all stations with a distance of a specified flight
+path. A flight path is specified by a series of `--waypoint` arguments, where
+each waypoint can be an ICAO identifier or a `lon,lat` tuple. Waypoints must be
+specified in order from origin to destination.
+
+ $ wx metar --path-dist 10 --waypoint ksea --waypoint kbos
+
+### Controlling density
+
+When running a query which will return METARs from many stations, it may be
+helpful to reduce the density of the results. This can be done with the
+`--min-dist` argument which specifies a minimum distance (in degrees of latitude
+or longitude) between stations to display. Providing a higher value for
+`--min-dist` will result in fewer stations being returned.
+
+ $ wx metar \
+ --path-dist 10 --waypoint ksea --waypoint kbos \
+ --min-dist 5 \
+
+### Filtering recency
+
+There are two mechanisms for filtering results by recency. First, you can
+request the single most recent METAR from all the stations being fetched:
+
+ $ wx metar --past 6h kbos ksea --most-recent
+
+Even though we've specified two stations, KBOS and KSEA, we'll only get a single
+METAR back from whichever of the two stations most recently made an observation.
+
+The second filtering mechanism is `--most-recent-by-station`. This argument can
+take several values:
+
+* `constraint` (default): request the most recent for each METAR station in the
+ fastest fashion.
+* `postfilter`: filter results after applying all other constraints.
+* `false`: don't filter results to only the most recent for each station.
+
+## Contributing
+
+Email patches to <mailto:~benburwell/patchall@lists.sr.ht>.
+
+## License
+
+MIT
diff --git a/cmd/metar.go b/cmd/metar.go
index 6355105..ea72f70 100644
--- a/cmd/metar.go
+++ b/cmd/metar.go
@@ -124,7 +124,7 @@ conjunction with --until`)
`Ending time for METARs (e.g. "2020-01-01T01:31:00" or "3h"), used in
conjunction with --since`)
metarCmd.Flags().DurationVar(
- &past, "past", 0,
+ &past, "past", time.Hour,
`Duration to retrieve METARs since (e.g. "3h")`)
// location constraints
@@ -154,8 +154,8 @@ reported. A higher value results in less dense results.`)
&mostRecentByStation, "most-recent-by-station", "constraint",
`Method for fetching most recent for each station ("constraint",
"postfilter", "false")`)
- metarCmd.Flags().BoolVarP(
- &mostRecent, "one", "1", false,
+ metarCmd.Flags().BoolVar(
+ &mostRecent, "most-recent", false,
`Only fetch the single most recently-issued METAR of all the selected
stations`)
}
@@ -173,19 +173,14 @@ var metarCmd = &cobra.Command{
if !since.t.IsZero() || !until.t.IsZero() {
reqArgs = append(reqArgs, metar.TimeRange(since.t, until.t))
- }
-
- dur, _ := cmd.Flags().GetDuration("past")
- if dur > 0 {
+ } else if dur, _ := cmd.Flags().GetDuration("past"); dur > 0 {
reqArgs = append(reqArgs, metar.HoursBeforeNow(dur.Hours()))
}
- if mostRecentByStation != "" {
- reqArgs = append(reqArgs, metar.MostRecentForEachStation(mostRecentByStation))
- }
-
if mostRecent {
reqArgs = append(reqArgs, metar.MostRecent(true))
+ } else if mostRecentByStation != "" {
+ reqArgs = append(reqArgs, metar.MostRecentForEachStation(mostRecentByStation))
}
if !rect.IsZero() {
diff --git a/doc/wx.1.scd b/doc/wx.1.scd
index 1b452d8..a11f65c 100644
--- a/doc/wx.1.scd
+++ b/doc/wx.1.scd
@@ -2,7 +2,7 @@ wx(1)
# NAME
-wx - a front-end CLI for NOAA Aviation Weather Center data
+wx - a command line interface for aviation weather
# SYNOPSIS
@@ -10,5 +10,61 @@ wx _command_
# COMMANDS
-*metar*
- fetch METAR data
+*metar* [_station_ ...]
+ fetch METAR data for _station_
+
+# METAR
+
+When fetching METARs, a time constraint must be supplied. A time constraint can
+either be in the form "past x" or "between x and y".
+
+Options:
+
+*--past* _duration_
+ fetch METARs from the past _duration_, formatted as a Go duration string
+ (e.g. _3h_).
+
+ *Default:* 1h
+
+*--since* _time_
+ fetch METARs since _time_, formatted as YYYY-MM-DDTHH:MM:SS
+
+*--until* _time_
+ fetch METARs until _time_, formatted as YYYY-MM-DDTHH:MM:SS
+
+*--rect* _minLat_,_minLon_,_maxLat_,_maxLon_
+ fetch METARs within the specified rectangle
+
+*--radial* _dist_,_lat_,_lon_
+ fetch METARs within _dist_ statute miles of the specified point
+
+*--path-dist* _dist_
+ when used with *--waypoint*, specify a maximum distance around the flight
+ path in which to fetch METARs.
+
+*--waypoint* _point_
+ fetch METARs along a flight path specified by multiple *--waypoint* arguments
+ in order from origin to destination. The _point_ may be either an ICAO
+ identifier or a lon,lat pair.
+
+*--min-dist* _dist_
+ when fetching METARs from multiple sources, enforce a minimum distance of
+ _dist_ degrees of latitude or longitude between stations to reduce the
+ density.
+
+*--most-recent*
+ fetch only the single most recent METAR that matches the station filters.
+
+*--most-recent-by-station* _type_
+ fetch the most recent METAR for each station that matches using _type_ as the
+ filter type, which can be one of constraint, postfilter, or false.
+
+ See _https://www.aviationweather.gov/dataserver/example?datatype=metar_ for
+ information about these options.
+
+ *Default:* constraint
+
+# AUTHORS
+
+Ben Burwell <wx@benburwell.com>. For more information, see
+_https://git.sr.ht/~benburwell/wxcli_.