<?xml version="1.0" encoding="utf-8" ?>
<doc xmlns="http://addonstudio.org/schemas/xmldoc">
	<!--                                                                          for remarks: column 100 >|  -->

	<!-- os table functions -->
	<!--<table name="os" virtual="true" />-->
	<table name="os">
		<summary>
			Contains functions to support use of operating system facilities.
		</summary>
		<function name="clock">
			<summary>Gets an approximation of the amount in seconds of CPU time used by the program.</summary>
			<return name="val" type="number">Time in seconds.</return>
		</function>

		<method name="date">
			<summary>Gets a date as a formatted string or a Lua date/time table.</summary>
			<paramchoice>
				<param name="token" type="string">if "*t" is passed, gets a date/time table.</param>
				<param name="format" type="table">a format string following the C stdlib date/time format convention.</param>
			</paramchoice>
			<param name="timestamp" type="number" optional="true">The integer based date/time value to be formatted, default is 'now'</param>
			<return name="val" type="string">A date/time table OR a formatted date/time string.</return>
			<remarks>
				'Date' is a complement to the 'time' function in that 'date' produces a date/time table, and 'time' consumes a
				date/time table. 'Time' also produces an integer based timestamp and 'date' consumes the timestamp. The 'date'
				function in Lua does not just deal with the date part, and 'time' part does not just deal with the time part,
				as the function names might confusingly imply.

				Returns a string or a table containing date and time, formatted according to the given string format. If
				the time argument is present, this is the time to be formatted (see the os.time function for a description
				of this value). Otherwise, date formats the current time.

				If format starts with '!', then the date is formatted in Coordinated Universal Time. After this optional
				character, if format is the string "*t", then date returns a table with the following fields: year (four
				digits), month (1--12), day (1--31), hour (0--23), min (0--59), sec (0--61), wday (weekday, Sunday is 1),
				yday (day of the year), and isdst (daylight saving flag, a boolean).

				If format is not "*t", then date returns the date as a string, formatted according to the same rules as
				the C function strftime.

				When called without arguments, date returns a reasonable date and time representation that depends on the
				host system and on the current locale (that is, os.date() is equivalent to os.date("%c")).
			</remarks>
		</method>
		<method name="time">
			<summary>Gets a timestamp representing a time value typically in seconds.</summary>
			<param name="table" type="number" optional="true">A date/time table, default is 'now'.</param>
			<return name="timestamp" type="number">A system dependent integer based date/time value.</return>
			<remarks>
				'Time' is a complement to the 'date' function in that 'date' produces a date/time table, and 'time' consumes a
				date/time table. 'Time' also produces an integer based timestamp and 'date' consumes the timestamp. The 'date'
				function in Lua does not only deal with just the date part, and 'time' part does not only just deal with the
				time part, as the function names might confusingly imply.

				A contrived 'round trip' example; sets current time's seconds value to 30:
				local table = os.date("*t");  -- get 'now' as a date/time table
				table.sec = 30;
				local time = os.time(table);
				local s = os.date("%H:%M:%S", time);
				print(time);  -- print the timestamp
				print(s);  -- print the formatted time/date string

				Returns the current time when called without arguments, or a time representing the date and time specified
				by the given table. This table must have fields year, month, and day, and may have fields hour, min, sec,
				and isdst (for a description of these fields, see the os.date function).

				The returned value is a number, whose meaning depends on your system. In POSIX, Windows, and some other
				systems, this number counts the number of seconds since some given start time (the "epoch"). In other
				systems, the meaning is not specified, and the number returned by time can be used only as an argument to
				date and difftime.
			</remarks>
		</method>

		<method name="difftime">
			<summary>Gets the number of seconds difference between two time values.</summary>
			<param name="t2" type="number">The timestamp to subtract from.</param>
			<param name="t1" type="number">The timestamp to subtract.</param>
			<return name="val" type="number">The time difference.</return>
			<remarks>
				Returns the number of seconds from time t1 to time t2. In POSIX, Windows, and some other systems, this
				value is exactly t2-t1.
			</remarks>
		</method>

		<!--<method name="execute">
			<summary></summary>
			<param name="command" type="number" optional="true">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				This function is equivalent to the C function system. It passes command to be executed by an operating
				system shell. It returns a status code, which is system-dependent. If command is absent, then it returns
				nonzero if a shell is available and zero otherwise.
			</remarks>
		</method>

		<method name="exit">
			<summary></summary>
			<param name="[code]" type="number">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				Calls the C function exit, with an optional code, to terminate the host program. The default value for
				code is the success code.
			</remarks>
		</method>

		<method name="getenv">
			<summary></summary>
			<param name="varname" type="number">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				Returns the value of the process environment variable varname, or nil if the variable is not defined.
			</remarks>
		</method>

		<method name="remove">
			<summary></summary>
			<param name="filename" type="number">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				Deletes the file or directory with the given name. Directories must be empty to be removed. If this
				function fails, it returns nil, plus a string describing the error.
			</remarks>
		</method>

		<method name="rename">
			<summary></summary>
			<param name="oldname, newname" type="number">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				Renames file or directory named oldname to newname. If this function fails, it returns nil, plus a string
				describing the error.
			</remarks>
		</method>

		<method name="setlocale">
			<summary></summary>
			<param name="locale [, category]" type="number">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				Sets the current locale of the program. locale is a string specifying a locale; category is an optional
				string describing which category to change: "all", "collate", "ctype", "monetary", "numeric", or "time";
				the default category is "all". The function returns the name of the new locale, or nil if the request cannot
				be honored.

				If locale is the empty string, the current locale is set to an implementation-defined native locale. If
				locale is the string "C", the current locale is set to the standard C locale.

				When called with nil as the first argument, this function only returns the name of the current locale
				for the given category.
			</remarks>
		</method>

		<method name="tmpname">
			<summary></summary>
			<param name="" type="number">The value</param>
			<return name="val" type="number"></return>
			<remarks>
				Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened
				before its use and explicitly removed when no longer needed.
				On some systems (POSIX), this function also creates a file with that name, to avoid security risks.
				(Someone else might create the file with wrong permissions in the time between getting the name and
				creating the file.) You still have to open the file to use it and to remove it (even if you do not use it).

				When possible, you may prefer to use io.tmpfile, which automatically removes the file when the program ends.
			</remarks>
		</method>-->
	</table>

	<!-- package table functions -->
	<table name="package" virtual="true" />
	<table name="debug" virtual="true" />
	<table name="io" virtual="true" />
	<table name="coroutine" virtual="true" />

	<!-- misc -->
	<function name="debugprint" />
	<function name="debugload" />
	<function name="debuginfo" />
	<function name="debugdump" />
	<function name="debugbreak" />
</doc>