.\" Man page for weatherhs
.TH "WEATHERHS" 1 "13 August 2022" "1.0.0" "Man page for weatherhs"
.SH NAME
weatherhs \- weather and related data info command-line tool
.SH SYNOPSIS
.B weatherhs
.RB [ -h ]
.RB [ -v ]
.RB [ --no-pp ]
.RB [ -m
.IR MODE ]
.RB [ -a ]
.RB [ -w ]
.RB [ -d
.IR INTEGER≥1 ]
.RB [ -t
.IR yyyy-MM-dd ]
.RB [ --format
.IR FORMAT ]
.RB [ --unsafe ]
.RB [ --get-file ]
.SH DESCRIPTION
This is a command-line utility that retrieves and nicely outputs ("pretty-prints") weather and related data ("data") from WeatherAPI server ("the server"), in the table form.
.SH ENVIRONMENT
All environment variables specific to this program start with "WEATHERHS_".
.TP
.B WEATHERHS_API_KEY
API key to retrieve data from the server.
You can get one by registering on WeatherAPI website.
.IP
Must match
.BR pcre (3)
pattern "^[0-9a-fA-F]+$" in order to be taken into consideration.
.TP
.B WEATHERHS_API_KEY_ENC
Path to the file where
.BR gpg (1)-encrypted
API key to retrieve data from the server is stored.
You will need to authenticate yourself in order for the program to decrypt the file and by that get the API key.
.IP
Must be set and non-empty and when its target is decrypted its content must be of the
.BR pcre (3)
pattern "^[0-9a-fA-F]+$" in order to be taken into consideration.
.IP
This environment variable will only be effective if the program was compiled with encryption support ("encryption" compile flag).
.P
Of
.B WEATHERHS_API_KEY
and
.B WEATHERHS_API_KEY_ENC
the latter one takes precedence, and one of them must be properly set for the main function of the program to work.
.TP
.B WEATHERHS_LOCATION
Location to retrieve the data for.
It is directly passed as the query parameter value to the server.
.IP
Must match
.BR pcre (3)
pattern "^[ .,[:alnum:]]+$" in order for the main function of the program to work.
.TP
.B WEATHERHS_LANGUAGE
Language code signifying in which language should be retrieved data strings.
The default is "en".
.IP
Must match
.BR pcre (3)
pattern "^[a-z_]+$" in order to be taken into consideration.
.SH OPTIONS
Without any option given, the program will send request only for the current weather data (which means without air quality) to the server for the location specified in
.B WEATHERHS_LOCATION
environment variable, and pretty-print it to the user on success.
.TP
.BR -h ", " --help
Display the program help menu and exit.
.TP
.BR -v ", " --version
Display the program version and exit.
.TP
.B --no-pp
Do not pretty-print data.
.TP
.BI -m " MODE\fR, " --mode " MODE"
Mode for information type.
The allowed values and their corresponding information types are:
.TS
lb l.
timezone	Location and time zone.
current	Current weather.
forecast	Forecast for the specific number of days.
astronomy	Astronomical data.
.TE
.IP
The default is "current".
.TP
.BR -a ", " --air-quality
Along with weather data retrieve and print air quality data.
.IP
Meaningful only if the information type mode is "current" or "forecast".
.TP
.BR -w ", " --alerts
Along with weather data retrieve and print weather alerts.
.IP
Meaningful only if the information type mode is "forecast".
.TP
.BI -d " INTEGER≥1\fR, " --days " INTEGER≥1"
Number of days to retrieve the data for when the information type mode is "forecast".
The default is 3.
.TP
.BI -t " yyyy-MM-dd\fR, " --date " yyyy-MM-dd"
Date to retrieve the data for when the information type mode is "astronomy".
The default is current date.
.TP
.BI -f " FORMAT\fR, " --format " FORMAT"
Format to request the data in from the server.
Either "json" (default) or "xml".
.TP
.B --unsafe
Use HTTP instead of HTTPS for communication with the server.
.TP
.B --get-file
Just print the retrieved data file.
.SH RETURN VALUE
.TS
r l.
0	No errors.
1	Invalid command-line arguments or environment.
2	System error.
3	Network error.
4	Data parsing error.
.TE
.SH LINKS
.TS
lb ci.
WeatherAPI	https://weatherapi.com/
.TE
.SH NOTES
If using
.B WEATHERHS_API_KEY_ENC
make sure that the decrypted API key does not contain the ending newline, as then it will not match the verifying pattern.
.P
Behavior of the tool described here is based on the behavior of WeatherAPI service at the time of writing, thus it may be different at the time when you use it.
.SH SEE ALSO
.BR pcre (3),
.BR gpg (1)