1 files changed, 95 insertions, 0 deletions
diff --git a/toml/README.md b/toml/README.md
new file mode 100644
index 000000000..a1acd7466
--- /dev/null
+++ b/toml/README.md
@@ -0,0 +1,95 @@
+# TOML
+
+This module parse TOML files. It follows as much as possible the
+[TOML specs](https://github.com/toml-lang/toml). Be sure to read the supported
+types as not every specs is supported at the moment and the handling in
+TypeScript side is a bit different.
+
+## Supported types and handling
+
+- :heavy_check_mark: [Keys](https://github.com/toml-lang/toml#string)
+- :exclamation: [String](https://github.com/toml-lang/toml#string)
+- :heavy_check_mark:
+  [Multiline String](https://github.com/toml-lang/toml#string)
+- :heavy_check_mark: [Literal String](https://github.com/toml-lang/toml#string)
+- :exclamation: [Integer](https://github.com/toml-lang/toml#integer)
+- :heavy_check_mark: [Float](https://github.com/toml-lang/toml#float)
+- :heavy_check_mark: [Boolean](https://github.com/toml-lang/toml#boolean)
+- :heavy_check_mark:
+  [Offset Date-time](https://github.com/toml-lang/toml#offset-date-time)
+- :heavy_check_mark:
+  [Local Date-time](https://github.com/toml-lang/toml#local-date-time)
+- :heavy_check_mark: [Local Date](https://github.com/toml-lang/toml#local-date)
+- :exclamation: [Local Time](https://github.com/toml-lang/toml#local-time)
+- :heavy_check_mark: [Table](https://github.com/toml-lang/toml#table)
+- :exclamation: [Inline Table](https://github.com/toml-lang/toml#inline-table)
+- :exclamation: [Array of Tables](https://github.com/toml-lang/toml#array-of-tables)
+
+:exclamation: _Supported with warnings see [Warning](#Warning)._
+
+### :warning: Warning
+
+#### String
+
+- Regex : Due to the spec, there is no flag to detect regex properly
+  in a TOML declaration. So the regex is stored as string.
+
+#### Integer
+
+For **Binary** / **Octal** / **Hexadecimal** numbers,
+they are stored as string to be not interpreted as Decimal.
+
+#### Local Time
+
+Because local time does not exist in JavaScript, the local time is stored as a string.
+
+#### Inline Table
+
+Inline tables are supported but nested inline property name are **not**. See below:
+
+```toml
+animal = { type = { name = "pug" } } # Supported
+animal = { type.name = "pug" }
+# not supported. Will output { "animal" : {"type.name":"pug"} }
+```
+
+#### Array of Tables
+
+At the moment only simple declarations like below are supported:
+
+```toml
+[[bin]]
+name = "deno"
+path = "cli/main.rs"
+
+[[bin]]
+name = "deno_core"
+path = "src/foo.rs"
+
+[[nib]]
+name = "node"
+path = "not_found"
+```
+
+will output:
+
+```json
+{
+  "bin": [
+    { "name": "deno", "path": "cli/main.rs" },
+    { "name": "deno_core", "path": "src/foo.rs" }
+  ],
+  "nib": [{ "name": "node", "path": "not_found" }]
+}
+```
+
+## Usage
+
+```ts
+import { parseFile, parse } from "./parser.ts";
+
+const tomlObject = parseFile("file.toml");
+
+const tomlString = 'foo.bar = "Deno"';
+const tomlObject22 = parse(tomlString);
+```