Fix two examples

docs/examples/datas/config.conf

@@ -0,0 +1,10 @@
+name: 'example-sonparser'
+version: '0.0.0'
+description: 'An example of sonparser'
+keywords: [
+  'example'
+  'more'
+  'complexible'
+]
+scripts:
+  test: 'echo "not implements!" && exit 1'

docs/examples/datas/config.cson

@@ -0,0 +1,10 @@
+name: 'example-sonparser'
+version: '0.0.0'
+description: 'An example of sonparser'
+keywords: [
+  'example'
+  'more'
+  'complexible'
+]
+scripts:
+  test: 'echo "not implements!" && exit 1'

docs/examples/datas/config.json

@@ -0,0 +1,13 @@
+{
+  "name": "example-sonparser",
+  "version": "0.0.0",
+  "description": "An example of sonparser",
+  "keywords": [
+    "example",
+    "more",
+    "complexible"
+  ],
+  "scripts": {
+    "test": "echo \"not implements!\" && exit 1"
+  }
+}

docs/examples/datas/illconf.cson

@@ -0,0 +1,11 @@
+name: 'example-sonparser'
+version: 0
+description: 'An example of sonparser'
+keywords: [
+  'example'
+  'more'
+  'complexible'
+  true
+]
+scripts:
+  test: 1

docs/examples/datas/invalid.cson

@@ -0,0 +1,10 @@
+name: 'example-sonparser'
+version: '0.0.0'
+description: 'An example of sonparser', 'invalid!'
+keywords: [
+  'example'
+  'more'
+  'complexible'
+]
+scripts:
+  test: 'echo "not implements!" && exit 1'

docs/examples/datas/normal.txt

@@ -0,0 +1,2 @@
+This is normal text file.
+This is not son file.

docs/examples/file.js

@@ -0,0 +1,155 @@
+const sparse = require("sonparser");
+const assert = require("assert");
+const path = require("path");
+
+function resolvePath(pathStr) {
+  return path.isAbsolute(pathStr)
+    ? pathStr
+    : path.join(__dirname, pathStr)
+    ;
+}
+
+const myConfParser = sparse.hasProperties([
+  ["private", sparse.boolean.option(false)],
+  ["name", sparse.string],
+  ["version", sparse.string],
+  ["description", sparse.string],
+  ["keywords", sparse.array(sparse.string).option([])],
+  ["scripts", sparse.object],
+  ["repository", sparse.hasProperties([
+    ["type", sparse.string],
+    ["url", sparse.string],
+  ]).option({
+    "type": "git",
+    "url": "",
+  })],
+]).desc("failed to parse my config", "my config");
+
+// pattern throw Error on failure
+assert.deepEqual(
+  sparse.parseFile(resolvePath("datas/config.json"), myConfParser),
+  {
+    "private": false,
+    "name": "example-sonparser",
+    "version": "0.0.0",
+    "description": "An example of sonparser",
+    "keywords": [
+      "example",
+      "more", "complexible",
+    ],
+    "scripts": {
+      "test": "echo \"not implements!\" && exit 1",
+    },
+    "repository": {
+      "type": "git",
+      "url": "",
+    },
+  }
+); // success
+
+
+assert.deepEqual(
+  sparse.parseFile(resolvePath("datas/config.cson"), myConfParser),
+  {
+    "private": false,
+    "name": "example-sonparser",
+    "version": "0.0.0",
+    "description": "An example of sonparser",
+    "keywords": [
+      "example",
+      "more", "complexible",
+    ],
+    "scripts": {
+      "test": "echo \"not implements!\" && exit 1",
+    },
+    "repository": {
+      "type": "git",
+      "url": "",
+    },
+  }
+); // success
+
+/**
+ * Unusual extension is also ok.
+ * It will be tryed by all son format.
+ */
+assert.deepEqual(
+  sparse.parseFile(resolvePath("datas/config.conf"), myConfParser),
+  {
+    "private": false,
+    "name": "example-sonparser",
+    "version": "0.0.0",
+    "description": "An example of sonparser",
+    "keywords": [
+      "example",
+      "more", "complexible",
+    ],
+    "scripts": {
+      "test": "echo \"not implements!\" && exit 1",
+    },
+    "repository": {
+      "type": "git",
+      "url": "",
+    },
+  }
+); // success
+
+/**
+ * Type check error or convert missing error will be thrown.
+ * You can receive and output error message.
+ */
+try {
+  sparse.parseFile(resolvePath("datas/illconf.cson"), myConfParser);
+  assert(false, "Don't reach here!");
+} catch (e) {
+  assert(e instanceof sparse.ConfigParseError);
+  console.log(`Got Error: ${e.message}`);
+}
+
+/**
+ * errno error will be recept
+ */
+assert.throws(
+  () => sparse.parseFile("not exists file!", myConfParser),
+  Error
+); // failure
+
+/**
+ * parse format error will be recept.
+ */
+assert.throws(
+  () => sparse.parseFile(resolvePath("datas/invalid.cson"), myConfParser),
+  Error
+); // failure
+
+/**
+ * not son file will also receive parse format error.
+ */
+assert.throws(
+  () => sparse.parseFile(resolvePath("datas/normal.txt"), myConfParser),
+  Error
+); // failure
+
+// you can use with status method.
+const resultConfig = sparse.parseFileWithStatus(resolvePath("datas/config.conf"), myConfParser);
+assert.strictEqual(resultConfig.status, true);
+assert.deepEqual(
+  resultConfig.value,
+  {
+    "private": false,
+    "name": "example-sonparser",
+    "version": "0.0.0",
+    "description": "An example of sonparser",
+    "keywords": [
+      "example",
+      "more", "complexible",
+    ],
+    "scripts": {
+      "test": "echo \"not implements!\" && exit 1",
+    },
+    "repository": {
+      "type": "git",
+      "url": "",
+    },
+  }
+);

