Update docs (#6)

lune-org · Sep 17, 2023 · 1ab4000 · 1ab4000
1 parent 63db4ac
commit 1ab4000
Show file tree

Hide file tree

Showing 4 changed files with 317 additions and 2 deletions.
diff --git a/pages/api-reference/_meta.json b/pages/api-reference/_meta.json
@@ -1,4 +1,5 @@
 {
+	"datetime": "DateTime",
 	"fs": "FS",
 	"luau": "Luau",
 	"net": "Net",

diff --git a/pages/api-reference/datetime.md b/pages/api-reference/datetime.md
@@ -0,0 +1,315 @@
+# DateTime
+
+Built-in library for date & time
+
+#### Example usage
+
+```lua
+local DateTime = require("@lune/datetime")
+
+-- Creates a DateTime for the current exact moment in time
+local now = DateTime.now()
+
+-- Formats the current moment in time as an ISO 8601 string
+print(now:toIsoDate())
+
+-- Formats the current moment in time, using the local
+-- time, the Frech locale, and the specified time string
+print(now:formatLocalTime("%A, %d %B %Y", "fr"))
+
+-- Returns a specific moment in time as a DateTime instance
+local someDayInTheFuture = DateTime.fromLocalTime({
+	year = 3033,
+	month = 8,
+	day = 26,
+	hour = 16,
+	minute = 56,
+	second = 28,
+	millisecond = 892,
+})
+
+-- Extracts the current local date & time as separate values (same values as above table)
+print(now:toLocalTime())
+
+-- Returns a DateTime instance from a given float, where the whole
+-- denotes the seconds and the fraction denotes the milliseconds
+-- Note that the fraction for millis here is completely optional
+DateTime.fromUnixTimestamp(871978212313.321)
+
+-- Extracts the current universal (UTC) date & time as separate values
+print(now:toUniversalTime())
+```
+
+## Functions
+
+### toIsoDate
+
+Formats this `DateTime` as an ISO 8601 date-time string.
+
+Some examples of ISO 8601 date-time strings:
+
+-   `2020-02-22T18:12:08Z`
+-   `2000-01-31T12:34:56+05:00`
+-   `1970-01-01T00:00:00.055Z`
+
+#### Parameters
+
+-   `self` DateTime
+
+#### Returns
+
+-   `string` The ISO 8601 formatted string
+
+---
+
+### toLocalTime
+
+Extracts local time values from this `DateTime`.
+
+The returned table contains the following values:
+
+| Key           | Type     | Range          |
+| ------------- | -------- | -------------- |
+| `year`        | `number` | `1400 -> 9999` |
+| `month`       | `number` | `1 -> 12`      |
+| `day`         | `number` | `1 -> 31`      |
+| `hour`        | `number` | `0 -> 23`      |
+| `minute`      | `number` | `0 -> 59`      |
+| `second`      | `number` | `0 -> 60`      |
+| `millisecond` | `number` | `0 -> 999`     |
+
+#### Parameters
+
+-   `self` DateTime
+
+#### Returns
+
+-   `DateTimeValues` A table of DateTime values
+
+---
+
+### toUniversalTime
+
+Extracts UTC (universal) time values from this `DateTime`.
+
+The returned table contains the following values:
+
+| Key           | Type     | Range          |
+| ------------- | -------- | -------------- |
+| `year`        | `number` | `1400 -> 9999` |
+| `month`       | `number` | `1 -> 12`      |
+| `day`         | `number` | `1 -> 31`      |
+| `hour`        | `number` | `0 -> 23`      |
+| `minute`      | `number` | `0 -> 59`      |
+| `second`      | `number` | `0 -> 60`      |
+| `millisecond` | `number` | `0 -> 999`     |
+
+#### Parameters
+
+-   `self` DateTime
+
+#### Returns
+
+-   `DateTimeValues` A table of DateTime values
+
+---
+
+### formatLocalTime
+
+Formats this `DateTime` using the given `formatString` and `locale`, as local time.
+
+The given `formatString` is parsed using a `strftime`/`strptime`-inspired date and time formatting
+syntax, allowing tokens such as the following:
+
+| Token | Example  | Description   |
+| ----- | -------- | ------------- |
+| `%Y`  | `1998`   | Year number   |
+| `%m`  | `04`     | Month number  |
+| `%d`  | `29`     | Day number    |
+| `%A`  | `Monday` | Weekday name  |
+| `%M`  | `59`     | Minute number |
+| `%S`  | `10`     | Second number |
+
+For a full reference of all available tokens, see the
+[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
+
+If not provided, `formatString` and `locale` will default to `"%Y-%m-%d %H:%M:%S"` and `"en"`
+(english) respectively.
+
+#### Parameters
+
+-   `self` DateTime
+
+-   `formatString` `string?` A string containing formatting tokens
+
+-   `locale` `Locale?` The locale the time should be formatted in
+
+#### Returns
+
+-   `string` The formatting string
+
+---
+
+### formatUniversalTime
+
+Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time.
+
+The given `formatString` is parsed using a `strftime`/`strptime`-inspired date and time formatting
+syntax, allowing tokens such as the following:
+
+| Token | Example  | Description   |
+| ----- | -------- | ------------- |
+| `%Y`  | `1998`   | Year number   |
+| `%m`  | `04`     | Month number  |
+| `%d`  | `29`     | Day number    |
+| `%A`  | `Monday` | Weekday name  |
+| `%M`  | `59`     | Minute number |
+| `%S`  | `10`     | Second number |
+
+For a full reference of all available tokens, see the
+[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
+
+If not provided, `formatString` and `locale` will default to `"%Y-%m-%d %H:%M:%S"` and `"en"`
+(english) respectively.
+
+#### Parameters
+
+-   `self` DateTime
+
+-   `formatString` `string?` A string containing formatting tokens
+
+-   `locale` `Locale? ` The locale the time should be formatted in
+
+#### Returns
+
+-   `string` The formatting string
+
+---
+
+### now
+
+Returns a `DateTime` representing the current moment in time.
+
+#### Returns
+
+-   `DateTime` The new DateTime object
+
+---
+
+### fromUnixTimestamp
+
+Creates a new `DateTime` from the given UNIX timestamp.
+
+This timestamp may contain both a whole and fractional part - where the fractional part denotes
+milliseconds / nanoseconds.
+
+Example usage of fractions:
+
+-   `DateTime.fromUnixTimestamp(123456789.001)` - one millisecond
+-   `DateTime.fromUnixTimestamp(123456789.000000001)` - one nanosecond
+
+Note that the fractional part has limited precision down to exactly one nanosecond, any fraction
+that is more precise will get truncated.
+
+#### Parameters
+
+-   `unixTimestamp` `number` Seconds passed since the UNIX epoch
+
+#### Returns
+
+-   `DateTime` The new DateTime object
+
+---
+
+### fromUniversalTime
+
+Creates a new `DateTime` from the given date & time values table, in universal (UTC) time.
+
+The given table must contains the following values:
+
+| Key      | Type     | Range          |
+| -------- | -------- | -------------- |
+| `year`   | `number` | `1400 -> 9999` |
+| `month`  | `number` | `1 -> 12`      |
+| `day`    | `number` | `1 -> 31`      |
+| `hour`   | `number` | `0 -> 23`      |
+| `minute` | `number` | `0 -> 59`      |
+| `second` | `number` | `0 -> 60`      |
+
+An additional `millisecond` value may also be included, and should be within the range `0 -> 999`,
+but is optional.
+
+This constructor is fallible and may throw an error in the following situations:
+
+-   Date units (year, month, day) that produce an invalid date will raise an error. For example,
+    January 32nd or February 29th on a non-leap year.
+-   Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing
+    2 hours, not 2 hours and 30 minutes.
+
+#### Parameters
+
+-   `values` `DateTimeValues` Table containing date & time values
+
+#### Returns
+
+-   `DateTime` The new DateTime object
+
+---
+
+### fromLocalTime
+
+Creates a new `DateTime` from the given date & time values table, in local time.
+
+The given table must contains the following values:
+
+| Key      | Type     | Range          |
+| -------- | -------- | -------------- |
+| `year`   | `number` | `1400 -> 9999` |
+| `month`  | `number` | `1 -> 12`      |
+| `day`    | `number` | `1 -> 31`      |
+| `hour`   | `number` | `0 -> 23`      |
+| `minute` | `number` | `0 -> 59`      |
+| `second` | `number` | `0 -> 60`      |
+
+An additional `millisecond` value may also be included, and should be within the range `0 -> 999`,
+but is optional.
+
+This constructor is fallible and may throw an error in the following situations:
+
+-   Date units (year, month, day) that produce an invalid date will raise an error. For example,
+    January 32nd or February 29th on a non-leap year.
+-   Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing
+    2 hours, not 2 hours and 30 minutes.
+
+#### Parameters
+
+-   `values` `DateTimeValues` Table containing date & time values
+
+#### Returns
+
+-   `DateTime` The new DateTime object
+
+---
+
+### fromIsoDate
+
+Creates a new `DateTime` from an ISO 8601 date-time string.
+
+This constructor is fallible and may throw an error if the given string does not strictly follow the
+ISO 8601 date-time string format.
+
+Some examples of valid ISO 8601 date-time strings:
+
+-   `2020-02-22T18:12:08Z`
+-   `2000-01-31T12:34:56+05:00`
+-   `1970-01-01T00:00:00.055Z`
+
+#### Parameters
+
+-   `isoDate` `string` An ISO 8601 formatted string
+
+#### Returns
+
+-   `DateTime` The new DateTime object
+
+---
diff --git a/pages/api-reference/fs.md b/pages/api-reference/fs.md
@@ -30,7 +30,6 @@ An error will be thrown in the following situations:
 
 -   `path` does not point to an existing file.
 -   The current process lacks permissions to read the file.
--   The contents of the file cannot be read as a UTF-8 string.
 -   Some other I/O error occurred.
 
 #### Parameters

diff --git a/pages/api-reference/luau.md b/pages/api-reference/luau.md
@@ -40,7 +40,7 @@ local bytecode = luau.compile("print('Hello, World!')", {
 
 -   `source` The string that'll be compiled into bytecode
 
--   `CompileOptions` The luau compiler options used when compiling the source string
+-   `compileOptions` The luau compiler options used when compiling the source string
 
 #### Returns