libs/js/jquery-mobile-1.2.0/node_modules/grunt/node_modules/prompt/node_modules/winston/node_modules/stack-trace/Readme.md

   1 # stack-trace
   2
   3 Get v8 stack traces as an array of CallSite objects.
   4
   5 ## Install
   6
   7 ``` bash
   8 npm install stack-trace
   9 ```
  10
  11 ## Usage
  12
  13 The stack-trace module makes it easy for you to capture the current stack:
  14
  15 ``` javascript
  16 var stackTrace = require('stack-trace');
  17 var trace = stackTrace.get();
  18
  19 require('assert').strictEqual(trace[0].getFileName(), __filename);
  20 ```
  21
  22 However, sometimes you have already popped the stack you are interested in,
  23 and all you have left is an `Error` object. This module can help:
  24
  25 ``` javascript
  26 var stackTrace = require('stack-trace');
  27 var err = new Error('something went wrong');
  28 var trace = stackTrace.parse(err);
  29
  30 require('assert').strictEqual(trace[0].getFileName(), __filename);
  31 ```
  32
  33 Please note that parsing the `Error#stack` property is not perfect, only
  34 certain properties can be retrieved with it as noted in the API docs below.
  35
  36 ## Long stack traces
  37
  38 stack-trace works great with [long-stack-traces][], when parsing an `err.stack`
  39 that has crossed the event loop boundary, a `CallSite` object returning
  40 `'----------------------------------------'` for `getFileName()` is created.
  41 All other methods of the event loop boundary call site return `null`.
  42
  43 [long-stack-traces]: https://github.com/tlrobinson/long-stack-traces
  44
  45 ## API
  46
  47 ### stackTrace.get([belowFn])
  48
  49 Returns an array of `CallSite` objects, where element `0` is the current call
  50 site.
  51
  52 When passing a function on the current stack as the `belowFn` parameter, the
  53 returned array will only include `CallSite` objects below this function.
  54
  55 ### stackTrace.parse(err)
  56
  57 Parses the `err.stack` property of an `Error` object into an array compatible
  58 with those returned by `stackTrace.get()`. However, only the following methods
  59 are implemented on the returned `CallSite` objects.
  60
  61 * getTypeName
  62 * getFunctionName
  63 * getMethodName
  64 * getFileName
  65 * getLineNumber
  66 * getColumnNumber
  67 * isNative
  68
  69 Note: Except `getFunctionName()`, all of the above methods return exactly the
  70 same values as you would get from `stackTrace.get()`. `getFunctionName()`
  71 is sometimes a little different, but still useful.
  72
  73 ### CallSite
  74
  75 The official v8 CallSite object API can be found [here][v8stackapi]. A quick
  76 excerpt:
  77
  78 > A CallSite object defines the following methods:
  79 >
  80 > * **getThis**: returns the value of this
  81 > * **getTypeName**: returns the type of this as a string. This is the name of the function stored in the constructor field of this, if available, otherwise the object's [[Class]] internal property.
  82 > * **getFunction**: returns the current function
  83 > * **getFunctionName**: returns the name of the current function, typically its name property. If a name property is not available an attempt will be made to try to infer a name from the function's context.
  84 > * **getMethodName**: returns the name of the property of this or one of its prototypes that holds the current function
  85 > * **getFileName**: if this function was defined in a script returns the name of the script
  86 > * **getLineNumber**: if this function was defined in a script returns the current line number
  87 > * **getColumnNumber**: if this function was defined in a script returns the current column number
  88 > * **getEvalOrigin**: if this function was created using a call to eval returns a CallSite object representing the location where eval was called
  89 > * **isToplevel**: is this a toplevel invocation, that is, is this the global object?
  90 > * **isEval**: does this call take place in code defined by a call to eval?
  91 > * **isNative**: is this call in native V8 code?
  92 > * **isConstructor**: is this a constructor call?
  93
  94 [v8stackapi]: http://code.google.com/p/v8/wiki/JavaScriptStackTraceApi
  95
  96 ## License
  97
  98 stack-trace is licensed under the MIT license.