Merge branch 'master' into skip-tests

README.md

@@ -19,22 +19,47 @@ The Dark Sky API requires an API key. See the [Dark Sky Developer Documentation]
 ```julia
 # DarkSky.jl is not currently registered as an official package
 # Please install the development version from GitHub:
-Pkg.clone("git://github.com:ellisvalentiner/DarkSky.jl.git")
+Pkg.clone("git://github.com/ellisvalentiner/DarkSky.jl.git")
 ```
 
 DarkSky.jl expects your API key to be stored as an environment variable named `DARKSKY_API_KEY`.
 
 ## Usage
 
+The basic usage is to request the current weather forecast (a [Forecast Request](https://darksky.net/dev/docs#forecast-request)) or the observed or forecast weather conditions for a datetime in the past or future (a [Time Machine Request](https://darksky.net/dev/docs#time-machine-request)).
+
 ```julia
 using DarkSky
 # Make a "Forecast Request", returns the current weather forecast for the next week.
-forecast(42.3601, -71.0589)
+response = forecast(42.3601, -71.0589);
 # Make a "Time Machine Request", returns the observed or forecast weather conditions for a date in
 # the past or future.
-forecast(42.3601, -71.0589, DateTime(2018, 3, 7, 14, 19, 57))
+response = forecast(42.3601, -71.0589, DateTime(2018, 3, 7, 14, 19, 57));
 ```
 
+The Dark Sky response contains the following properties (and can be accessed by functions with the same name):
+
+* `latitude` - The requested latitude.
+* `longitude` - The requested longitude.
+* `timezone` - The IANA timezone name for the requested location.
+* `currently` - A data point containing the current weather conditions at the requested location. (optional)
+* `minutely` - A data block containing the weather conditions minute-by-minute for the next hour. (optional)
+* `hourly` - A data block containing the weather conditions hour-by-hour for the next two days. (optional)
+* `daily` - A data block containing the weather conditions day-by-day for the next week. (optional)
+* `alerts` - An alerts array, which, if present, contains any severe weather alerts pertinent to the requested location. (optional)
+* `flags` - A flags object containing miscellaneous metadata about the request. (optional)
+
+```julia
+# Extract the requested latitude
+latitude(response)
+# Extract the "daily" data block
+daily(response)
+# Extract the "alerts" data block
+alerts(response)
+```
+
+Note that optional properties may not contain data (e.g. there may be no alerts).
+
 ## Contributing
 
 See the [CONTRIBUTING](https://github.com/ellisvalentiner/DarkSky.jl/blob/master/CONTRIBUTING) file.

src/DarkSky.jl

@@ -27,6 +27,18 @@ struct DarkSkyResponse
 end
 DarkSkyResponse(x::Dict) = DarkSkyResponse((get.(x, String.(fieldnames(DarkSkyResponse)), nothing))...)
 
+function Base.show(io::IO, x::DarkSkyResponse)
+    print(io, (x.latitude, x.longitude), "\n" * x.daily["summary"])
+end
+
+for fieldname in fieldnames(DarkSkyResponse)
+    fname = Symbol(fieldname)
+    @eval begin
+        ($fieldname)(x::DarkSkyResponse) = x.$fname
+        export $fieldname
+    end
+end
+
 function _get_json(url::String, verbose::Bool)
     response = HTTP.get(url)
     verbose ? info(response) : nothing