Show support for mode (#587)

Node fs's mkdir supports mode specification. After reviewing the source
fs-extra does as well, but is not documented. Update the documentation
to include the `options` parameter and provide a few examples of using
`mode`.

Author: robertjacobson

docs/ensureDir-sync.md

@@ -1,17 +1,29 @@
-# ensureDirSync(dir)
+# ensureDirSync(dir[,options])
 
-Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`.
+Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`. If provided, options may specify the desired mode for the directory. 
 
 **Aliases:** `mkdirsSync()`, `mkdirpSync()`
 
 - `dir` `<String>`
-
+- `options` `<Integer>|<Object>`
 ## Example:
 
 ```js
 const fs = require('fs-extra')
 
 const dir = '/tmp/this/path/does/not/exist'
+
+const desiredMode = 0o2775
+const options = {
+  mode: 0o2775
+}
+
 fs.ensureDirSync(dir)
 // dir has now been created, including the directory it is to be placed in
+
+fs.ensureDirSync(dir, desiredMod)
+// dir has now been created, including the directory it is to be placed in with permission 0o2775
+
+fs.ensureDirSync(dir, options)
+// dir has now been created, including the directory it is to be placed in with permission 0o2775
 ```

docs/ensureDir.md

@@ -1,10 +1,11 @@
-# ensureDir(dir, [callback])
+# ensureDir(dir[,options][,callback])
 
 Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`.
 
 **Aliases:** `mkdirs()`, `mkdirp()`
 
 - `dir` `<String>`
+- `options` `<Integer>|<Object>`
 - `callback` `<Function>`
 
 ## Example:
@@ -13,13 +14,23 @@ Ensures that the directory exists. If the directory structure does not exist, it
 const fs = require('fs-extra')
 
 const dir = '/tmp/this/path/does/not/exist'
+const desiredMode = 0o2775
+const options = {
+  mode: 0o2775
+}
 
 // With a callback:
 fs.ensureDir(dir, err => {
   console.log(err) // => null
   // dir has now been created, including the directory it is to be placed in
 })
 
+// With a callback and a mode integer
+fs.ensureDir(dir, desiredMode, err => {
+  console.log(err) // => null
+  // dir has now been created with mode 0o2775, including the directory it is to be placed in
+})
+
 // With Promises:
 fs.ensureDir(dir)
 .then(() => {
@@ -29,6 +40,15 @@ fs.ensureDir(dir)
   console.error(err)
 })
 
+// With Promises and a mode integer:
+fs.ensureDir(dir, desiredMode)
+.then(() => {
+  console.log('success!')
+})
+.catch(err => {
+  console.error(err)
+})
+
 // With async/await:
 async function example (directory) {
   try {
@@ -38,6 +58,16 @@ async function example (directory) {
     console.error(err)
   }
 }
-
 example(dir)
+
+// With async/await and an options object, containing mode:
+async function exampleMode (directory) {
+  try {
+    await fs.ensureDir(directory, options)
+    console.log('success!')
+  } catch (err) {
+    console.error(err)
+  }
+}
+exampleMode(dir)
 ```