spark - GitLite

KO | EN

gitlite — search

#hacktoberfest #android #open-source #cross-platform #cpp #reactjs #macos #awesome-list #linux #terminal

spark

(★ 204)

Tooling for building DSLs in Elixir

File Explorer

ZIP Download

- - elixir.yml
- dependabot.yml
- options.exs
- config.exs
- - build-extensions-with-builders.md
  - setup-autocomplete.md
  - split-up-large-dsls.md
  - test-spark-verifiers.md
  - upgrade-to-2.0.md
  - use-source-annotations.md
  - writing-extensions.md
- - get-started-with-spark.md
- - helpers.ex
- - cheat_sheet.ex
  - code_helpers.ex
  - docs.ex
  - dsl.ex
  - formatter.ex
  - igniter.ex
  - info_generator.ex
  - options_helpers.ex
  - regex.ex
  - test.ex
  - warning.ex
- spark.ex
- MIT.txt
- logo.svg
- - plugin_test.exs
- - and_type_test.exs
  - impl_validator_test.exs
  - mixed_list_test.exs
  - validator_test.exs
- - collector_fixture.ex
  - example_contacter.ex
  - example_options.ex
- add_extension_test.exs
- cheat_sheet_test.exs
- code_helpers_test.exs
- cross_extension_recursive_patch_test.exs
- docs_test.exs
- dsl_test.exs
- dsl_validation_test.exs
- formatter_test.exs
- igniter_test.exs
- info_generator_test.exs
- persister_sort_test.exs
- recursive_test.exs
- spark_test.exs
- test_helper.exs
- top_level_test.exs
- transformer_test.exs
.check.exs
.credo.exs
.formatter.exs
.gitignore
.tool-versions
.tool-versions.license
CHANGELOG.md
mix.exs
mix.lock
mix.lock.license
README.md
usage-rules.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`spark`

View Details ▼

The Laravel Spark tool.

spark register {{token}}

Register your API token:

spark token

Display the currently registered API token:

spark new {{project_name}}

Create a new Spark project:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<!--
SPDX-FileCopyrightText: 2020 Zach Daniel
SPDX-FileCopyrightText: 2022 spark contributors <https://github.com/ash-project/spark/graphs.contributors>

SPDX-License-Identifier: MIT
-->

<p align="center">
  <img src="logos/logo.svg" alt="Spark Logo" width="150" height="200" />
</p>

