aboutsummaryrefslogtreecommitdiff
path: root/node_modules/sanitize-filename/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'node_modules/sanitize-filename/README.md')
-rw-r--r--node_modules/sanitize-filename/README.md103
1 files changed, 103 insertions, 0 deletions
diff --git a/node_modules/sanitize-filename/README.md b/node_modules/sanitize-filename/README.md
new file mode 100644
index 0000000..1287d30
--- /dev/null
+++ b/node_modules/sanitize-filename/README.md
@@ -0,0 +1,103 @@
+# sanitize-filename [![build status](https://secure.travis-ci.org/parshap/node-sanitize-filename.svg?branch=master)](http://travis-ci.org/parshap/node-sanitize-filename)
+
+Sanitize a string to be safe for use as a filename by removing directory
+paths and invalid characters.
+
+## Install
+
+[npm: *sanitize-filename*](https://www.npmjs.com/package/sanitize-filename)
+
+```
+npm install sanitize-filename
+```
+
+## Example
+
+```js
+var sanitize = require("sanitize-filename");
+
+// Some string that may be unsafe or invalid as a filename
+var UNSAFE_USER_INPUT = "~/.\u0000ssh/authorized_keys";
+
+// Sanitize the string to be safe for use as a filename.
+var filename = sanitize(UNSAFE_USER_INPUT);
+// -> "~.sshauthorized_keys"
+```
+
+## Details
+
+*sanitize-filename* removes the following:
+
+ * [Control characters][] (`0x00`–`0x1f` and `0x80`–`0x9f`)
+ * [Reserved characters][] (`/`, `?`, `<`, `>`, `\`, `:`, `*`, `|`, and
+ `"`)
+ * Unix reserved filenames (`.` and `..`)
+ * Trailing periods and spaces ([for Windows][windows trailing])
+ * Windows reserved filenames (`CON`, `PRN`, `AUX`, `NUL`, `COM1`,
+ `COM2`, `COM3`, `COM4`, `COM5`, `COM6`, `COM7`, `COM8`, `COM9`,
+ `LPT1`, `LPT2`, `LPT3`, `LPT4`, `LPT5`, `LPT6`, `LPT7`, `LPT8`, and
+ `LPT9`)
+
+[control characters]: https://en.wikipedia.org/wiki/C0_and_C1_control_codes
+[reserved characters]: https://kb.acronis.com/content/39790
+[windows trailing]: https://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx#Naming_Conventions
+
+The resulting string is truncated to [255 bytes in length][255]. The
+string will not contain any directory paths and will be safe to use as a
+filename.
+
+[255]: http://unix.stackexchange.com/questions/32795/what-is-the-maximum-allowed-filename-and-folder-size-with-ecryptfs
+
+### Empty String `""` Result
+
+An empty string `""` can be returned. For example:
+
+```js
+var sanitize = require("sanitize-filename");
+sanitize("..")
+// -> ""
+
+```
+
+### Non-unique Filenames
+
+Two different inputs can return the same value. For example:
+
+```js
+var sanitize = require("sanitize-filename");
+sanitize("file?")
+// -> "file"
+sanitize ("*file*")
+// -> "file"
+```
+
+### File Systems
+
+Sanitized filenames will be safe for use on modern Windows, OS X, and
+Unix file systems (`NTFS`, `ext`, etc.).
+
+[`FAT` 8.3 filenames][8.3] are not supported.
+
+[8.3]: https://en.wikipedia.org/wiki/8.3_filename
+
+#### Test Your File System
+
+The test program will use various strings (including the [Big List of
+Naughty Strings][blns]) to create files in the working directory. Run
+`npm test` to run tests against your file system.
+
+[blns]: https://github.com/minimaxir/big-list-of-naughty-strings
+
+## API
+
+### `sanitize(inputString, [options])`
+
+Sanitize `inputString` by removing or replacing invalid characters.
+
+Options:
+
+ * `options.replacement`: *optional, string/function, default: `""`*. If passed
+ as a string, it's used as the replacement for invalid characters. If passed as
+ a function, the function will be called with the invalid characters and it's
+ return value will be used as the replacement. See [`String.prototype.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+ for more info.