Started updating the docs for the new options

Author: JamesMessinger

README.md

@@ -67,8 +67,8 @@ $RefParser.dereference(mySchema, function(err, schema) {
     console.error(err);
   }
   else {
-    // `schema` is just a normal JavaScript object that contains your
-    // entire JSON Schema - even if it spans multiple files
+    // `schema` is just a normal JavaScript object that contains your entire JSON Schema,
+    // including referenced files, combined into a single object
     console.log(schema.definitions.person.properties.firstName);
   }
 });

docs/README.md

@@ -50,7 +50,7 @@ var parser = new $RefParser();
 parser.bundle("my-schema.json");
 ```
 
-The difference is that in the second example you now have a reference to `parser`, which means you can access the results ([`parser.schema`](ref-parser.md#schema) and [`parser.$refs`](ref-parser.md#refs)) anytime you want, rather than just in the callback function. Also, having a `$RefParser` instance allows you to benefit from **[caching](options.md#caching)**, so the next time you call [`parser.resolve()`](ref-parser.md#resolveschema-options-callback), it won't need to re-download those files again (as long as the cache hasn't expired).
+The difference is that in the second example you now have a reference to `parser`, which means you can access the results ([`parser.schema`](ref-parser.md#schema) and [`parser.$refs`](ref-parser.md#refs)) anytime you want, rather than just in the callback function. Also, having a `$RefParser` instance allows you to benefit from **[caching](options.md#cache)**, so the next time you call [`parser.resolve()`](ref-parser.md#resolveschema-options-callback), it won't need to re-download those files again (as long as the cache hasn't expired).
 
 
 ### Callbacks vs. Promises

docs/options.md

@@ -3,32 +3,99 @@ Options
 
 All [`$RefParser`](ref-parser.md) methods accept an optional `options` parameter, which you can use to customize how the JSON Schema is parsed, resolved, dereferenced, etc.
 
-If you pass an options parameter, you _don't_ need to specify _every_ option.  Any options you don't specify will use their default values, as shown below.
+If you pass an options parameter, you _don't_ need to specify _every_ option.  Any options you don't specify will use their default values.
+
+Example
+-------------------
 
 ```javascript
 $RefParser.dereference("my-schema.yaml", {
-    allow: {
-        json: false,        // Don't allow JSON files
-        empty: false        // Don't allow empty files
-    },
-    $refs: {
-        internal: false     // Don't dereference internal $refs, only external
+  parse: {
+    json: false,               // Disable the JSON parser
+    yaml: {
+      empty: false             // Don't allow empty YAML files
     },
-    cache: {
-        fs: 1,              // Cache local files for 1 second
-        http: 600           // Cache http URLs for 10 minutes
+    text: {
+      ext: [".txt", ".html"],  // Parse .txt and .html files as plain text (strings)
+      encoding: 'utf16'        // Use UTF-16 encoding
+    }
+  },
+  resolve: {
+    file: false,               // Don't resolve local file references
+    http: {
+      cache: 30000,            // Cache downloaded files for 30 seconds
+      timeout: 2000            // 2 second timeout
+    }    
+  },
+  dereference: {
+    circular: false            // Don't allow circular $refs
+  }
+});
+```
+
+
+`parse` Options
+-------------------
+The `parse` options determine how different types of files will be parsed.  JSON Schema $Ref Parser comes with built-in JSON, YAML, plain-text, and binary parsers, any of which you can configure or disable.  You can also add your own custom parsers if you want.
+
+#### Disabling a parser
+To disable a parser, just set it to `false`, like this:
+
+```javascript
+// Disable the JSON parser
+$RefParser.dereference("my-schema.yaml", { parse: { json: false } });
+```
+
+#### `order`
+Parsers run in a specific order, relative to other parsers. For example, a parser with `order: 5` will run _before_ a parser with `order: 10`.  If a parser is unable to successfully parse a file, then the next parser is tried, until one succeeds or they all fail.
+
+You can change the order in which parsers run, which is useful if you know that most of your referenced files will be a certain type, or if you add your own custom parser that you want to run _first_. 
+
+```javascript
+// Run the plain-text parser first
+$RefParser.dereference("my-schema.yaml", { parse: { text: { order: 1 } } });
+```
+
+#### `ext`
+Each parser has a list of file extensions that it will try to parse.  For example, the plain-text parser will parse most common text files, such as `.txt`, `.html`, `.xml`, etc.
+
+Multiple parsers can contain the same file extensions. For example, both the JSON parser _and_ the YAML parser will parse `.json` files.  In this case, the JSON parser will run _first_, because it has `order: 100` and the YAML parser has `order: 200`.
+
+You can set your own file extensions for any parser.  Each extension can be a string or a regular expression to test against the _full file path_.  Here's an example:
+
+```javascript
+$RefParser.dereference("my-schema.yaml", { 
+  parse: { 
+    text: { 
+        // parse text, html, and readme files as plain-text
+        ext: [".txt", ".html", /docs\/README/i] 
     }
+  }
 });
 ```
 
+#### `empty`
+All of the built-in parsers allow empty files by default. The JSON and YAML parsers will parse empty files as `null`. The text parser will parse empty files as an empty string.  The binary parser will parse empty files as an empty byte array.
+
+You can set `empty: false` on any parser, which will cause an error to be thrown if a file empty.
+
+#### Parser-specific options
+Parsers can have other options that are specific to that parser.  Currently, the only such option is `text.encoding`, which allows you to set the encoding for parsing text-based files.  The default encoding is `utf8`.
+
+#### Adding a custom parser
+TODO
+
+
+`resolve` Options
+-------------------
+
+
+`dereference` Options
+-------------------
+
+
 |Option                |Type     |Default   |Description
 |:---------------------|:--------|:---------|:----------
-|`allow.json`          |bool     |true      |Determines whether JSON files are supported
-|`allow.yaml`          |bool     |true      |Determines whether YAML files are supported<br> (note: all JSON files are also valid YAML files)
-|`allow.empty`         |bool     |true      |Determines whether it's ok for a `$ref` pointer to point to an empty file
-|`allow.unknown`       |bool     |true      |Determines whether it's ok for a `$ref` pointer to point to an unknown/unsupported file type (such as HTML, text, image, etc.). The default is to resolve unknown files as a [`Buffer`](https://nodejs.org/api/buffer.html#buffer_class_buffer)
-|`$refs.internal`      |bool     |true      |Determines whether internal `$ref` pointers (such as `#/definitions/widget`) will be dereferenced when calling [`dereference()`](ref-parser.md#dereferenceschema-options-callback).  Either way, you'll still be able to get the value using [`$Refs.get()`](refs.md#getref-options)
-|`$refs.external`      |bool     |true      |Determines whether external `$ref` pointers get resolved/dereferenced. If `false`, then no files/URLs will be retrieved.  Use this if you only want to allow single-file schemas.
 |`$refs.circular`      |bool or "ignore"     |true      |Determines whether [circular `$ref` pointers](README.md#circular-refs) are allowed. If `false`, then a `ReferenceError` will be thrown if the schema contains a circular reference.<br><br> If set to `"ignore"`, then circular references will _not_ be dereferenced, even when calling [`dereference()`](ref-parser.md#dereferenceschema-options-callback). No error will be thrown, but the [`$Refs.circular`](refs.md#circular) property will still be set to `true`.
 |`cache.fs`            |number   |60        |<a name="caching"></a>The length of time (in seconds) to cache local files.  The default is one minute.  Setting to zero will cache forever.
 |`cache.http`          |number   |300       |The length of time (in seconds) to cache HTTP URLs.  The default is five minutes.  Setting to zero will cache forever.