lezer-fhirpath

A Lezer parser for the FHIRPath expression language.

Overview

lezer-fhirpath provides a complete grammar-based parser for FHIRPath expressions, built using the Lezer parser system. FHIRPath is a path-based navigation and extraction language used with FHIR (Fast Healthcare Interoperability Resources) data.

This parser is designed for integration into code editors, development tools, and any application that needs to parse and understand FHIRPath syntax.

Rationale

While an official ANTLR grammar exists, this Lezer implementation offers specific advantages for editor integration:

• Incremental Parsing: Lezer reparses only changed portions of text, providing real-time feedback during editing
• Built-in Error Recovery: Continues parsing after syntax errors, essential for incomplete code during typing
• Native CodeMirror 6 Support: Direct integration without adaptation layers
• Smaller Bundle Size: More suitable for web-based applications than ANTLR-generated parsers
• Unified Highlighting: Syntax highlighting rules are part of the grammar definition itself

Features

• Complete FHIRPath Grammar: Supports all FHIRPath expression types including literals, operators, functions, path navigation, and type operations
• Syntax Highlighting: Built-in semantic highlighting for keywords, operators, functions, and literals
• Incremental Parsing: Leverages Lezer's efficient incremental parsing for real-time editor integration
• Type Definitions: Full TypeScript support with included type definitions
• Comprehensive Testing: Extensive test suite covering various FHIRPath expressions

Installation

npm install lezer-fhirpath

Usage

import { parser } from 'lezer-fhirpath';

// Parse a FHIRPath expression
const tree = parser.parse('Patient.name.given.first()');

// Walk the syntax tree
tree.iterate({
  enter(node) {
    console.log(node.type.name, node.from, node.to);
  }
});

With CodeMirror

import { parser } from 'lezer-fhirpath';
import { LRLanguage, LanguageSupport } from '@codemirror/language';
import { styleTags, tags as t } from '@lezer/highlight';

// Create a language definition
const fhirpathLanguage = LRLanguage.define({
  parser: parser.configure({
    props: [
      styleTags({
        // Highlighting rules are already configured in the parser
      })
    ]
  })
});

// Create language support
export const fhirpath = () => {
  return new LanguageSupport(fhirpathLanguage);
};

Supported FHIRPath Features

Literals

• Strings: 'hello', "world"
• Numbers: 42, 3.14
• Booleans: true, false
• Null: {}
• Dates and Times: @2023-01-01, @T14:30:00, @2023-01-01T14:30:00Z

Operators

• Arithmetic: +, -, *, /, div, mod
• Comparison: =, !=, <, >, <=, >=
• Logical: and, or, xor, implies
• String: & (concatenation)
• Collections: | (union), in, contains

Path Navigation

• Dot notation: Patient.name.given
• Indexers: name[0], telecom[use='home']

Functions

• Collection functions: first(), last(), tail(), skip(), take(), count(), etc.
• String functions: matches(), replace(), split(), etc.
• Type functions: is(), as(), ofType()
• Math functions: abs(), ceiling(), floor(), round(), etc.

Special Variables

• $this - Current context
• $index - Current index in iteration
• $total - Total items in collection

External Constants

• %context - External constant references

Grammar Structure

The parser implements the complete FHIRPath grammar with proper operator precedence:

1. Primary expressions: Literals, identifiers, function calls
2. Postfix operators: Invocations (.), indexers ([])
3. Unary operators: +, -, not
4. Multiplicative: *, /, div, mod
5. Additive: +, -, &
6. Type operators: is, as
7. Comparison: <, >, <=, >=
8. Equality: =, !=, ~, !~
9. Membership: in, contains
10. Logical: and, or, xor, implies

Development

Building

npm install
npm run build

Testing

npm test

Project Structure

lezer-fhirpath/
├── src/
│   ├── fhirpath.grammar    # Grammar definition
│   ├── index.js           # Parser export
│   └── tokens.js          # Token helpers
├── test/
│   └── fhirpath.txt       # Test cases
├── dist/                  # Built files
└── package.json

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with Lezer, the incremental parser system by Marijn Haverbeke.

Developed by Health Samurai.