Skip to content

Quodatum/xqlint

Repository files navigation

@Quodatum/XQLint

GitHub release (latest SemVer including pre-releases) GitHub GitHub last commit

GitHub Workflow Status Libraries.io dependency status for latest release, scoped npm package

npm @quodatum/xqlint

XQLint parses XQuery files and returns errors and warnings based on static code analysis. It provides the following features:

  • Lint: errors and warnings based on static code analysis.
  • Format: standardised indentation of source.
  • AST: Abstract syntax tree as XML.
  • xqdoc: json object with information similar to the xqdoc XML format
  • Completion: suggestions for line completion given a source and location.
  • Highlight console source listing using https://www.npmjs.com/package/colors
  • Context analysis for a position in source

The goal of this project is to support XQuery development tools, particularly for BaseX (9.7+).

This project is in an Alpha state - errors and changes expected.

This project began as a fork of the marvelous wcandillon/xqlint. but many features have been added and some, such as JSONiq support, removed.

Earlier versions quodatum/xqlint have been used as a drop-in replacement for wcandillon/xqlint in the following projects:

Due to changes in the range object this is no longer as simple.

Installation

XQlint is published on npm Install Node.js and NPM for your system (Mac, Windows or Linux). Then install the command line tool using:

$ npm install @quodatum/xqlint -g

Command line usage

Lint

Analyse code for potential errors. In file or directory

Examples

xqlint lint -pbasex-9 .
xqlint lint . --processor basex-10

Options

  • --processor name or -pname processor libraries to load
  • --style-check no or -s yes/no. reports on trailing whitespace, tab use
$ xqlint lint <path> [-s, --style-check <yes, no>]

windows..

xqlint --no-color lint C:\Users\andy\git\proj\XML-CMS\data_server\eapp\  >report.txt

xqlint lint --style-check yes cases\history.xqm 

Format

$ xqlint format <path>

xqdoc JSON object

$ xqlint xqdoc <path>
{
    "ns" : "http://www.w3.org/2005/xpath-functions/math", 
    "description" : " This module contains all the functions part of the\n W3C XPath and XQuery Functions and Operators 3.0\n section \"4.7 Trigonometric and exponential functions\".\n", 
    "sees" : [ "<xqdoc:see xmlns:xqdoc=\"http://www.xqdoc.org/1.0\">http://www.w3.org/TR/xpath-functions-30/#trigonometry</xqdoc:see>" ], 
    "authors" : [ "<xqdoc:author xmlns:xqdoc=\"http://www.xqdoc.org/1.0\">www.w3c.org</xqdoc:author>" ], 
    "version" : null, 
    "encoding" : "utf-8", 
    "namespaces" : [ {
      "uri" : "http://www.w3.org/2005/xpath-functions/math", 
      "prefix" : "math"
    } ], 
  "variables": [],
  "functions": [
   {
      "isDocumented" : true, 
      "arity" : 1, 
      "name" : "acos", 
      "qname" : "math:acos", 
      "signature" : "($arg as xs:double?) as xs:double? external", 
      "description" : " <div xmlns:xqdoc=\"http://www.xqdoc.org/1.0\"><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\">Returns the arc cosine of the argument, the result being in the range zero to\n                +<var>π</var> radians.</p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\"><example role=\"signature\"><proto name=\"acos\" return-type=\"xs:double?\" isOp=\"no\" prefix=\"math\" returnEmptyOk=\"no\" returnSeq=\"no\" returnVaries=\"no\" isSchema=\"no\" isDatatype=\"no\" isSpecial=\"no\"><arg name=\"arg\" type=\"xs:double?\"/></proto></example></p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\">This function is <termref def=\"dt-deterministic\">deterministic</termref>, <termref def=\"dt-context-independent\">context-independent</termref>,  and <termref def=\"dt-focus-independent\">focus-independent</termref>. </p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\">If <code>$arg</code> is the empty sequence, the function returns the empty sequence.</p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\" diff=\"chg\" at=\"G\">Otherwise the result is the arc cosine of <code>$</code><var>θ</var>,\n             treated as an angle in radians, as defined in the <bibref ref=\"ieee754-2008\"/>\n             specification of the <code>acos</code> function applied to 64-bit binary floating point\n             values.</p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\">The treatment of the <code>invalidOperation</code> exception is defined in <specref ref=\"op.numeric\"/>. </p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\">If <code>$arg</code> is <code>NaN</code>, or if its absolute value is greater than one,\n             then the result is <code>NaN</code>.</p><p xmlns:e=\"http://www.w3.org/1999/XSL/Spec/ElementSyntax\">In other cases the result is an <code>xs:double</code> value representing an angle\n                <var>θ</var> in radians in the range <code>0 &lt;= $</code><var>θ</var><code> &lt;=\n                +</code><var>π</var>. </p></div>\n", 
      "summary" : "<p>  Returns the arc cosine of the argument, the result being in the range zero to\n                + π  radians.</p>", 
      "annotation_str" : "", 
      "annotations" : [  ], 
      "updating" : false, 
      "parameters" : [ {
        "name" : "arg", 
        "type" : "xs:double", 
        "occurrence" : "?", 
        "description" : ""
      } ], 
      "returns" : {
        "type" : "xs:double?", 
        "description" : ""
      }, 
      "errors" : [  ]
    },
   

Print AST as XML

$ xqlint ast <path>

<XQuery>
  ....
  <EOF>
   </EOF>
</XQuery>

Syntax Highlighting

$ xqlint highlight <path>

The output is for terminal display

Code

The following functions are exported:

  • XQLint = function (source, opts)
  • XQueryLexer
  • createStaticContext(processor)
  • CodeFormatter(ast, newLinesEnabled, DEBUG)

Development

If you'd like to hack on xqlint itself:

git clone https://github.com/Quodatum/xqlint
cd xqlint
npm install
sudo npm install grunt@1.5.3 -g
grunt

Run tests

grunt vows

// just one test, hardcoded in `grunt.js`
grunt vows:test

Generate parsers

npm run-script rex parsers

Command generates:

  • lib/lexers/XQueryTokenizer.ebnf -> XQueryTokenizer.js
  • lib/parsers/XQueryParser.ebnf -> XQueryParser.js

publish to npm

npm pack
npm publish