www.aleph1.co.uk Git - yaffs-website/blob - node_modules/error-ex/README.md

   1 # node-error-ex [![Travis-CI.org Build Status](https://img.shields.io/travis/Qix-/node-error-ex.svg?style=flat-square)](https://travis-ci.org/Qix-/node-error-ex) [![Coveralls.io Coverage Rating](https://img.shields.io/coveralls/Qix-/node-error-ex.svg?style=flat-square)](https://coveralls.io/r/Qix-/node-error-ex)
   2 > Easily subclass and customize new Error types
   3
   4 ## Examples
   5 To include in your project:
   6 ```javascript
   7 var errorEx = require('error-ex');
   8 ```
   9
  10 To create an error message type with a specific name (note, that `ErrorFn.name`
  11 will not reflect this):
  12 ```javascript
  13 var JSONError = errorEx('JSONError');
  14
  15 var err = new JSONError('error');
  16 err.name; //-> JSONError
  17 throw err; //-> JSONError: error
  18 ```
  19
  20 To add a stack line:
  21 ```javascript
  22 var JSONError = errorEx('JSONError', {fileName: errorEx.line('in %s')});
  23
  24 var err = new JSONError('error')
  25 err.fileName = '/a/b/c/foo.json';
  26 throw err; //-> (line 2)-> in /a/b/c/foo.json
  27 ```
  28
  29 To append to the error message:
  30 ```javascript
  31 var JSONError = errorEx('JSONError', {fileName: errorEx.append('in %s')});
  32
  33 var err = new JSONError('error');
  34 err.fileName = '/a/b/c/foo.json';
  35 throw err; //-> JSONError: error in /a/b/c/foo.json
  36 ```
  37
  38 ## API
  39
  40 #### `errorEx([name], [properties])`
  41 Creates a new ErrorEx error type
  42
  43 - `name`: the name of the new type (appears in the error message upon throw;
  44   defaults to `Error.name`)
  45 - `properties`: if supplied, used as a key/value dictionary of properties to
  46   use when building up the stack message. Keys are property names that are
  47   looked up on the error message, and then passed to function values.
  48         - `line`: if specified and is a function, return value is added as a stack
  49     entry (error-ex will indent for you). Passed the property value given
  50     the key.
  51   - `stack`: if specified and is a function, passed the value of the property
  52     using the key, and the raw stack lines as a second argument. Takes no
  53     return value (but the stack can be modified directly).
  54   - `message`: if specified and is a function, return value is used as new
  55     `.message` value upon get. Passed the property value of the property named
  56     by key, and the existing message is passed as the second argument as an
  57     array of lines (suitable for multi-line messages).
  58
  59 Returns a constructor (Function) that can be used just like the regular Error
  60 constructor.
  61
  62 ```javascript
  63 var errorEx = require('error-ex');
  64
  65 var BasicError = errorEx();
  66
  67 var NamedError = errorEx('NamedError');
  68
  69 // --
  70
  71 var AdvancedError = errorEx('AdvancedError', {
  72         foo: {
  73                 line: function (value, stack) {
  74                         if (value) {
  75                                 return 'bar ' + value;
  76                         }
  77                         return null;
  78                 }
  79         }
  80 }
  81
  82 var err = new AdvancedError('hello, world');
  83 err.foo = 'baz';
  84 throw err;
  85
  86 /*
  87         AdvancedError: hello, world
  88             bar baz
  89             at tryReadme() (readme.js:20:1)
  90 */
  91 ```
  92
  93 #### `errorEx.line(str)`
  94 Creates a stack line using a delimiter
  95
  96 > This is a helper function. It is to be used in lieu of writing a value object
  97 > for `properties` values.
  98
  99 - `str`: The string to create
 100   - Use the delimiter `%s` to specify where in the string the value should go
 101
 102 ```javascript
 103 var errorEx = require('error-ex');
 104
 105 var FileError = errorEx('FileError', {fileName: errorEx.line('in %s')});
 106
 107 var err = new FileError('problem reading file');
 108 err.fileName = '/a/b/c/d/foo.js';
 109 throw err;
 110
 111 /*
 112         FileError: problem reading file
 113             in /a/b/c/d/foo.js
 114             at tryReadme() (readme.js:7:1)
 115 */
 116 ```
 117
 118 #### `errorEx.append(str)`
 119 Appends to the `error.message` string
 120
 121 > This is a helper function. It is to be used in lieu of writing a value object
 122 > for `properties` values.
 123
 124 - `str`: The string to append
 125   - Use the delimiter `%s` to specify where in the string the value should go
 126
 127 ```javascript
 128 var errorEx = require('error-ex');
 129
 130 var SyntaxError = errorEx('SyntaxError', {fileName: errorEx.append('in %s')});
 131
 132 var err = new SyntaxError('improper indentation');
 133 err.fileName = '/a/b/c/d/foo.js';
 134 throw err;
 135
 136 /*
 137         SyntaxError: improper indentation in /a/b/c/d/foo.js
 138             at tryReadme() (readme.js:7:1)
 139 */
 140 ```
 141
 142 ## License
 143 Licensed under the [MIT License](http://opensource.org/licenses/MIT).
 144 You can find a copy of it in [LICENSE](LICENSE).