docs/examples/main.js

@@ -0,0 +1,136 @@
+const sparse = require("sonparser");
+const assert = require("assert");
+
+const nestConsoleReporter = sparse.Reporters.nestReporter(console.log);
+
+/**
+ * check boolean
+ */
+const booleanParser = sparse.boolean;
+
+const resultCheckBoolean = booleanParser.parse(true);
+assert.strictEqual(
+  resultCheckBoolean,
+  true
+);
+
+assert.throws(
+  () => booleanParser.parse("not boolean!"),
+  sparse.ConfigParseError
+);
+
+// if you don't want to use try-catch
+const resultCheckBooleanSafetySuccess = booleanParser.parseWithStatus(false);
+assert.strictEqual(
+  resultCheckBooleanSafetySuccess.status,
+  true
+);
+assert.strictEqual(
+  resultCheckBooleanSafetySuccess.value,
+  false
+);
+
+const resultCheckBooleanSafetyFailure = booleanParser.parseWithStatus("not boolean!");
+assert.strictEqual(
+  resultCheckBooleanSafetyFailure.status,
+  false
+);
+
+// you can see more human readable message by using reporters
+/**
+ * Output:
+ * this : "not boolean!" is not 'boolean'
+ */
+try {
+  booleanParser.parseWithReporter("not boolean!", nestConsoleReporter);
+} catch (e) {
+  // catch Error
+}
+
+/**
+ * check and convert my object
+ */
+const myObjectParser = sparse.hasProperties([
+  ["private", sparse.boolean.option(false)],
+  ["name", sparse.string],
+  ["version", sparse.string],
+  ["description", sparse.string],
+  ["keywords", sparse.array(sparse.string).option([])],
+  ["scripts", sparse.object],
+  ["repository", sparse.hasProperties([
+    ["type", sparse.string],
+    ["url", sparse.string],
+  ]).option({
+    "type": "git",
+    "url": "",
+  })],
+]);
+
+const resultCheckMyObject = myObjectParser.parse({
+  "name": "example-sonparser",
+  "version": "0.0.0",
+  "description": "An example of sonparser",
+  "keywords": [
+    "example",
+    "more", "complexible",
+  ],
+  "scripts": {
+    "test": "echo \"not implements!\" && exit 1",
+  },
+});
+assert.deepEqual(
+  resultCheckMyObject,
+  {
+    "private": false,
+    "name": "example-sonparser",
+    "version": "0.0.0",
+    "description": "An example of sonparser",
+    "keywords": [
+      "example",
+      "more", "complexible",
+    ],
+    "scripts": {
+      "test": "echo \"not implements!\" && exit 1",
+    },
+    "repository": {
+      "type": "git",
+      "url": "",
+    },
+  }
+);
+
+assert.throws(
+  () => myObjectParser.parse("not my object!"),
+  sparse.ConfigParseError
+);
+
+// you can see more human readable message by using reporters
+/**
+ * Output:
+ * this : failed to parse elem of 'object'
+ * ├── .private : "not boolean!" is not 'boolean'
+ * ├── .version : 0 is not 'string'
+ * ├─┬ .keywords : failed to parse elem of 'array'
+ * │ └── [1] : true is not 'string'
+ * ├── .scripts : undefined is not 'object'
+ * └─┬ .repository : failed to parse elem of 'object'
+ *   └── .type : 0 is not 'string'
+ */
+try {
+  myObjectParser.parseWithReporter({
+    "private": "not boolean!",
+    "name": "example-sonparser",
+    "version": 0,
+    "description": "An example of sonparser",
+    "keywords": [
+      "example",
+      true,
+    ],
+    "repository": {
+      "type": 0,
+      "url": "",
+    },
+  }, nestConsoleReporter);
+} catch (e) {
+  // catch Error
+}

docs/man/README.md

@@ -24,7 +24,7 @@ For more information, see and find [examples][examples].
 
 You can see really patterns on [main examples][main example], and file patterns on [file examples][file example].
 
- 1. Choose or create by chaining or customize parsers
+ 1. Choose or create by chaining or customize parsers (you can find parsers on [here][parsers document])
 
 ```javascript
 const chosenParser = sonparser.boolean;
@@ -34,13 +34,13 @@ const chainParser = sonparser
   .option(true);
 ```
 
- 2. Optionally, choose a reporter
+ 2. Optionally, choose a reporter (you can find reporters on [here][reporters document])
 
 ```javascript
 const nestReporter = sonparser.Reporters.nestReporter;
 ```
 
- 3. Give the target JSON object to a parser
+ 3. Give the target JSON object to a parser (you can see more parse flow information on [here][methods document])
 
 ```javascript
 return chainParser.parse(true);
@@ -53,6 +53,7 @@ return chainParser.parseWithReporter("not expected!", nestReporter);
 
 ## Links
 
+ * [methods document][methods document]
  * [parsers document][parsers document]
  * [reporters document][reporters document]
  * [main example][main example]
@@ -65,6 +66,7 @@ return chainParser.parseWithReporter("not expected!", nestReporter);
 [examples]: ../examples
 [main example]: ../examples/main.js
 [file example]: ../examples/file.js
+[methods document]: ./methods.md
 [parsers document]: ./parsers.md
 [reporters document]: ./reporters.md
 [parsimmon-url]: https://www.npmjs.com/package/parsimmon