Correct and simplify URLError exception handling
[weather.git] / weather.1
1 .TH weather 1 "2020\-08\-23" "2.4.1" \" -*- nroff -*-
2 \" Copyright (c) 2006-2020 Jeremy Stanley <fungi@yuggoth.org>.
3 \" Permission to use, copy, modify, and distribute this software is
4 \" granted under terms provided in the LICENSE file distributed with
5 \" this software.
6 .SH NAME
7 weather \- command-line tool to obtain weather conditions and forecasts
8 .SH SYNOPSIS
9 .B weather
10 [
11 .I options
12 ] [
13 .I alias1
14 |
15 .I search1
16 [
17 .I alias2
18 |
19 .I search2
20 [...]]]
21 .SH DESCRIPTION
22 .
23 This command-line utility is intended to provide quick access to current
24 weather conditions and forecasts.
25 .
26 Presently, it is capable of returning data for localities throughout the
27 USA and some select locations globally by retrieving and formatting
28 decoded METARs (Meteorological Aerodrome Reports) from NOAA (the USA
29 National Oceanic and Atmospheric Administration) and forecasts/alerts
30 from NWS (the USA National Weather Service).
31 .
32 The tool is written to function in the same spirit as other command-line
33 informational utilities like \fIcal\fR(1), \fIcalendar\fR(1) and
34 \fIdict\fR(1).
35 .
36 It retrieves arbitrary weather data via precompiled correlations or
37 custom-tailored aliases (system-wide or on a per-user basis).
38
39 Behavior can be determined by command-line options and specification of
40 zero or more location aliases and search terms.
41
42 Aliases are defined in \fIweatherrc\fR(5) files, as a convenient means
43 of grouping URIs together using a short name.
44 .
45 Specifying multiple aliases or location search terms on the command line
46 causes the utility to output data for each, as if it had been invoked
47 multiple times.
48 .
49 If none are specified, then an alias of \fIdefault\fR is checked for a
50 \fIdefargs\fR option and any alias names listed within it
51 (comma-separated) are applied instead.
52
53 Searches utilize location correlation sets in INI-style text files named
54 \fIairports\fR, \fIplaces\fR, \fIstations\fR, \fIzctas\fR and
55 \fIzones\fR.
56 .
57 A precomputed copy is distributed with the source, but can be rebuilt
58 from updated data sources as needed by placing them in the current
59 working directory and running with the \fI\-\-build\-sets\fR option (see
60 the comments at the top of any location correlation set file for
61 instructions on where to find updated data sources).
62 .
63 Positive search results are cached and sourced as aliases on subsequent
64 runs for as long as the correlation sets remain unchanged, and are
65 cleared automatically once the correlation sets are updated.
66
67 Retrieved data is also cached automatically for a short period of time,
68 adjustable with the \fIcacheage\fR configuration option or
69 \fI\-\-cacheage\fR command-line option.
70 .
71 This helps throttle load against NOAA/NWS servers in case the utility is
72 repeatedly re-run requesting the same data, but can be overridden with
73 the \fIcache_data\fR configuration option or \fI\-\-no\-cache\-data\fR
74 command-line option.
75 .
76 .SH OPTIONS
77 A summary of options is included below.
78 .TP
79 .BR \-\-version
80 show program's version number and exit
81 .TP
82 .BR \-h ", " \-\-help
83 show a help message and exit
84 .TP
85 .BR \-a ", " \-\-alert
86 include local alert notices
87 .TP
88 .BR \-\-atypes =\fIATYPES\fR
89 list of alert notification types to display (ex:
90 .BR tornado_warning,urgent_weather_message )
91 .TP
92 .BR \-\-build\-sets
93 (re)build location correlation sets
94 .TP
95 .BR \-\-cacheage =\fICACHEAGE\fR
96 duration in seconds to refresh cached data (ex:
97 .BR 900 )
98 .TP
99 .BR \-\-cachedir =\fICACHEDIR\fR
100 directory for storing cached searches and data (ex:
101 .BR ~/.weather )
102 .TP
103 .BR \-f ", " \-\-forecast
104 include a local forecast
105 .TP
106 .BR \-\-headers =\fIHEADERS\fR
107 list of conditions headers to display (ex:
108 .BR temperature,wind )
109 .TP
110 .BR \-\-imperial
111 filter/convert conditions for US/UK units
112 .TP
113 .BR \-\-info
114 output detailed information for your search
115 .TP
116 .BR \-l ", " \-\-list
117 list all configured aliases and cached searches
118 .TP
119 .BR \-\-longlist
120 display details of all configured aliases
121 .TP
122 .BR \-m ", " \-\-metric
123 filter/convert conditions for metric units
124 .TP
125 .BR \-n ", " \-\-no\-conditions
126 disable output of current conditions
127 .TP
128 .BR \-\-no\-cache
129 disable all caching (searches and data)
130 .TP
131 .BR \-\-no\-cache\-data
132 disable retrieved data caching
133 .TP
134 .BR \-\-no\-cache\-search
135 disable search result caching
136 .TP
137 .BR \-q ", " \-\-quiet
138 skip preambles and don't indent
139 .TP
140 .BR \-\-setpath =\fISETPATH\fR
141 directory search path for correlation sets (ex:
142 .BR .:~/.weather )
143 .TP
144 .BR \-v ", " \-\-verbose
145 show full decoded feeds
146 .SH EXAMPLES
147 .TP
148 .B weather
149 View output for the default alias, if one has been defined (otherwise
150 display usage/syntax similar to \-\-help)
151 .TP
152 .BR weather " " rdu
153 Display weather conditions at the airport with IATA/FAA code \fIRDU\fR.
154 .TP
155 .BR weather " " \-\-info " " raleigh
156 Show a list of FIPS codes for United States Census Bureau places
157 containing the word \fIraleigh\fR (or the proximity information if only
158 one match was found).
159 .TP
160 .BR weather " " \(dq ^ral[ie]{2}gh " " city.*nc$ \(dq
161 Get the current weather conditions from the nearest station to the
162 Census place name matching the regular expression provided.
163 .TP
164 .BR weather " " \-fv " " fips3755000
165 Get the full decoded METAR from the nearest station, and the forecast
166 data for the nearest zone to the Census place with FIPS code
167 \fI3755000\fR with no special filtering or formatting.
168 .TP
169 .BR weather " " \-\-forecast " " \-\-no\-cache\-data " " 27613
170 Ignore any recent cached METAR or forecast data and display fresh output
171 for the nearest station and zone to the Census ZCTA (essentially USPS
172 ZIP code) \fI27613\fR.
173 .TP
174 .BR weather " " home " " work
175 Show current conditions for both the \fIhome\fR and \fIwork\fR aliases
176 in that order.
177 .TP
178 .BR weather " " 35.878573,\-78.727813
179 .TP
180 .BR weather " " 35\-52\-43n,78\-43\-40w
181 .TP
182 .BR weather " " \(dq 35\-52n, " " 78\-43w \(dq
183 Display weather conditions for the nearest station to an arbitrary set
184 of global coordinates in latitude,longitude order either in decimal
185 format or degree, degree\-minute or degree\-minute\-second formats,
186 optionally using signed or cardinal hemisphere designations with or
187 without spacing.
188 .
189 Note that the cut-off for maximum acceptable distance is hard-coded at
190 0.1 radians (roughly 637km or 396mi).
191 .
192 .SH INPUT FILES
193 .
194 .B weather
195 may additionally obtain configuration data from a system-wide
196 configuration file, a per-user configuration file, and a local
197 directory configuration file.
198 .
199 The file format and configuration options are described in
200 .IR weatherrc (5).
201 .
202 They are aggregated in the following order:
203 .TP
204 .I /etc/weatherrc " or " /etc/weather/weatherrc
205 the system-wide configuration
206 .TP
207 .IR ~/.weather/weatherrc " or " ~/.weatherrc
208 the per-user configuration
209 .TP
210 .I ./weatherrc
211 the local directory configuration
212 .SH AUTHOR
213 Utility and manual written by Jeremy Stanley <fungi@yuggoth.org>.
214 .SH SEE ALSO
215 .IR weatherrc (5)