kdu-eslint-parser

The ESLint custom parser for .kdu files.

⤴️ Motivation

This parser allows us to lint the <template> of .kdu files. We can make mistakes easily on <template> if we use complex directives and expressions in the template. This parser and the rules of eslint-plugin-kdu would catch some of the mistakes.

💿 Installation

npm install --save-dev eslint kdu-eslint-parser

• Requires Node.js ^12.22.0, ^14.17.0, 16.0.0 or later.
• Requires ESLint 6.0.0 or later.

📖 Usage

1. Write parser option into your .eslintrc.* file.
2. Use glob patterns or --ext .kdu CLI option.

{
    "extends": "eslint:recommended",
    "parser": "kdu-eslint-parser"
}

$ eslint "src/**/*.{js,kdu}"
# or
$ eslint src --ext .kdu

🔧 Options

parserOptions has the same properties as what espree, the default parser of ESLint, is supporting. For example:

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "sourceType": "module",
        "ecmaVersion": 2018,
        "ecmaFeatures": {
            "globalReturn": false,
            "impliedStrict": false,
            "jsx": false
        }
    }
}

parserOptions.parser

You can use parserOptions.parser property to specify a custom parser to parse <script> tags. Other properties than parser would be given to the specified parser. For example:

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "parser": "@babel/eslint-parser",
        "sourceType": "module"
    }
}

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "parser": "@typescript-eslint/parser",
        "sourceType": "module"
    }
}

You can also specify an object and change the parser separately for <script lang="...">.

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "parser": {
             // Script parser for `<script>`
            "js": "espree",

             // Script parser for `<script lang="ts">`
            "ts": "@typescript-eslint/parser",

             // Script parser for kdu directives (e.g. `k-if=` or `:attribute=`)
             // and kdu interpolations (e.g. `{{variable}}`).
             // If not specified, the parser determined by `<script lang ="...">` is used.
            "<template>": "espree",
        }
    }
}

If the parserOptions.parser is false, the kdu-eslint-parser skips parsing <script> tags completely. This is useful for people who use the language ESLint community doesn't provide custom parser implementation.

parserOptions.kduFeatures

You can use parserOptions.kduFeatures property to specify how to parse related to Kdu features. For example:

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "kduFeatures": {
            "filter": true,
            "interpolationAsNonHTML": true,
            "styleCSSVariableInjection": true,
        }
    }
}

parserOptions.kduFeatures.filter

You can use parserOptions.kduFeatures.filter property to specify whether to parse the Kdu2 filter. If you specify false, the parser does not parse | as a filter. For example:

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "kduFeatures": {
            "filter": false
        }
    }
}

If you specify false, it can be parsed in the same way as Kdu 3. The following template parses as a bitwise operation.

<template>
  <div>{{ a | b }}</div>
</template>

However, the following template that are valid in Kdu 2 cannot be parsed.

<template>
  <div>{{ a | valid:filter }}</div>
</template>

parserOptions.kduFeatures.interpolationAsNonHTML

You can use parserOptions.kduFeatures.interpolationAsNonHTML property to specify whether to parse the interpolation as HTML. If you specify true, the parser handles the interpolation as non-HTML (However, you can use HTML escaping in the interpolation). Default is true. For example:

{
    "parser": "kdu-eslint-parser",
    "parserOptions": {
        "kduFeatures": {
            "interpolationAsNonHTML": true
        }
    }
}

If you specify true, it can be parsed in the same way as Kdu 3. The following template can be parsed well.

<template>
  <div>{{a<b}}</div>
</template>

But, it cannot be parsed with Kdu 2.

parserOptions.kduFeatures.styleCSSVariableInjection

If set to true, to parse expressions in k-bind CSS functions inside <style> tags. k-bind() is parsed into the KExpressionContainer AST node and held in the KElement of <style>. Default is true.

🎇 Usage for custom rules / plugins

• This parser provides parserServices to traverse <template>.
  • defineTemplateBodyVisitor(templateVisitor, scriptVisitor, options) ... returns ESLint visitor to traverse <template>.
  • getTemplateBodyTokenStore() ... returns ESLint TokenStore to get the tokens of <template>.
  • getDocumentFragment() ... returns the root KDocumentFragment.
  • defineCustomBlocksVisitor(context, customParser, rule, scriptVisitor) ... returns ESLint visitor that parses and traverses the contents of the custom block.
  • defineDocumentVisitor(documentVisitor, options) ... returns ESLint visitor to traverses the document.
• mustache-interpolation-spacing.js is an example.

defineTemplateBodyVisitor(templateBodyVisitor, scriptVisitor, options)

Arguments

• templateBodyVisitor ... Event handlers for <template>.
• scriptVisitor ... Event handlers for <script> or scripts. (optional)
• options ... Options. (optional)
  • templateBodyTriggerSelector ... Script AST node selector that triggers the templateBodyVisitor. Default is "Program:exit". (optional)

import { AST } from "kdu-eslint-parser"

export function create(context) {
    return context.parserServices.defineTemplateBodyVisitor(
        // Event handlers for <template>.
        {
            KElement(node: AST.KElement): void {
                //...
            }
        },
        // Event handlers for <script> or scripts. (optional)
        {
            Program(node: AST.ESLintProgram): void {
                //...
            }
        },
        // Options. (optional)
        {
            templateBodyTriggerSelector: "Program:exit"
        }
    )
}

⚠️ Known Limitations

Some rules make warnings due to the outside of <script> tags. Please disable those rules for .kdu files as necessary.

• eol-last
• linebreak-style
• max-len
• max-lines
• no-trailing-spaces
• unicode-bom
• Other rules which are using the source code text instead of AST might be confused as well.

Development Tools

• npm run build compiles TypeScript source code to index.js, index.js.map, and index.d.ts.
• npm run clean removes the temporary files which are created by npm run build.
• npm run lint runs ESLint.
• npm run setup setups submodules to develop.