[![Spark CI](https://github.com/ash-project/spark/actions/workflows/elixir.yml/badge.svg)](https://github.com/ash-project/spark/actions/workflows/elixir.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Hex version badge](https://img.shields.io/hexpm/v/spark.svg)](https://hex.pm/packages/spark)
[![Hexdocs badge](https://img.shields.io/badge/docs-hexdocs-purple)](https://hexdocs.pm/spark)
[![REUSE status](https://api.reuse.software/badge/github.com/ash-project/spark)](https://api.reuse.software/info/github.com/ash-project/spark)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ash-project/spark)

**Build powerful, extensible DSLs with exceptional developer experience**

Spark is a framework for creating declarative domain-specific languages in
Elixir. It transforms simple struct definitions into rich, extensible DSLs that
come with autocomplete, documentation generation, and sophisticated tooling
built right in.

## Quick Example

Here's how you can build a data validator DSL with Spark:

```elixir
defmodule MyApp.PersonValidator do
  use MyLibrary.Validator

fields do
    required [:name]
    field :name, :string

field :email, :string do
      check &String.contains?(&1, "@")
      transform &String.trim/1
    end
  end
end

MyApp.PersonValidator.validate(%{name: "Zach", email: " foo@example.com "})
{:ok, %{name: "Zach", email: "foo@example.com"}}
```

The DSL definition itself is clean and declarative:

```elixir
@field %Spark.Dsl.Entity{
  name: :field,
  args: [:name, :type],
  target: Field,
  describe: "A field that is accepted by the validator",
  schema: [
    name: [type: :atom, required: true, doc: "The name of the field"],
    type: [type: {:one_of, [:integer, :string]}, required: true, doc: "The type of the field"],
    check: [type: {:fun, 1}, doc: "A function to validate the value"],
    transform: [type: {:fun, 1}, doc: "A function to transform the value"]
  ]
}

@fields %Spark.Dsl.Section{
  name: :fields,
  entities: [@field],
  describe: "Configure the fields that are supported and required"
}

use Spark.Dsl.Extension, sections: [@fields]
```

## What You Get Out of the Box

* 🔧 **Extensible Architecture** - Anyone can write extensions for your DSL,
  making it infinitely customizable
* 🧠 **Smart Autocomplete** - Built-in ElixirSense integration provides
  intelligent code completion and inline documentation in your editor
* 📚 **Auto Documentation** - Generate comprehensive documentation for your DSL
  automatically, including all options and usage examples
* ⚡ **Developer Tools** - Mix tasks for formatting, code generation, and
  maintaining `locals_without_parens` automatically
* 🔄 **Compile-time Processing** - Use transformers to modify DSL structures
  during compilation and verifiers to validate correctness
* 🎯 **Type Safety** - Rich schema validation ensures DSL usage is correct at
  compile time with helpful error messages
* 🔍 **Introspection** - Built-in tools to inspect and query DSL definitions
  programmatically at runtime

## Installation

Add `spark` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:spark, "~> 2.3"}
  ]
end
```

## Getting Started

The best way to get started is with our comprehensive tutorial that walks you
through building a complete DSL from scratch:

📖 **[Get Started with Spark](documentation/tutorials/get-started-with-spark.md)** -
Build a data validator DSL step by step

### Quick Start Checklist

1. **Define your DSL structure** using `Spark.Dsl.Section` and `Spark.Dsl.Entity`
2. **Create your extension** with `use Spark.Dsl.Extension`
3. **Build your DSL module** that users will import
4. **Add transformers and verifiers** for advanced behavior
5. **Generate helper functions** with `Spark.InfoGenerator`

Each step is covered in detail in the tutorial above.

## Documentation

### 📚 Guides & Tutorials
- **[Get Started with Spark](documentation/tutorials/get-started-with-spark.md)** -
  Complete tutorial building a validator DSL
- **[Writing Extensions](documentation/how_to/writing-extensions.md)** -
  Deep dive into extension development
- **[Setup Autocomplete](documentation/how_to/setup-autocomplete.md)** -
  Configure editor integration
- **[Split Up Large DSLs](documentation/how_to/split-up-large-dsls.md)** -
  Organize complex DSL definitions
- **[Use Source Annotations](documentation/how_to/use-source-annotations.md)** -
  Leverage location tracking for better errors

### 🔧 API Reference
- **[HexDocs](https://hexdocs.pm/spark)** - Complete API documentation
- **Core Modules**: `Spark.Dsl.Extension`, `Spark.Dsl.Entity`,
  `Spark.Dsl.Section`
- **Advanced Features**: `Spark.Dsl.Transformer`, `Spark.Dsl.Verifier`,
  `Spark.InfoGenerator`

## Production Ready

Spark is battle-tested and powers all DSLs in the [Ash Framework](https://ash-hq.org),
handling complex real-world applications with thousands of DSL definitions.
Whether you're building configuration DSLs, workflow orchestrators, or
domain-specific languages for your business logic, Spark provides the foundation
for production-grade solutions.

## Contributing

We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md)
and feel free to open issues or submit pull requests.

## Links

- **[GitHub](https://github.com/ash-project/spark)** - Source code and issue
  tracking
- **[Hex.pm](https://hex.pm/packages/spark)** - Package repository
- **[HexDocs](https://hexdocs.pm/spark)** - API documentation
- **[Ash Framework](https://ash-hq.org)** - See Spark in action
- **[Discord](https://discord.gg/HTHRaaVPUc)** - Community chat
- **[Forum](https://elixirforum.com/c/elixir-framework-forums/ash-framework-forum)** -
  Discussion forum

## License

MIT - see [`LICENSES/MIT.txt`](LICENSES/MIT.txt) for details.