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