This project requires Node.js>=8.11(see
Support & Release Policy).
Install it using yarn or
npm. We highly recommend to use Yarn when you
think to contribute to this project.
$ yarn add parse-function
Which version to use?
There's no breaking changes between the v2.x version. The only breaking is
v2.1 which also is not working properly, so no use it.
Use v2.0.x
When you don't need support for arrow functions and es6 default params. This
version uses a RegExp expression to work.
Use v2.2.x
Only when you need a basic support for es6 features like arrow functions.
This version uses a RegExp expression to work.
Use v2.3.x
When you want full* support for arrow functions and es6 default params.
Where this "full", means "almost full", because it has bugs. This version also
uses (acorn.parse) real parser to do the parsing.
Use v3.x
When you want to use different parser instead of the default babylon.parse, by
passing custom parse function to the options.parse option. From this version
we require node >= 4.
Use v4.x
When you want full customization and most stable support for old and modern
features. This version uses babylon.parseExpression for parsing and provides a
Plugins API. See the Features section for
more info.
Use v5.x
It is basically the same as v4, but requires Node 6 & npm 5. Another is
boilerplate stuff.
If you pass a function which is named "anonymous" the result.name will be
'anonymous', but the result.isAnonymous will be false and result.isNamed
will be true, because in fact it's a named function.
Only if you pass really an anonymous function you will get result.name equal
to null, result.isAnonymous equal to true and result.isNamed equal to
false.
A more human description of the plugin mechanism. Plugins are synchronous -
no support and no need for async plugins here, but notice that you can do
that manually, because that exact architecture.
The first function that is passed to the .use method is used for
extending the core API, for example adding a new method to the app instance.
That function is immediately invoked.
const parseFunction = require('parse-function');const app = parseFunction();app.use((self) => { // self is same as `app` console.log(self.use); console.log(self.parse); console.log(self.define); self.define(self, 'foo', (bar) => bar + 1);});console.log(app.foo(2)); // => 3
On the other side, if you want to access the AST of the parser, you should
return a function from that plugin, which function is passed with
(node, result) signature.
This function is lazy plugin, it is called only when the .parse method
is called.
const parseFunction = require('parse-function');const app = parseFunction();app.use((self) => { console.log('immediately called'); return (node, result) => { console.log('called only when .parse is invoked'); console.log(node); console.log(result); };});
Where 1) the node argument is an object - actual and real AST Node coming
from the parser and 2) the result is an object too - the end
Result, on which you can add more properties if you want.
Initializes with optional opts object which is passed directly to the
desired parser and returns an object with .use and .parse methods. The
default parse which is used is babylon's .parseExpression method from
v7.
Signature
function(opts = {})
Params
opts{object} - optional, merged with options passed to .parse method
returns{object} - app object with .use and .parse methods
Examples
const parseFunction = require('parse-function');const app = parseFunction({ ecmaVersion: 2017,});const fixtureFn = (a, b, c) => { a = b + c; return a + 2;};const result = app.parse(fixtureFn);console.log(result);// see moreconsole.log(result.name); // => nullconsole.log(result.isNamed); // => falseconsole.log(result.isArrow); // => trueconsole.log(result.isAnonymous); // => true// array of names of the argumentsconsole.log(result.args); // => ['a', 'b', 'c']// comma-separated names of the argumentsconsole.log(result.params); // => 'a, b, c'
Parse a given code and returns a result object with useful properties -
such as name, body and args. By default it uses Babylon parser, but you
can switch it by passing options.parse - for example
options.parse: acorn.parse. In the below example will show how to use
acorn parser, instead of the default one.
Params
code{Function|string} - any kind of function or string to be parsed
options{object} - directly passed to the parser babylon, acorn, espree
options.parse{Function} - by default babylon.parseExpression, all
options are passed as second argument
returns{object} - result see result section for more info
Add a plugin fn function for extending the API or working on the AST nodes.
The fn is immediately invoked and passed with app argument which is
instance of parseFunction() call. That fn may return another function that
accepts (node, result) signature, where node is an AST node and result
is an object which will be returned result from the .parse
method. This retuned function is called on each node only when .parse method
is called.
Define a non-enumerable property on an object. Just a convenience mirror of
the define-property library, so check out its docs. Useful to be used in
plugins.
Params
obj{object} - the object on which to define the property
prop{string} - the name of the property to be defined or modified
val{any} - the descriptor for the property being defined or modified
returns{object} - obj the passed object, but modified
Examples
const parseFunction = require('parse-function');const app = parseFunction();// use it like `define-property` libconst obj = {};app.define(obj, 'hi', 'world');console.log(obj); // => { hi: 'world' }// or define a custom plugin that adds `.foo` property// to the end result, returned from `app.parse`app.use((app) => { return (node, result) => { // this function is called // only when `.parse` is called app.define(result, 'foo', 123); return result; };});// fixture function to be parsedconst asyncFn = async (qux) => { const bar = await Promise.resolve(qux); return bar;};const result = app.parse(asyncFn);console.log(result.name); // => nullconsole.log(result.foo); // => 123console.log(result.args); // => ['qux']console.log(result.isAsync); // => trueconsole.log(result.isArrow); // => trueconsole.log(result.isNamed); // => falseconsole.log(result.isAnonymous); // => true
For bug reports and feature requests, please join our community
forum and open a thread there with prefixing the title of the thread with the
name of the project if there's no separate channel for it.
Consider reading the
Support and Release Policy
guide if you are interested in what are the supported Node.js versions and how
we proceed. In short, we support latest two even-numbered Node.js release lines.
Support the project
Become a Partner or Sponsor? :dollar: Check the OpenSource
Commision (tier). :tada: You can get your company logo, link & name on this
file. It's also rendered on package's page in npmjs.com and
yarnpkg.com sites too! :rocket:
Not financial support? Okey!
Pull requests,
stars and all kind of
contributions
are always welcome. :sparkles:
Contributors
This project follows the
all-contributors
specification. Contributions of any kind are welcome!
Thanks goes to these wonderful people
(emoji key), consider showing
your support to them: