Updated API documentation
[metar.git] / api / ikiwiki / files / metar.lua.mdwn
1 [[!meta title="LuaDoc - metar.lua"]]
2
3 <div id="luadoc" markdown="1">
4
5 [[Jump to content|ikiwiki/files/metar.lua#luadoc-content"]]
6
7 # LuaDoc
8
9
10 * [[Index|ikiwiki]]
11
12
13
14 # Modules
15
16 * [[metar|ikiwiki/modules/metar]]
17
18
19
20
21 # Files
22
23 * **metar.lua**
24
25
26
27
28 ---
29
30 <span id="luadoc-content" />
31
32 # File `metar.lua`
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
56 | [[`metatable.__index:get_metar_data`|ikiwiki/files/metar.lua#luadoc-function-metatable.__index:get_metar_data]] `(`*``*`)` | Return parsed METAR data as a table  |
57
58 | [[`new`|ikiwiki/files/metar.lua#luadoc-function-new]] `(`*`args`*`)` | Create a new METAR object  |
59
60
61
62
63 ## Tables summary
64
65 | - | - |
66 | [[`CLOUD_COVERAGE`|ikiwiki/files/metar.lua#luadoc-table-CLOUD_COVERAGE]] | Could coverage table. |
67 | [[`CLOUD_TYPE`|ikiwiki/files/metar.lua#luadoc-table-CLOUD_TYPE]] | Could type table. |
68 | [[`SKY_STATUS`|ikiwiki/files/metar.lua#luadoc-table-SKY_STATUS]] | Could type table. |
69 | [[`WEATHER_DESCRIPTOR`|ikiwiki/files/metar.lua#luadoc-table-WEATHER_DESCRIPTOR]] | Weather descriptor table. |
70 | [[`WEATHER_INTENSITY`|ikiwiki/files/metar.lua#luadoc-table-WEATHER_INTENSITY]] | Weather intensity table. |
71 | [[`WEATHER_PHENOMENA`|ikiwiki/files/metar.lua#luadoc-table-WEATHER_PHENOMENA]] | Weather phenomena table. |
72 | [[`WIND_DIRECTION`|ikiwiki/files/metar.lua#luadoc-table-WIND_DIRECTION]] | Wind direction table. |
73
74
75
76
77 ## Functions
78
79 ---
80
81 <span id="luadoc-function-metatable.__index:get_metar_data" />
82
83 ### metatable.__index:get_metar_data ()
84
85
86 Return parsed METAR data as a table
87
88
89
90
91
92 **Usage**
93
94 * `var m = metar.new('EFHF')          -- Weather station Helsinki/Malmi`
95 * `var md = m:get_metar_data()        -- metardata.temperature contains the temperature etc.`
96 * `if md.temperature >= 30 then print("It's hot!") end`
97 * `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`
98
99
100
101
102 **Return values:**
103
104 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>
105 1. Error string in case an error occurred and nil METAR table is returned
106
107
108
109
110
111
112 ---
113
114 <span id="luadoc-function-new" />
115
116 ### new (args)
117
118
119 Create a new METAR object
120
121
122
123 **Parameters**
124
125 * `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>.
126
127
128
129
130
131
132 **Return value:**
133
134 A table which is the metar object for METAR data given or downloaded from IWS for the given weather station code
135
136
137
138
139
140
141
142
143 ## Tables
144
145 ---
146
147 <span id="luadoc-table-CLOUD_COVERAGE" />
148
149 ### CLOUD_COVERAGE
150
151
152 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>.
153
154
155
156 **Fields**
157
158 * `CLEAR`: Clear
159 * `FEW`: Few clouds
160 * `SCATTERED`: Scattered clouds
161 * `BROKEN_SKY`: Broken sky
162 * `OVERCAST`: Overcast
163
164
165
166
167 ---
168
169 <span id="luadoc-table-CLOUD_TYPE" />
170
171 ### CLOUD_TYPE
172
173
174 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>.
175
176
177
178 **Fields**
179
180 * `CUMULONIMBUS`: Cumulonimbus clouds
181 * `TOWERING_CUMULUS`: Towering Cumulus clouds
182
183
184
185
186 ---
187
188 <span id="luadoc-table-SKY_STATUS" />
189
190 ### SKY_STATUS
191
192
193 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>.
194
195
196
197 **Fields**
198
199 * `UNKNOWN`: Sky type is unknown
200 * `OBSCURE`: Obscured sky
201 * `CLOUDS`: Clouds in the sky
202 * `CLEAR`: Clear sky
203 * `NO_SIGNIFICANT_CLOUDS`: No significant clouds detected
204 * `NO_CLOUDS_DETECTED`: No clouds detected
205
206
207
208
209 ---
210
211 <span id="luadoc-table-WEATHER_DESCRIPTOR" />
212
213 ### WEATHER_DESCRIPTOR
214
215
216 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>.
217
218
219
220 **Fields**
221
222 * `SHALLOW`: Shallow phenomena
223 * `PARTIAL`: Partial phenomena
224 * `PATCHES`: Patches phenomena
225 * `DRIFTING`: Drifring phenomena
226 * `BLOWING`: Blowing phenomena
227 * `SHOWERS`: Showers phenomena
228 * `THUNDERSTORM`: Thunderstorm phenomena
229 * `FREEZING`: Freezing phenomena
230
231
232
233
234 ---
235
236 <span id="luadoc-table-WEATHER_INTENSITY" />
237
238 ### WEATHER_INTENSITY
239
240
241 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>.
242
243
244
245 **Fields**
246
247 * `MODERATE`: Moderate phenomena
248 * `LIGHT`: Light phenomena
249 * `HEAVY`: Heavy phenomena
250 * `VICINITY`: In the vicinity of the weather observation point
251
252
253
254
255 ---
256
257 <span id="luadoc-table-WEATHER_PHENOMENA" />
258
259 ### WEATHER_PHENOMENA
260
261
262 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>.
263
264
265
266 **Fields**
267
268 * `DRIZZLE`: Drizzle
269 * `RAIN`: Rain
270 * `SNOW`: Snow
271 * `SNOW_GRAINS`: Snow grains
272 * `ICE_CRYSTALS`: Ice crystals
273 * `ICE_PELLETS`: Ice pellets
274 * `HAIL`: Hail
275 * `SMALL_HAIL`: Small hail
276 * `UNKNOWN`: Unknown phenomena
277 * `MIST`: Mist
278 * `FOG`: Fog
279 * `SMOKE`: Smoke
280 * `VOLCANIC_ASH`: Volcanic ash
281 * `WIDESPREAD_DUST`: Widespread dust
282 * `SAND`: Sand
283 * `HAZE`: Haze
284 * `SPRAY`: Spray
285 * `DUST_WHIRLS`: Dust whirls
286 * `SQUALLS`: Squalls
287 * `FUNNEL_CLOUD`: Funnel cloud
288 * `SAND_STORM`: Sand storm
289 * `DUST_STORM`: Dust storm
290
291
292
293
294 ---
295
296 <span id="luadoc-table-WIND_DIRECTION" />
297
298 ### WIND_DIRECTION
299
300
301 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>.
302
303
304
305 **Fields**
306
307 * `VRB`: Index value for variable speed direction
308 * `N`: Index value for North
309 * `NNE`: Index value for North - North East
310 * `NE`: Index value for Nort - East
311 * `ENE`: Index value for East - North East
312 * `E`: Index value for East
313 * `ESE`: Index value for East - South East
314 * `SE`: Index value for South East
315 * `SSE`: Index value for South - South Est
316 * `S`: Index value for South
317 * `SSW`: Index value for South - South West
318 * `SW`: Index value for South West
319 * `WSW`: Index value for West - South West
320 * `W`: Index value for West
321 * `WNW`: Index value for West - North West
322 * `NW`: Index value for North West
323 * `NNW`: Index value for North - North West
324
325
326
327
328
329
330 </div>