catala/README.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

231 lines
9.2 KiB
Markdown
Raw Normal View History

2021-11-29 14:25:45 +03:00
<div align="center">
<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/logo.png" alt="Catala logo" width="120"/>
<h3 align="center">
<big>Catala</big>
2021-11-29 14:25:45 +03:00
</h3>
<p align="center">
<a href="https://catala-lang.org/ocaml_docs/"><strong>Explore the docs »</strong></a>
<br/>
<a href="https://catala-lang.org/en/examples/tutorial">View Tutorial</a>
<a href="https://github.com/CatalaLang/catala/issues">Report Bug</a>
<a href="https://github.com/CatalaLang/catala/blob/master/CONTRIBUTING.md">Contribute</a>
<a href="https://zulip.catala-lang.org/">Join Zulip Chat</a>
</p>
2019-09-04 11:32:33 +03:00
2022-01-27 19:16:58 +03:00
![CI][ci-link] [![Opam][opam-link]](https://opam.ocaml.org/packages/catala/) [![Licence][licence-link]](https://www.apache.org/licenses/LICENSE-2.0) ![Tag][tag-link] ![LoC][loc-link] ![Language][language-link] [![Issues][issues-link]](https://github.com/CatalaLang/catala/issues) [![Contributors][contributors-link]](https://github.com/CatalaLang/catala/graphs/contributors) [![Activity][activity-link]](https://github.com/CatalaLang/catala/pulse)
2020-04-17 17:22:20 +03:00
Catala is a domain-specific language for deriving
2020-12-14 12:59:15 +03:00
faithful-by-construction algorithms from legislative texts. To learn quickly
about the language and its features, you can jump right to the official
2020-12-14 12:59:15 +03:00
[Catala tutorial](https://catala-lang.org/en/examples/tutorial).
2021-03-19 20:34:38 +03:00
You can join the Catala community on [Zulip][chat-link]!
2022-01-11 14:51:34 +03:00
2021-11-29 14:25:45 +03:00
</div>
<br>
<details>
<summary>Table of Contents</summary>
<!-- vim-markdown-toc GitLab -->
2022-02-22 21:07:54 +03:00
* [Concepts](#concepts)
* [Getting started](#getting-started)
* [Building and installation](#building-and-installation)
* [Usage](#usage)
* [Catala](#catala)
* [Clerk](#clerk)
* [Documentation](#documentation)
* [Syntax cheat sheet](#syntax-cheat-sheet)
* [Formal semantics](#formal-semantics)
* [Compiler documentation](#compiler-documentation)
* [Examples](#examples)
* [API](#api)
* [Contributing](#contributing)
* [Test suite](#test-suite)
* [License](#license)
* [Limitations and disclaimer](#limitations-and-disclaimer)
* [Pierre Catala](#pierre-catala)
2021-11-29 14:25:45 +03:00
<!-- vim-markdown-toc -->
</details>
2021-01-05 21:05:29 +03:00
2020-04-17 17:22:20 +03:00
## Concepts
2020-12-14 12:59:15 +03:00
Catala is a programming language adapted for socio-fiscal legislative literate
programming. By annotating each line of the legislative text with its meaning
in terms of code, one can derive an implementation of complex socio-fiscal
mechanisms that enjoys a high level of assurance regarding the code-law
2020-12-14 12:59:15 +03:00
faithfulness.
2020-04-17 17:22:20 +03:00
Concretely, you have to first gather all the laws, executive orders, previous
cases, etc. that contain information about the socio-fiscal mechanism that
you want to implement. Then, you can proceed to annotate the text article by
2020-12-14 12:59:15 +03:00
article, in your favorite text editor :
2020-04-17 17:22:20 +03:00
2021-11-29 14:25:45 +03:00
<div align="center">
<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/ScreenShotVSCode.png" alt="Screenshot" height="350"/>
</div>
2020-04-17 17:22:20 +03:00
Once your code is complete and tested, you can use the Catala
compiler to produce a lawyer-readable PDF version of your
implementation. The Catala language has been specially designed
in collaboration with law professionals to ensure that the code
can be reviewed and certified correct by the domain experts, which
are in this case lawyers and not programmers.
2021-11-29 14:25:45 +03:00
<div align="center">
<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/CatalaScreenShot.png" alt="Screenshot" height="350"/>
</div>
2020-04-17 17:22:20 +03:00
The Catala language is special because its logical structure mimics
the logical structure of the law. Indeed, the core concept of
"definition-under-conditions" that builds on default logic has been formalized
2021-03-19 20:34:38 +03:00
by Professor Sarah Lawsky in her article
[A Logic for Statutes](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3088206).
The Catala language is the only programming language to our knowledge that
embeds default logic as a first-class feature, which is why it is the only
2020-12-14 12:59:15 +03:00
language perfectly adapted to literate legislative programming.
2020-04-17 17:22:20 +03:00
2022-02-14 01:40:23 +03:00
## Getting started
To get started, the best place is the [tutorial](https://catala-lang.org/en/examples/tutorial)
of the language. A [French version](https://catala-lang.org/fr/examples/tutoriel)
is also available but might be out of sync with the latest language features.
2023-03-09 18:07:36 +03:00
> **Note:** bleeding-edge version
>
> If you are interested in the latest development version, pre-built artifacts
> including binaries and API documentation can be found at
> https://catalalang.github.io/catala
2020-12-21 18:02:00 +03:00
## Building and installation
2020-04-17 17:22:20 +03:00
2021-03-19 20:38:57 +03:00
Catala is available as an [opam package](https://opam.ocaml.org/packages/catala/)!
If opam is installed on your machine, simply execute:
opam install catala
2021-04-13 19:35:04 +03:00
To get the cutting-edge, latest version of Catala, you
can also do
opam pin add catala --dev-repo
2021-03-19 20:38:57 +03:00
However, if you wish to get the latest developments of the compiler, you probably
want to compile it from the sources of this repository or use nix. For that, see
2021-03-19 20:38:57 +03:00
[the dedicated readme](INSTALL.md).
2020-04-17 17:22:20 +03:00
2020-12-21 18:02:00 +03:00
## Usage
2022-01-11 14:51:34 +03:00
### Catala
Use `catala --help` if you have installed it to get more information about the command line
2022-02-14 01:40:23 +03:00
options available. The man page is also [available online](https://catala-lang.org/en/doc/catala).
To get the development version of the help, run `make help_catala`
2022-01-11 14:51:34 +03:00
after `make build`. The `catala` binary corresponds to the Catala compiler.
2020-12-21 18:02:00 +03:00
The top-level `Makefile` contains a lot of useful targets to run. To display
them, use
make help
2022-08-09 16:00:13 +03:00
### Plugin backends
While the compiler has some builtin backends for Catala (Python, Ocaml, etc.),
it is also possible to add a custom backend to the Catala compiler without
having to modify its source code. This plugin solution relies on dynamic
linking: see [the dedicated README](compiler/plugins/README.md).
2022-01-11 14:51:34 +03:00
### Clerk
Use `clerk --help` if you have installed it to get more information about the command line
options available. To get the development version of the help, run `make help_clerk`
after `make build`. The `clerk` binary corresponds to the Catala build system,
responsible for testing among other things.
To get more information about Clerk, see [the dedicated readme](https://github.com/CatalaLang/catala/tree/master/build_system/README.md)
2022-02-14 01:40:23 +03:00
## Documentation
### Syntax cheat sheet
A complete and handy reference of the Catala syntax can be found in the [cheat
sheet](https://catalalang.github.io/catala/syntax.pdf) (for French and English
versions of the syntax).
2022-02-14 01:40:23 +03:00
### Formal semantics
To audit the formal proof of the partial certification of the Catala compiler,
see [the dedicated readme](doc/formalization/README.md).
### Compiler documentation
The documentation is accessible online, both for the [latest release](https://catala-lang.org/ocaml_docs/) and [bleeding-edge version](https://catalalang.github.io/catala/api-doc/).
It is otherwise generated from the compiler source code using
`dune` and `odoc`. Run
2022-02-14 01:40:23 +03:00
make doc
to generate the documentation, then open the `doc/odoc.html` file in any browser.
2020-12-14 12:59:15 +03:00
## Examples
2020-04-17 17:22:20 +03:00
2021-06-25 11:50:49 +03:00
To explore the different programs written in Catala, see
[the dedicated readme](examples/README.md).
## API
To know how to use the code generated by the Catala compiler in your favorite
programming language, head to the [readme of the French law library](french_law/README.md). The corresponding pre-built examples are also [available](https://catalalang.github.io/catala/).
2020-04-17 17:22:20 +03:00
2020-12-14 12:59:15 +03:00
## Contributing
2020-04-17 17:22:20 +03:00
2021-06-25 11:50:49 +03:00
To know how you can contribute to the project, see
[the dedicated readme](CONTRIBUTING.md).
2020-04-27 11:04:13 +03:00
2020-12-14 12:59:15 +03:00
## Test suite
2020-04-27 11:04:13 +03:00
2021-06-25 11:50:49 +03:00
To know how to run or improve the Catala reference test suite,
see [the dedicated readme](tests/README.md).
2020-04-27 11:04:13 +03:00
2020-12-14 12:59:15 +03:00
## License
2020-08-07 18:37:28 +03:00
2021-06-25 11:50:49 +03:00
The compiler and all the code contained in this repository is released under
the [Apache license (version 2)](LICENSE.txt) unless another license is explicited
for a sub-directory.
2020-08-07 18:37:28 +03:00
2020-12-14 12:59:15 +03:00
## Limitations and disclaimer
2020-04-17 14:02:15 +03:00
2020-12-14 12:59:15 +03:00
Catala is a research project from Inria, the French National
Research Institute for Computer Science. The compiler is yet
unstable and lacks some of its features.
2020-04-16 19:58:05 +03:00
## Pierre Catala
The language is named after Pierre Catala, a professor of law who
pionneered the French legaltech by creating a computer database of law cases,
Juris-Data. The research group that he led in the late 1960s, the
Centre détudes et de traitement de linformation juridique (CETIJ),
has also influenced the creation by state conselor Lucien Mehl of the
Centre de recherches et développement en informatique juridique (CENIJ),
which eventually transformed into the entity managing the LegiFrance website,
2020-04-17 14:02:15 +03:00
acting as the public service of legislative documentation.
2021-03-19 20:34:38 +03:00
[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg?style=social&logo=zulip&color=5c75a2
[chat-link]: https://zulip.catala-lang.org/
2022-02-22 21:07:54 +03:00
[ci-link]: https://github.com/catalalang/catala/actions/workflows/run-builds.yml/badge.svg
2021-03-19 20:34:38 +03:00
[licence-link]: https://img.shields.io/github/license/catalalang/catala
[tag-link]: https://img.shields.io/github/v/tag/catalalang/catala
[loc-link]: https://img.shields.io/tokei/lines/github/catalalang/catala
[issues-link]: https://img.shields.io/github/issues/catalalang/catala
[opam-link]: https://img.shields.io/badge/Package-opam-orange?logo=OCaml&link=https://opam.ocaml.org/packages/catala/
[language-link]: https://img.shields.io/github/languages/top/catalalang/catala
[contributors-link]: https://img.shields.io/github/contributors/catalalang/catala
[activity-link]: https://img.shields.io/github/commit-activity/m/catalalang/catala