Updated API documentation
[metar.git] / api / html / modules / metar.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html>
4 <head>
5     <title>Reference</title>
6     <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7         <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
8 </head>
9
10 <body>
11 <div id="container">
12
13 <div id="product">
14         <div id="product_logo"></div>
15         <div id="product_name"><big><b></b></big></div>
16         <div id="product_description"></div>
17 </div> <!-- id="product" -->
18
19 <div id="main">
20
21 <div id="navigation">
22
23
24 <h1>LuaDoc</h1>
25 <ul>
26         
27         <li><a href="../index.html">Index</a></li>
28         
29 </ul>
30
31
32 <!-- Module list -->
33
34 <h1>Modules</h1>
35 <ul>
36
37         <li><strong>metar</strong></li>
38         
39 </ul>
40
41
42
43 <!-- File list -->
44
45 <h1>Files</h1>
46 <ul>
47
48         <li>
49                 <a href="../files/metar.html">metar.lua</a>
50         </li>
51
52 </ul>
53
54
55
56
57
58
59 </div><!-- id="navigation" -->
60
61 <div id="content">
62
63 <h1>Module <code>metar</code></h1>
64
65 <p>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.</p>
66
67 <p><b>Author:</b>
68 <table class="authors_list">
69
70         <tr><td class="name">Tuomas Jormola</td></tr>
71
72 </table>
73 </p>
74
75
76 <p>Copyright&copy; © 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>.  </p>
77
78
79
80
81 <h2>Functions</h2>
82 <table class="function_list">
83
84         <tr>
85         <td class="name" nowrap><a href="#metatable.__index:get_metar_data">metatable.__index:get_metar_data</a>&nbsp;()</td>
86         <td class="summary">Return parsed METAR data as a table </td>
87         </tr>
88
89         <tr>
90         <td class="name" nowrap><a href="#new">new</a>&nbsp;(args)</td>
91         <td class="summary">Create a new METAR object </td>
92         </tr>
93
94 </table>
95
96
97
98
99 <h2>Tables</h2>
100 <table class="table_list">
101
102         <tr>
103         <td class="name" nowrap><a href="#CLOUD_COVERAGE">CLOUD_COVERAGE</a></td>
104         <td class="summary">Could coverage table.</td>
105         </tr>
106
107         <tr>
108         <td class="name" nowrap><a href="#CLOUD_TYPE">CLOUD_TYPE</a></td>
109         <td class="summary">Could type table.</td>
110         </tr>
111
112         <tr>
113         <td class="name" nowrap><a href="#SKY_STATUS">SKY_STATUS</a></td>
114         <td class="summary">Could type table.</td>
115         </tr>
116
117         <tr>
118         <td class="name" nowrap><a href="#WEATHER_DESCRIPTOR">WEATHER_DESCRIPTOR</a></td>
119         <td class="summary">Weather descriptor table.</td>
120         </tr>
121
122         <tr>
123         <td class="name" nowrap><a href="#WEATHER_INTENSITY">WEATHER_INTENSITY</a></td>
124         <td class="summary">Weather intensity table.</td>
125         </tr>
126
127         <tr>
128         <td class="name" nowrap><a href="#WEATHER_PHENOMENA">WEATHER_PHENOMENA</a></td>
129         <td class="summary">Weather phenomena table.</td>
130         </tr>
131
132         <tr>
133         <td class="name" nowrap><a href="#WIND_DIRECTION">WIND_DIRECTION</a></td>
134         <td class="summary">Wind direction table.</td>
135         </tr>
136
137 </table>
138
139
140
141 <br/>
142 <br/>
143
144
145
146 <h2><a name="functions"></a>Functions</h2>
147 <dl class="function">
148
149
150
151 <dt><a name="metatable.__index:get_metar_data"></a><strong>metatable.__index:get_metar_data</strong>&nbsp;()</dt>
152 <dd>
153 Return parsed METAR data as a table
154
155
156
157
158
159 <h3>Usage</h3>
160 <ul>
161         
162         <li>var m = metar.new('EFHF')          -- Weather station Helsinki/Malmi
163         
164         <li>var md = m:get_metar_data()        -- metardata.temperature contains the temperature etc.
165         
166         <li>if md.temperature >= 30 then print("It's hot!") end
167         
168         <li>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
169         
170 </ul>
171
172
173
174 <h3>Return values:</h3>
175 <ol>
176         
177         <li>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>
178         
179         <li>Error string in case an error occurred and nil METAR table is returned
180         
181 </ol>
182
183
184
185 </dd>
186
187
188
189
190 <dt><a name="new"></a><strong>new</strong>&nbsp;(args)</dt>
191 <dd>
192 Create a new METAR object
193
194
195 <h3>Parameters</h3>
196 <ul>
197         
198         <li>
199           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>.
200         </li>
201         
202 </ul>
203
204
205
206
207
208
209 <h3>Return value:</h3>
210 A table which is the metar object for METAR data given or downloaded from IWS for the given weather station code
211
212
213
214 </dd>
215
216
217 </dl>
218
219
220
221
222 <h2><a name="tables"></a>Tables</h2>
223 <dl class="table">
224
225 <dt><a name="CLOUD_COVERAGE"></a><strong>CLOUD_COVERAGE</strong></dt>
226 <dd>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>.
227
228
229 <em>Fields</em>
230 <ul>
231         
232         <li>
233           CLEAR: Clear
234         </li>
235         
236         <li>
237           FEW: Few clouds
238         </li>
239         
240         <li>
241           SCATTERED: Scattered clouds
242         </li>
243         
244         <li>
245           BROKEN_SKY: Broken sky
246         </li>
247         
248         <li>
249           OVERCAST: Overcast
250         </li>
251         
252 </ul>
253
254
255 </dd>
256
257
258 <dt><a name="CLOUD_TYPE"></a><strong>CLOUD_TYPE</strong></dt>
259 <dd>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>.
260
261
262 <em>Fields</em>
263 <ul>
264         
265         <li>
266           CUMULONIMBUS: Cumulonimbus clouds
267         </li>
268         
269         <li>
270           TOWERING_CUMULUS: Towering Cumulus clouds
271         </li>
272         
273 </ul>
274
275
276 </dd>
277
278
279 <dt><a name="SKY_STATUS"></a><strong>SKY_STATUS</strong></dt>
280 <dd>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>.
281
282
283 <em>Fields</em>
284 <ul>
285         
286         <li>
287           UNKNOWN: Sky type is unknown
288         </li>
289         
290         <li>
291           OBSCURE: Obscured sky
292         </li>
293         
294         <li>
295           CLOUDS: Clouds in the sky
296         </li>
297         
298         <li>
299           CLEAR: Clear sky
300         </li>
301         
302         <li>
303           NO_SIGNIFICANT_CLOUDS: No significant clouds detected
304         </li>
305         
306         <li>
307           NO_CLOUDS_DETECTED: No clouds detected
308         </li>
309         
310 </ul>
311
312
313 </dd>
314
315
316 <dt><a name="WEATHER_DESCRIPTOR"></a><strong>WEATHER_DESCRIPTOR</strong></dt>
317 <dd>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>.
318
319
320 <em>Fields</em>
321 <ul>
322         
323         <li>
324           SHALLOW: Shallow phenomena
325         </li>
326         
327         <li>
328           PARTIAL: Partial phenomena
329         </li>
330         
331         <li>
332           PATCHES: Patches phenomena
333         </li>
334         
335         <li>
336           DRIFTING: Drifring phenomena
337         </li>
338         
339         <li>
340           BLOWING: Blowing phenomena
341         </li>
342         
343         <li>
344           SHOWERS: Showers phenomena
345         </li>
346         
347         <li>
348           THUNDERSTORM: Thunderstorm phenomena
349         </li>
350         
351         <li>
352           FREEZING: Freezing phenomena
353         </li>
354         
355 </ul>
356
357
358 </dd>
359
360
361 <dt><a name="WEATHER_INTENSITY"></a><strong>WEATHER_INTENSITY</strong></dt>
362 <dd>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>.
363
364
365 <em>Fields</em>
366 <ul>
367         
368         <li>
369           MODERATE: Moderate phenomena
370         </li>
371         
372         <li>
373           LIGHT: Light phenomena
374         </li>
375         
376         <li>
377           HEAVY: Heavy phenomena
378         </li>
379         
380         <li>
381           VICINITY: In the vicinity of the weather observation point
382         </li>
383         
384 </ul>
385
386
387 </dd>
388
389
390 <dt><a name="WEATHER_PHENOMENA"></a><strong>WEATHER_PHENOMENA</strong></dt>
391 <dd>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>.
392
393
394 <em>Fields</em>
395 <ul>
396         
397         <li>
398           DRIZZLE: Drizzle
399         </li>
400         
401         <li>
402           RAIN: Rain
403         </li>
404         
405         <li>
406           SNOW: Snow
407         </li>
408         
409         <li>
410           SNOW_GRAINS: Snow grains
411         </li>
412         
413         <li>
414           ICE_CRYSTALS: Ice crystals
415         </li>
416         
417         <li>
418           ICE_PELLETS: Ice pellets
419         </li>
420         
421         <li>
422           HAIL: Hail
423         </li>
424         
425         <li>
426           SMALL_HAIL: Small hail
427         </li>
428         
429         <li>
430           UNKNOWN: Unknown phenomena
431         </li>
432         
433         <li>
434           MIST: Mist
435         </li>
436         
437         <li>
438           FOG: Fog
439         </li>
440         
441         <li>
442           SMOKE: Smoke
443         </li>
444         
445         <li>
446           VOLCANIC_ASH: Volcanic ash
447         </li>
448         
449         <li>
450           WIDESPREAD_DUST: Widespread dust
451         </li>
452         
453         <li>
454           SAND: Sand
455         </li>
456         
457         <li>
458           HAZE: Haze
459         </li>
460         
461         <li>
462           SPRAY: Spray
463         </li>
464         
465         <li>
466           DUST_WHIRLS: Dust whirls
467         </li>
468         
469         <li>
470           SQUALLS: Squalls
471         </li>
472         
473         <li>
474           FUNNEL_CLOUD: Funnel cloud
475         </li>
476         
477         <li>
478           SAND_STORM: Sand storm
479         </li>
480         
481         <li>
482           DUST_STORM: Dust storm
483         </li>
484         
485 </ul>
486
487
488 </dd>
489
490
491 <dt><a name="WIND_DIRECTION"></a><strong>WIND_DIRECTION</strong></dt>
492 <dd>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>.
493
494
495 <em>Fields</em>
496 <ul>
497         
498         <li>
499           VRB: Index value for variable speed direction
500         </li>
501         
502         <li>
503           N: Index value for North
504         </li>
505         
506         <li>
507           NNE: Index value for North - North East
508         </li>
509         
510         <li>
511           NE: Index value for Nort - East
512         </li>
513         
514         <li>
515           ENE: Index value for East - North East
516         </li>
517         
518         <li>
519           E: Index value for East
520         </li>
521         
522         <li>
523           ESE: Index value for East - South East
524         </li>
525         
526         <li>
527           SE: Index value for South East
528         </li>
529         
530         <li>
531           SSE: Index value for South - South Est
532         </li>
533         
534         <li>
535           S: Index value for South
536         </li>
537         
538         <li>
539           SSW: Index value for South - South West
540         </li>
541         
542         <li>
543           SW: Index value for South West
544         </li>
545         
546         <li>
547           WSW: Index value for West - South West
548         </li>
549         
550         <li>
551           W: Index value for West
552         </li>
553         
554         <li>
555           WNW: Index value for West - North West
556         </li>
557         
558         <li>
559           NW: Index value for North West
560         </li>
561         
562         <li>
563           NNW: Index value for North - North West
564         </li>
565         
566 </ul>
567
568
569 </dd>
570
571
572 </dl>
573
574
575
576 </div> <!-- id="content" -->
577
578 </div> <!-- id="main" -->
579
580 <div id="about">
581         <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
582 </div> <!-- id="about" -->
583
584 </div> <!-- id="container" -->  
585 </body>
586 </html>