https://github.com/sellout/dada

A total recursion scheme library for Dhall
https://github.com/sellout/dada

dhall recursion-schemes

Last synced: 18 days ago
JSON representation

A total recursion scheme library for Dhall

• Host: GitHub
• URL: https://github.com/sellout/dada
• Owner: sellout
• License: agpl-3.0
• Created: 2018-03-07T22:32:48.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2024-08-21T18:27:16.000Z (3 months ago)
• Last Synced: 2024-10-13T10:34:05.001Z (about 1 month ago)
• Topics: dhall, recursion-schemes
• Language: Nix
• Size: 172 KB
• Stars: 65
• Watchers: 8
• Forks: 7
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-dhall - dada - Recursion schemes. (Libraries)

README

        
# dada

[![built with garnix](https://img.shields.io/endpoint?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fsellout%2Fdada)](https://garnix.io)

[![Packaging status](https://repology.org/badge/tiny-repos/haskell:dada.svg)](https://repology.org/project/haskell:dada/versions)

[![latest packaged version(s)](https://repology.org/badge/latest-versions/haskell:dada.svg)](https://repology.org/project/haskell:dada/versions)

A total recursion scheme library for Dhall

Recursion schemes allow you to separate recursion from your business logic – making your own operations simpler, more modular, and less error-prone. This library also provides tools for combining your operations in ways that reduce the number of passes over your data and is designed to encourage total (that is, successfully terminating) functions.

## documentation

API docs are on [GitHub Pages](https://sellout.github.io/dada).

## development environment

We recommend the following steps to make working in this repository as easy as possible.

### `direnv allow`

This command ensures that any work you do within this repository happens within a consistent reproducible environment. That environment provides various debugging tools, etc. When you leave this directory, you will leave that environment behind, so it doesn’t impact anything else on your system.

### `git config --local include.path ../.cache/git/config`

This will apply our repository-specific Git configuration to `git` commands run against this repository. It’s lightweight (you should definitely look at it before applying this command) – it does things like telling `git blame` to ignore formatting-only commits.

## building & development

Especially if you are unfamiliar with the Dhall or Haskell ecosystems, there is a Nix build (both with and without a flake). If you are unfamiliar with Nix, [Nix adjacent](...) can help you get things working in the shortest time and least effort possible.

### if you have `nix` installed

`nix build` will build and test the project fully.

`nix develop` will put you into an environment where the traditional build tooling works. If you also have `direnv` installed, then you should automatically be in that environment when you're in a directory in this project.

### traditional build

The Haskell part of this project is built with [Cabal](https://cabal.readthedocs.io/en/stable/index.html). Individual packages will work with older versions, but ./cabal.package requires Cabal 3.6+.

## versioning

In the absolute, almost every change is a breaking change. This section describes how we mitigate that to offer minor updates and revisions.

Here are some common Haskell changes that can have unintended effects:

- adding instances can conflict with downstream orphans,

- adding a module can conflict with a module from another package,

- adding a definition to an existing module can conflict if there are unqualified imports, and

- even small bugfixes can introduce breaking changes where downstream depended on the broken results.

To mitigate some of those issues for versioning, we assume the following usage:

- modules should be imported using `PackageImports`, so that adding modules is a _minor_ change;

- modules should be imported qualified, so that adding definitions is a _minor_ change;

- adding instances can't be mitigated in the same way, and it's not uncommon for downstream libraries to add orphans instances when they're omitted from upstream libraries. However, since these conflicts can only happen via direct dependencies, and represent an explicit downstream workaround, it’s reasonable to expect a quick downstream update to remove or conditionalize the workaround. So, this is considered a _minor major_ change;

- deprecation is considered a _revision_ change, however it will often be paired with _minor_ changes. `-Werror` can cause this to fail, but published libraries shouldn't be compiled with `-Werror`.

## comparisons

Other projects similar to this one, and how they differ.