CDL Language Server

A Language Server Protocol (LSP) implementation for the Crystal Description Language (CDL).

Part of the Gemmology Project.

Features

• Diagnostics: Real-time error detection and warnings
• Completion: Context-aware autocomplete for systems, point groups, forms, and modifications
• Hover: Documentation on hover for CDL elements
• Go to Definition: Navigate to symbol definitions
• Formatting: Automatic CDL formatting
• Code Actions: Quick fixes for common errors
• Document Symbols: Outline view of CDL documents
• Signature Help: Parameter hints for modifications

CDL v2.0 Support

• Amorphous completions: Autocomplete for subtypes (opalescent, glassy, waxy, resinous, cryptocrystalline) and shapes (massive, botryoidal, reniform, etc.)
• Aggregate completions: Autocomplete for arrangement types (parallel, random, radial, epitaxial, druse, cluster) and orientations (aligned, random, planar, spherical)
• New diagnostics: Validation of amorphous subtypes, amorphous shapes, arrangement types, and aggregate count limits
• Formatting: Normalizes spacing around > (nested growth) and ~ (aggregate) operators, and amorphous[sub]:{shapes} syntax
• Document symbols: Recognizes amorphous descriptions, nested growth operators, and aggregate specifications in the outline view
• Go to Definition: Navigates to source definitions for amorphous subtypes, shapes, and arrangement types

Installation

pip install cdl-lsp

Dependencies

The package requires:

• cdl-parser>=2.0.0 - CDL parsing library
• pygls>=1.0.0 - Python language server framework
• lsprotocol>=2023.0.0 - LSP type definitions

Usage

From Command Line

# Standard I/O mode (default)
cdl-lsp

# TCP mode
cdl-lsp --tcp --host 127.0.0.1 --port 2087

# With logging
cdl-lsp --log-file /tmp/cdl-lsp.log --log-level DEBUG

From Python

from cdl_lsp import create_server

server = create_server()
server.start_io()  # or server.start_tcp(host, port)

Editor Integration

VS Code

Install the CDL extension from the VS Code marketplace, or configure manually:

{
  "cdl.server.path": "cdl-lsp"
}

Neovim (nvim-lspconfig)

require('lspconfig').cdl_lsp.setup{
  cmd = {'cdl-lsp'},
  filetypes = {'cdl'},
}

Sublime Text (LSP)

Add to LSP settings:

{
  "clients": {
    "cdl": {
      "command": ["cdl-lsp"],
      "selector": "source.cdl"
    }
  }
}

CDL Syntax Overview

The Crystal Description Language describes crystal morphologies:

# Basic forms
cubic[m3m]:{111}                     # Octahedron
cubic[m3m]:{100}                     # Cube

# Combined forms
cubic[m3m]:{111}@1.0 + {100}@1.3     # Truncated octahedron

# Named forms
cubic[m3m]:octahedron                # Same as {111}

# Modifications
cubic[m3m]:{111}|elongate(c:1.5)     # Elongated
cubic[m3m]:{111}|twin(spinel)        # Twinned

# Different crystal systems
hexagonal[6/mmm]:{10-10}@1.0 + {0001}@0.5   # Hexagonal prism
trigonal[-3m]:{10-11}                       # Rhombohedron

# Amorphous materials (v2.0)
amorphous[opalescent]:{botryoidal} | phenomenon[play_of_color:intense]
amorphous[cryptocrystalline]:{massive, nodular}[colour:blue]

# Nested growth (v2.0)
trigonal[32]:({10-10}@1.0 + {10-11}@0.8) > ({10-10}@0.5 + {10-11}@0.4)

# Aggregates (v2.0)
trigonal[32]:{10-10}@1.0 + {10-11}@0.8 ~ cluster[12]
cubic[m3m]:{100} ~ cluster[5]

API Reference

Constants

from cdl_lsp.constants import (
    CRYSTAL_SYSTEMS,      # Set of crystal system names
    POINT_GROUPS,         # Dict mapping system to point groups
    ALL_POINT_GROUPS,     # Set of all 32 point groups
    TWIN_LAWS,            # Set of twin law names
    NAMED_FORMS,          # Dict mapping form names to Miller indices
    MODIFICATIONS,        # Set of modification names
)

Server

The LSP server handles all features internally. Use the server module to start the language server:

from cdl_lsp import create_server, SERVER_NAME, SERVER_VERSION

server = create_server()
print(f"Running {SERVER_NAME} v{SERVER_VERSION}")
server.start_io()  # or server.start_tcp(host, port)

Development

Setup

git clone https://github.com/gemmology-dev/cdl-lsp
cd cdl-lsp
pip install -e ".[dev]"

Testing

pytest tests/ -v

Linting

ruff check src/
mypy src/

License

MIT License - see LICENSE for details.

Links

• Documentation
• CDL Specification
• GitHub Repository
• Issue Tracker