Skip to content
This repository has been archived by the owner on Feb 8, 2020. It is now read-only.

Latest commit

 

History

History
314 lines (219 loc) · 13.2 KB

.verb.md

File metadata and controls

314 lines (219 loc) · 13.2 KB
Raw

Parse a function

{%= name %} [![npm version][npmv-img]][npmv-url] [![github release][github-release-img]][github-release-url] [![License][license-img]][license-url]

{%= description %}

{%= include('highlight') %}

Quality Assurance 💯

Code Style Standard [![Linux Build][circleci-img]][circleci-url] [![Code Coverage][codecov-img]][codecov-url] [![Dependencies Status][dependencies-img]][dependencies-url] Renovate App Status

If you have any how-to kind of questions, please read Code of Conduct and join the chat room or [open an issue][open-issue-url].
You may also read the Contributing Guide. There, beside "How to contribute?", we describe everything stated by the badges.

Make A Pull Request Code Format Prettier [![Node Security Status][nodesecurity-img]][nodesecurity-url] Conventional Commits Semantically Released Renovate App Status

Project is semantically & automatically released on [CircleCI][codecov-url] with [new-release][] and its New Release Github Bot.

![All Contributors Spec][all-contributors-img] Newsletter Subscribe Give thanks [![Share Love Tweet][share-love-img]][share-love-url] [![NPM Downloads Weekly][downloads-weekly-img]][npmv-url] [![NPM Downloads Monthly][downloads-monthly-img]][npmv-url] [![NPM Downloads Total][downloads-total-img]][npmv-url]

Features

  • Always up-to-date: auto-publish new version when new version of dependency is out, Renovate
  • Standard: using StandardJS, Prettier, SemVer, Semantic Release and conventional commits
  • Smart Plugins: for extending the core API or the end Result, see .use method and Plugins Architecture
  • Extensible: using plugins for working directly on AST nodes, see the Plugins Architecture
  • ES2017 Ready: by using .parseExpression method of the [babylon][] v7.x parser
  • Customization: allows switching the parser, through options.parse
  • Support for: arrow functions, default parameters, generators and async/await functions
  • Stable: battle-tested in production and against all parsers - [espree][], [acorn][], [babylon][]
  • Tested: with 450+ tests for 200% coverage

Table of Contents

Install

This project requires Node.js v{%= engines.node.slice(2) %} and above. Use yarn v{%= engines.yarn.slice(2) %} / npm v{%= engines.npm.slice(2) %} or above to install it.

$ yarn add {%= name %}

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.

back to top

Notes

Throws in one specific case

see: issue #3 and test/index.js#L229-L235

It may throw in one specific case, otherwise it won't throw, so you should relay on the result.isValid for sure.

Function named "anonymous"

see: test/index.js#L319-L324 and Result section

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.

Real anonymous function

see: test/index.js#L326-L331 and Result section

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.

back to top

Plugins Architecture

see: the .use method, test/index.js#L305-L317 and test/index.js#L396-L414

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.

back to top

API

Review carefully the provided examples and the working tests.

{%= apidocs('src/index.js') %}

back to top

Result

In the result object you have name, args, params, body and few hidden properties that can be useful to determine what the function is - arrow, regular, async/await or generator.

  • name {String|null}: name of the passed function or null if anonymous
  • args {Array}: arguments of the function
  • params {String}: comma-separated list representing the args
  • defaults {Object}: key/value pairs, useful when use ES2015 default arguments
  • body {String}: actual body of the function, respects trailing newlines and whitespaces
  • isValid {Boolean}: is the given value valid or not, that's because it never throws!
  • isAsync {Boolean}: true if function is ES2015 async/await function
  • isArrow {Boolean}: true if the function is arrow function
  • isNamed {Boolean}: true if function has name, or false if is anonymous
  • isGenerator {Boolean}: true if the function is ES2015 generator function
  • isAnonymous {Boolean}: true if the function don't have name

back to top

{% if (verb.related && verb.related.list && verb.related.list.length) { %}

Related

{%= related(verb.related.list, { words: 12 }) %} {% } %}

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue][open-issue-url].
Please read the Contributing Guide and Code of Conduct documents for advices.

Author

License

{%= copyright({ start: licenseStart, linkify: true, prefix: 'Copyright', symbol: '©' }) %} {%= licenseStatement %}

{%= include('footer') %}
Project automation and management with [hela][] task framework.

{%= reflinks(verb.reflinks) %}

[npmv-url]: https://www.npmjs.com/package/{%= name %} [npmv-img]: https://img.shields.io/npm/v/{%= name %}.svg?label=npm%20version

[github-release-url]: https://github.com/{%= repository %}/releases/latest [github-release-img]: https://img.shields.io/github/release/{%= repository %}.svg?label=github%20release

[license-url]: https://github.com/{%= repository %}/blob/master/LICENSE [license-img]: https://img.shields.io/badge/license-{%= license.replace('-', '%20') %}-blue.svg

[bithound-score-url]: https://www.bithound.io/github/{%= repository %} [bithound-score-img]: https://www.bithound.io/github/{%= repository %}/badges/score.svg

[bithound-code-url]: https://www.bithound.io/github/{%= repository %} [bithound-code-img]: https://www.bithound.io/github/{%= repository %}/badges/code.svg

[circleci-url]: https://circleci.com/gh/{%= repository %}/tree/master [circleci-img]: https://img.shields.io/circleci/project/github/{%= repository %}/master.svg

[codecov-url]: https://codecov.io/gh/{%= repository %} [codecov-img]: https://img.shields.io/codecov/c/github/{%= repository %}/master.svg

[bithound-deps-url]: https://www.bithound.io/github/{%= repository %}/dependencies/npm [bithound-deps-img]: https://www.bithound.io/github/{%= repository %}/badges/dependencies.svg

[dependencies-url]: https://david-dm.org/{%= repository %} [dependencies-img]: https://img.shields.io/david/{%= repository %}.svg

[nodesecurity-url]: https://nodesecurity.io/orgs/tunnckocore/projects/{%= nspId %}/master [nodesecurity-img]: https://nodesecurity.io/orgs/tunnckocore/projects/{%= nspId %}/badge

[nodeversion-img]: https://img.shields.io/node/v/{%= name %}.svg

[all-contributors-img]: https://img.shields.io/github/contributors/{%= repository %}.svg?label=all%20contributors&colorB=ffa500

[downloads-weekly-img]: https://img.shields.io/npm/dw/{%= name %}.svg [downloads-monthly-img]: https://img.shields.io/npm/dm/{%= name %}.svg [downloads-total-img]: https://img.shields.io/npm/dt/{%= name %}.svg

[share-love-url]: https://twitter.com/intent/tweet?text={%= encodeURI(homepage) %}&via=tunnckoCore [share-love-img]: https://img.shields.io/badge/tweet-about-1da1f2.svg

[open-issue-url]: https://github.com/{%= repository %}/issues/new [highlighted-link]: https://ghub.now.sh/{%= verb.related.highlight %} [author-link]: https://i.am.charlike.online