Updated API documentation
[metar.git] / api / ikiwiki / modules / metar.mdwn
1 [[!meta title="LuaDoc - metar"]]
2
3 <div id="luadoc" markdown="1">
4
5 [[Jump to content|ikiwiki/modules/metar#luadoc-content"]]
6
7 # LuaDoc
8
9
10 * [[Index|ikiwiki]]
11
12
13
14 # Modules
15
16 * **metar**
17
18
19
20
21 # Files
22
23 * [[metar.lua|ikiwiki/files/metar.lua]]
24
25
26
27
28 ---
29
30 <span id="luadoc-content" />
31
32 # Module `metar`
33
34
35 Lua class to parse METAR coded weather reports and fetch current METAR reports from <a href="http://www.noaa.gov">NOAA</a> <a href="http://weather.noaa.gov">Internet Weather Service</a>. The parser is pretty simple and by no means claims to support every feature one might find in METAR coded weather reports. For example, weather forecasts and automatic weather reports are not detected. Unsupported features in the weather reports are silently dropped.
36
37
38
39 **Author:**
40
41 * Tuomas Jormola
42
43
44
45
46 Copyright: © 2010 Tuomas Jormola <a href="mailto:tj@solitudo.net">tj@solitudo.net</a> <a href="http://solitudo.net">http://solitudo.net</a> Licensed under the terms of the <a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License Version 2.0</a>.  
47
48
49
50
51
52 ## Functions summary
53
54 | - | - |
55 | [[`metatable.__index:get_metar_data`|ikiwiki/modules/metar#luadoc-function-metatable.__index:get_metar_data]] `(`*``*`)` | Return parsed METAR data as a table  |
56 | [[`new`|ikiwiki/modules/metar#luadoc-function-new]] `(`*`args`*`)` | Create a new METAR object  |
57
58
59
60
61 ## Tables summary
62
63 | - | - |
64 | [[`CLOUD_COVERAGE`|ikiwiki/modules/metar#luadoc-table-CLOUD_COVERAGE]] | Could coverage table. |
65 | [[`CLOUD_TYPE`|ikiwiki/modules/metar#luadoc-table-CLOUD_TYPE]] | Could type table. |
66 | [[`SKY_STATUS`|ikiwiki/modules/metar#luadoc-table-SKY_STATUS]] | Could type table. |
67 | [[`WEATHER_DESCRIPTOR`|ikiwiki/modules/metar#luadoc-table-WEATHER_DESCRIPTOR]] | Weather descriptor table. |
68 | [[`WEATHER_INTENSITY`|ikiwiki/modules/metar#luadoc-table-WEATHER_INTENSITY]] | Weather intensity table. |
69 | [[`WEATHER_PHENOMENA`|ikiwiki/modules/metar#luadoc-table-WEATHER_PHENOMENA]] | Weather phenomena table. |
70 | [[`WIND_DIRECTION`|ikiwiki/modules/metar#luadoc-table-WIND_DIRECTION]] | Wind direction table. |
71
72
73
74
75 ## Functions
76
77 ---
78
79 <span id="luadoc-function-metatable.__index:get_metar_data" />
80
81 ### metatable.__index:get_metar_data ()
82
83
84 Return parsed METAR data as a table
85
86
87
88
89
90 **Usage**
91
92 * `var m = metar.new('EFHF')          -- Weather station Helsinki/Malmi`
93 * `var md = m:get_metar_data()        -- metardata.temperature contains the temperature etc.`
94 * `if md.temperature >= 30 then print("It's hot!") end`
95 * `if md.weather.intensity and md.weather.intensity == m.WEATHER_INTENSITY.HEAVY and md.weather.phenomena and md.weather.phenomena == m.WEATHER_PHENOMENA.RAIN then print("It's raining a lot!") end`
96
97
98
99
100 **Return values:**
101
102 1. Table containing the data parsed from the METAR data. If an error occurs, returns nil as the first return value. The table may contain following entries <ul> <li><code>timestamp</code> <code>os.time</code> table which represents the timestamp when the METAR data was generated. Time is in UTC. Always included.</li> <li><code>wind</code> A table representing the wind phenomena with the following keys. Optional, but usually included.</li> <ul> <li><code>direction</code> Wind direction as a value of the <a href="#WIND_DIRECTION">WIND_DIRECTION</a> table.</li> <li><code>speed</code> Wind speed in knots.</li> <li><code>gust</code> Gust speed in knots, optional.</li> </ul> <li><code>visibility</code> A list of tables that represent the visibility towards different directions. Tables contain the following keys. Optional, but if defined, at least one visibility entry exists in the list. Usually included.</li> <ul> <li><code>direction</code> Direction as a value of the <a href="#WIND_DIRECTION">WIND_DIRECTION</a> table. Optional.</li> <li><code>distance</code> Visibility distance in meters</li> </ul> <li><code>vertical_visibility</code> Vertical visibility in meters. Optional.</li> <li><code>runway_visual_range</code> A table representing runway visual range with the following keys. Optional.</li> <ul> <li><code>runway</code> Runway code</li> <li><code>visibility</code> Visibility in meters</li> </ul> <li><code>clouds</code> A list of tables that represent clouds at different altitudes. Tables contain the following keys. Optional, but if defined, at least one cloud entry exists in the list. Usually included.</li> <ul> <li><code>coverage</code> Cloud coverate as a value of the <a href="#CLOUD_COVERAGE">CLOUD_COVERAGE</a> table.</li> <li><code>altitude</code> Altitude of the clouds in feet.</li> <li><code>type</code> Cloud type as a value of the <a href="#CLOUD_TYPE">CLOUD_TYPE</a> table.</li> </ul> <li><code>weather</code> A table representing weather conditions with the following keys. Optional, but usually included.</li> <ul> <li><code>intensity</code> Weather intensity as a value of the <a href="#WEATHER_INTENSITY">WEATHER_INTENSITY</a> table. Optional.</li></li> <li><code>descriptor</code> Weather descriptor as a value of the <a href="#WEATHER_DESCRIPTOR">WEATHER_DESCRIPTOR</a> table. Optional.</li> <li><code>phenomena</code> Weather phenomena as a value of the <a href="#WEATHER_PHENOMENA">WEATHER_PHENOMENA</a> table. Always included.</li> </ul> <li><code>sky</code> Sky status as a value of the <a href="#SKY_STATUS">SKY_STATUS</a> table. Always included.</li> <li><code>temperature</code> Temperature in Celcius. Always  included.</li> <li><code>dewpoint</code> Dewpoint temperature in Celcius. Always included.</li> <li><code>pressure</code> Pressure in hectopascals. Optional, but usually included.</li> </ul>
103 1. Error string in case an error occurred and nil METAR table is returned
104
105
106
107
108
109
110 ---
111
112 <span id="luadoc-function-new" />
113
114 ### new (args)
115
116
117 Create a new METAR object
118
119
120
121 **Parameters**
122
123 * `args`: String that is either the METAR data string (one line) to parse or the four-letter, upper-case <a href="http://en.wikipedia.org/wiki/International_Civil_Aviation_Organization_airport_code">ICAO code</a> for the weather station. If weather station code is given, the current METAR data for the station is downloaded from <a href="http://weather.noaa.gov">IWS</a>.
124
125
126
127
128
129
130 **Return value:**
131
132 A table which is the metar object for METAR data given or downloaded from IWS for the given weather station code
133
134
135
136
137
138
139
140
141 ## Tables
142
143 ---
144
145 <span id="luadoc-table-CLOUD_COVERAGE" />
146
147 ### CLOUD_COVERAGE
148
149
150 Could coverage table. Values from this table are used in the result table with key <code>clouds[n].coverage</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
151
152
153
154 **Fields**
155
156 * `CLEAR`: Clear
157 * `FEW`: Few clouds
158 * `SCATTERED`: Scattered clouds
159 * `BROKEN_SKY`: Broken sky
160 * `OVERCAST`: Overcast
161
162
163
164
165 ---
166
167 <span id="luadoc-table-CLOUD_TYPE" />
168
169 ### CLOUD_TYPE
170
171
172 Could type table. Values from this table are used in the result table with key <code>clouds[n].type</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
173
174
175
176 **Fields**
177
178 * `CUMULONIMBUS`: Cumulonimbus clouds
179 * `TOWERING_CUMULUS`: Towering Cumulus clouds
180
181
182
183
184 ---
185
186 <span id="luadoc-table-SKY_STATUS" />
187
188 ### SKY_STATUS
189
190
191 Could type table. Values from this table are used in the result table with key <code>sky</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
192
193
194
195 **Fields**
196
197 * `UNKNOWN`: Sky type is unknown
198 * `OBSCURE`: Obscured sky
199 * `CLOUDS`: Clouds in the sky
200 * `CLEAR`: Clear sky
201 * `NO_SIGNIFICANT_CLOUDS`: No significant clouds detected
202 * `NO_CLOUDS_DETECTED`: No clouds detected
203
204
205
206
207 ---
208
209 <span id="luadoc-table-WEATHER_DESCRIPTOR" />
210
211 ### WEATHER_DESCRIPTOR
212
213
214 Weather descriptor table. Values from this table are used in the result table with key <code>weather.descriptor</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
215
216
217
218 **Fields**
219
220 * `SHALLOW`: Shallow phenomena
221 * `PARTIAL`: Partial phenomena
222 * `PATCHES`: Patches phenomena
223 * `DRIFTING`: Drifring phenomena
224 * `BLOWING`: Blowing phenomena
225 * `SHOWERS`: Showers phenomena
226 * `THUNDERSTORM`: Thunderstorm phenomena
227 * `FREEZING`: Freezing phenomena
228
229
230
231
232 ---
233
234 <span id="luadoc-table-WEATHER_INTENSITY" />
235
236 ### WEATHER_INTENSITY
237
238
239 Weather intensity table. Values from this table are used in the result table with key <code>weather.intensity</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
240
241
242
243 **Fields**
244
245 * `MODERATE`: Moderate phenomena
246 * `LIGHT`: Light phenomena
247 * `HEAVY`: Heavy phenomena
248 * `VICINITY`: In the vicinity of the weather observation point
249
250
251
252
253 ---
254
255 <span id="luadoc-table-WEATHER_PHENOMENA" />
256
257 ### WEATHER_PHENOMENA
258
259
260 Weather phenomena table. Values from this table are used in the result table with key <code>weather.phenomena</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
261
262
263
264 **Fields**
265
266 * `DRIZZLE`: Drizzle
267 * `RAIN`: Rain
268 * `SNOW`: Snow
269 * `SNOW_GRAINS`: Snow grains
270 * `ICE_CRYSTALS`: Ice crystals
271 * `ICE_PELLETS`: Ice pellets
272 * `HAIL`: Hail
273 * `SMALL_HAIL`: Small hail
274 * `UNKNOWN`: Unknown phenomena
275 * `MIST`: Mist
276 * `FOG`: Fog
277 * `SMOKE`: Smoke
278 * `VOLCANIC_ASH`: Volcanic ash
279 * `WIDESPREAD_DUST`: Widespread dust
280 * `SAND`: Sand
281 * `HAZE`: Haze
282 * `SPRAY`: Spray
283 * `DUST_WHIRLS`: Dust whirls
284 * `SQUALLS`: Squalls
285 * `FUNNEL_CLOUD`: Funnel cloud
286 * `SAND_STORM`: Sand storm
287 * `DUST_STORM`: Dust storm
288
289
290
291
292 ---
293
294 <span id="luadoc-table-WIND_DIRECTION" />
295
296 ### WIND_DIRECTION
297
298
299 Wind direction table. Values from this table are used in the result table with key <code>wind.direction</code> returned by <a href="#metatable.__index:get_metar_data"><code>get_metar_data()</code></a>.
300
301
302
303 **Fields**
304
305 * `VRB`: Index value for variable speed direction
306 * `N`: Index value for North
307 * `NNE`: Index value for North - North East
308 * `NE`: Index value for Nort - East
309 * `ENE`: Index value for East - North East
310 * `E`: Index value for East
311 * `ESE`: Index value for East - South East
312 * `SE`: Index value for South East
313 * `SSE`: Index value for South - South Est
314 * `S`: Index value for South
315 * `SSW`: Index value for South - South West
316 * `SW`: Index value for South West
317 * `WSW`: Index value for West - South West
318 * `W`: Index value for West
319 * `WNW`: Index value for West - North West
320 * `NW`: Index value for North West
321 * `NNW`: Index value for North - North West
322
323
324
325
326
327
328 </div>