DOCSEARCHbyAlgolia
Submit Docs

Civet Documentation

repository·main·Indexed 24 days ago

https://github.com/danielxmoore/civet

Civet is a modern superset of TypeScript that provides CoffeeScript-style syntax and brings proposed or experimental ECMAScript features—such as pattern matching, pipe operators, and enhanced JSX—into a productive development workflow. The documentation covers integration with ESLint, Gulp, Jest, React Native/Metro, Astro, Next.js, and SolidStart, as well as browser-based execution via script tags.

Tokens
39.7K
Snippets
136
Records
194
Agent score
83%

What's inside Civet

  1. Overview of Civet LSP packages and editor support

    main

    Civet LSP provides language server and editor integrations. The core components include:

    Core Packages

    • @danielx/civet-language-server: A standalone, editor-agnostic Language Server.
    • @danielx/civet-monaco: Helpers for Monaco language registration, tokens, and LSP providers.
    • @danielx/civet-vscode: VS Code extension.

    Supported Editors

    • VS Code: Install via the marketplace.
    • Monaco: Integrate using @danielx/civet-monaco with @danielx/civet-language-server/browser.
    • Sublime Text: Use the package located in sublime/.
    • Zed: Use the Zed editor extension (Rust/WASM).
    • Neovim / Other LSP clients: Run civet-lsp --stdio.

  2. What is Civet?

    main
    Civet is a programming language that compiles to TypeScript or JavaScript. It is designed to be highly compatible with existing JS/TS codebases (starting with 99% compatibility) while providing concise and powerful syntax through features like pattern matching, pipelines, and custom operators. Because it compiles to TypeScript/JavaScript, you can use existing tooling such as VSCode for type checking, hints, and completion.

  3. Features of the Civet Zed Extension

    main

    The Civet Zed extension provides support for both Civet and Hera languages with the following capabilities:

    Syntax Highlighting

    Uses tree-sitter grammars located in:

    • ../tree-sitter/ for Civet
    • ../tree-sitter-hera/ for .hera files

    LSP Support

    Powered by civet-lsp for both .civet and .hera files, providing:

    • Diagnostics
    • Completions
    • Hover information
    • Go-to-definition
    • Grammar-level navigation for .hera rules

  4. Civet Build Tool Integrations

    main

    Civet can be integrated into various build pipelines using several methods:

    • unplugin: Integrates Civet into Vite, esbuild, Astro, Farm, Rolldown, Rollup, and Webpack (includes .d.ts generation).
    • ESM/CJS loader: Use the provided loader for import/require to support .civet files.
    • Babel plugin: Use babel-plugin-civet (includes React Native / Metro support).
    • Jest plugin: For testing environments.
    • Gulp plugin: For Gulp-based workflows.
    • Bun plugin: For Bun runtimes.
    • Meteor plugin: For Meteor applications.
    • Civetman: Automatically compiles .civet files for arbitrary build chains.
    • <script> tag: Support for direct browser usage.

  5. Civet Tooling and AI Integration

    main

    Civet supports several advanced tooling options:

    • mcp-language-server: Exposes civet-lsp to AI agents via the Model Context Protocol, enabling diagnostics, hover, go-to-definition, references, and edits.
    • YavaScript: A standalone script runner that supports Civet without requiring Node.js.
    • eslint-plugin-civet: Provides linting support for Civet code.

  6. Syntax for Single-Argument Arrow Functions

    main

    In Civet, arrow functions with a single argument must be wrapped in parentheses. If you omit them, the argument is treated as an implicit function call.

    Conversely, zero-parameter functions do not require () to indicate arguments, allowing for a cleaner syntax like => ... or createEffect => ....

  7. Use Dedented Strings and Templates

    main

    Civet supports dedented strings and templates (based on the TC39 String Dedent proposal), allowing you to write multi-line strings without including the leading indentation in the resulting string.

    text = """
  This text is a string that doesn't include
  the leading whitespace.
"""

text = ```
  Also works for
  ${templates}!

  8. Use Pipelines and Fat Pipes

    main

    Civet implements the Pipe Operator proposal. You can use standard pipes to pass data through functions, or 'fat pipes' (||>) to manipulate the same object repeatedly.

    // Standard pipe
data
  |> Object.keys
  |> console.log

// Fat pipe (manipulates the same object)
document.createElement('div')
||> .className = 'civet'
||> .appendChild document.createTextNode 'Civet'

// Pipe with shorthand functions
a |> & + 1 |> bar

  9. Syntax for Labels and Decorators

    main

    Civet uses specific syntax for labels and decorators to support its unique features:

    • Labels: Written as :label (instead of the JS label:).
    • Decorators: Written as @@DecoratorName. This distinguishes them from the @ shorthand used for this, static, and constructor.
    • Method Decorators: Decorators cannot be on the same line as a method. They must be on the line above to allow for implicit function call syntax within the method.
    // Labels
:label while (true) {
  break label
}

// Decorators
@@Object.seal
class Civet
  @name = "Civet"

// Method Decorators
class Civet
  @@description translate "Caffeine time!"
  drink()
    @fetch @coffeeCup

  10. Use symbols with the :symbol syntax

    main

    The :symbol syntax represents either a well-known symbol (static member of Symbol) or a symbol in the global registry via Symbol.for.

    If a symbol name is not a valid identifier, wrap it in quotes: :"magic-symbol".

    You can also define a specific list of well-known symbols using a compiler directive: "civet symbols=magic".

    magicSymbol := :magic

// For invalid identifiers
magicSymbol := :"magic-symbol"

// Using compiler directive
"civet symbols=magic"
magicSymbol := :magic

  12. Use dynamic imports in Civet

    main

    Civet supports dynamic imports with two main patterns:

    1. Unparenthesized Dynamic Import: If import is not at the start of a statement, you do not need parentheses.
    2. Dynamic Import Declarations: If an import declaration is used inside a function (not at the top level), it is automatically transformed into a dynamic import. Note that this makes the containing function async because the import is awaited.
    3. Import Expressions: You can use import as an expression as a shorthand for awaiting and destructuring a dynamic import.
    // Unparenthesized
{x} = await import url

// Inside a function (becomes async)
function load
  * as utils from ./utils
  { version: nodeVer, execPath as nodePath } from process
  fs, {readFile} from fs
  return {utils, nodeVer, nodePath, fs, readFile}

// As expressions
urlPath := import { fileURLToPath, pathToFileURL } from url
url := import * from url
Foo := import default from Foo