mirror of
https://github.com/CatalaLang/catala.git
synced 2024-11-08 07:51:43 +03:00
Improved readmes
This commit is contained in:
Denis Merigoux
parent
1ddd46af55
commit
f282d9586b
@ -1,11 +1,18 @@
|
||||
# Contributing to Catala
|
||||
|
||||
The project is open to external contributions, in the spirit of open source. If you want to open a pull request, please follow the instructions below.
|
||||
The project is open to external contributions, in the spirit of open source.
|
||||
If you want to open a pull request, please follow the instructions below.
|
||||
|
||||
To ask a question to the Catala team, please open an issue on this repository. If you want to contribute to the project on a longer-term basis, or if you have specific competences as a socio-fiscal lawyer or a programming language specialist, please email the authors at denis.merigoux@inria.fr. The Catala team meets over visioconference once in a week.
|
||||
To ask a question to the Catala team, please open an issue on this repository.
|
||||
If you want to contribute to the project on a longer-term basis, or if you have
|
||||
specific competences as a socio-fiscal lawyer or a programming language specialist,
|
||||
please [contact the authors](mailto:contact@catala-lang.org).
|
||||
The Catala team meets over visioconference once every two weeks.
|
||||
|
||||
Please note that the copyright of this code is owned by Inria;
|
||||
by contributing, you disclaim all copyright interests in favor of Inria. Both the code for the compiler and the examples in this repository are distributed under the Apache2 license.
|
||||
by contributing, you disclaim all copyright interests in favor of Inria.
|
||||
Both the code for the compiler and the examples in this repository are
|
||||
distributed under the Apache2 license.
|
||||
|
||||
## Writing Catala examples
|
||||
|
||||
@ -99,3 +106,18 @@ Again, make sure to regularly check that your example is parsing correctly. The
|
||||
## Working on the compiler
|
||||
|
||||
The Catala compiler is a standard dune-managed OCaml project. You can look at the [online OCaml documentation](https://catala-lang.org/ocaml_docs/) for the different modules' interfaces.
|
||||
|
||||
## Internationalization
|
||||
|
||||
The Catala language should be adapted to any legislative text that follows a
|
||||
general-to-specifics statutes order. Therefore, there exists multiple versions
|
||||
of the Catala surface syntax, adapted to the language of the legislative text.
|
||||
|
||||
Currently, Catala supports English and French legislative text via the
|
||||
`--language=en` or `--language=fr` option.
|
||||
|
||||
Technically, support for new languages can be added via a new lexer. If you want
|
||||
to add a new language, you can start from
|
||||
[existing lexer examples](src/catala/catala_surface/lexer_fr.ml), tweak and open
|
||||
a pull request. If you don't feel familiar enough with OCaml to do so, please
|
||||
leave an issue on this repository.
|
||||
|
||||
62
INSTALL.md
62
INSTALL.md
@ -1,29 +1,26 @@
|
||||
# Installing the Catala compiler
|
||||
# Building and installing the Catala language
|
||||
|
||||
## Requirements
|
||||
|
||||
The Catala compiler is written using OCaml. To install OCaml on your machine and
|
||||
if you're running Linux ou MacOS, open a terminal and enter :
|
||||
The Catala compiler is written using OCaml. First, you have to install `opam`,
|
||||
OCaml's distribution and package manager. Follow the [instructions on the `opam`
|
||||
website](https://opam.ocaml.org/doc/Install.html).
|
||||
|
||||
./install_opam.sh
|
||||
|
||||
This will install `opam`, the OCaml dependency manager and the
|
||||
base OCaml compiler. If you're on Windows, the simplest solution
|
||||
would be to use Cygwin or the Windows Subsystem for Linux. Catala has been tested
|
||||
with OCaml version 4.09.1. You can switch to this version by typing :
|
||||
|
||||
opam switch create 4.09.1
|
||||
|
||||
or
|
||||
Next, you will need to use the correct version of OCaml. Catala has been tested
|
||||
with OCaml compiler versions that are at least 4.09.1. To switch to OCaml 4.09.1.,
|
||||
just use:
|
||||
|
||||
opam switch 4.09.1
|
||||
|
||||
if this version of OCaml is already installed. Next, install all the build
|
||||
dependencies with
|
||||
If you get a `No switch 4.09.1 is currently installed` error message, follow
|
||||
the hint and enter `opam switch create 4.09.1`.
|
||||
|
||||
Next, install all the OCaml packages that Catala depend on, as well as some
|
||||
git submodules, with
|
||||
|
||||
make install-dependencies
|
||||
|
||||
This should ensure everything is set up for developping on the Catala compiler !
|
||||
This should ensure everything is set up for developping on the Catala compiler!
|
||||
|
||||
Other features for generation of files and literate programming also require
|
||||
the following executables to be present
|
||||
@ -41,7 +38,7 @@ On ArchLinux :
|
||||
|
||||
sudo pacman -S python-virtualenv man2html rsync
|
||||
|
||||
## Installation
|
||||
## Build
|
||||
|
||||
The project is distributed as a Dune artifact. Use standard dune commands to build
|
||||
and install the library. Makefile aliases are here to help you: running
|
||||
@ -50,12 +47,27 @@ and install the library. Makefile aliases are here to help you: running
|
||||
|
||||
builds the compiler from its OCaml sources.
|
||||
|
||||
## Install
|
||||
|
||||
The installation of the Catala compiler is handled through `opam`. Since the
|
||||
Catala compiler is not yet published to the `opam` repository, you can install
|
||||
a local version from this Git repository by using
|
||||
|
||||
opam install ./
|
||||
|
||||
To uninstall, use
|
||||
|
||||
opam unpin catala
|
||||
|
||||
### Generating website assets
|
||||
|
||||
The Catala website features assets generated by the Catala compiler. They are
|
||||
needed to build the website. To produce them, simply run from this repository's
|
||||
root directory
|
||||
needed to build the website. To produce them, simply run
|
||||
|
||||
make website-assets
|
||||
|
||||
Then, use a helper script to copy them over to the `assets` directory of the
|
||||
Catala website.
|
||||
|
||||
./generate_website_assets.sh <path-to-catala-website>/assets
|
||||
|
||||
@ -63,15 +75,6 @@ You will need the `man2html` executable to generate the HTML versions of the man
|
||||
pages, as well as the `rsync` executable to transfer files (preferred to `cp`)
|
||||
because it also works with a remote server.
|
||||
|
||||
### Opam package
|
||||
|
||||
If you want to install the library as an opam
|
||||
package, use the following command at the root of the repository:
|
||||
|
||||
opam install ./
|
||||
|
||||
You can then use the compiler with the `catala` command.
|
||||
|
||||
## Usage
|
||||
|
||||
Use `catala --help` to get more information about the command line options available.
|
||||
@ -119,7 +122,8 @@ augmented with the Catala plugin, simply enter
|
||||
make pygments
|
||||
|
||||
This will execute the
|
||||
script `syntax_highlighting/fr/pygments/set_up_pygments.sh` and `syntax_highlighting/en/pygments/set_up_pygments.sh`.
|
||||
script `syntax_highlighting/fr/pygments/set_up_pygments.sh` and
|
||||
`syntax_highlighting/en/pygments/set_up_pygments.sh`.
|
||||
|
||||
The scripts set up a virtual environement in
|
||||
`syntax_highlighting/fr/pygments/pygments/env` or
|
||||
|
||||
109
README.md
109
README.md
@ -1,27 +1,30 @@
|
||||
|
||||
<center>
|
||||
<img src="https://github.com/CatalaLang/catala/raw/master/doc/logo.png" alt="Catala logo" width="100"/>
|
||||
<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/logo.png" alt="Catala logo" width="100"/>
|
||||
</center>
|
||||
|
||||
# Catala
|
||||
|
||||
Catala is a domain-specific language for deriving
|
||||
faithful-by-construction algorithms from legislative texts.
|
||||
faithful-by-construction algorithms from legislative texts. To learn quickly
|
||||
about the language and its features, you can jump right to the official
|
||||
[Catala tutorial](https://catala-lang.org/en/examples/tutorial).
|
||||
|
||||
## Concepts
|
||||
|
||||
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 faithfulness.
|
||||
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
|
||||
faithfulness.
|
||||
|
||||
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 article, in your favorite
|
||||
text editor :
|
||||
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
|
||||
article, in your favorite text editor :
|
||||
|
||||
<center>
|
||||
<img src="https://github.com/CatalaLang/catala/raw/master/doc/ScreenShotVSCode.png" alt="Screenshot" height="500"/>
|
||||
<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/ScreenShotVSCode.png" alt="Screenshot" height="500"/>
|
||||
</center>
|
||||
|
||||
Once your code is complete and tested, you can use the Catala
|
||||
@ -32,72 +35,58 @@ can be reviewed and certified correct by the domain experts, which
|
||||
are in this case lawyers and not programmers.
|
||||
|
||||
<center>
|
||||
<img src="https://github.com/CatalaLang/catala/raw/master/doc/CatalaScreenShot.png" alt="Screenshot" height="500"/>
|
||||
<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/CatalaScreenShot.png" alt="Screenshot" height="500"/>
|
||||
</center>
|
||||
|
||||
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 by Professor of Law 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 language
|
||||
perfectly adapted to literate legislative programming.
|
||||
|
||||
|
||||
## Catala motivating example : French "allocations familiales"
|
||||
|
||||
In the `example/allocations_familiales` folder, you will find the
|
||||
`allocations_familiales.catala` file which contains the
|
||||
algorithm computing French family benefits. The algorithm consists of annotations to the legislative
|
||||
texts that define the family benetifs, using the literate programming paradigm. The Catala
|
||||
compiler can extract from the `.catala` file a lawyer-readable version of the annotated text.
|
||||
|
||||
Currently, this lawyer-readable version comes in the form of a LaTeX document.
|
||||
You will need to have a standard LaTeX distribution installed as well as the
|
||||
`latexmk` build tool in order to enjoy the automated document generation process.
|
||||
|
||||
To get that lawyer-readable version (which is a LaTeX-created) PDF, simply use
|
||||
|
||||
make -C allocations_familiales allocations_familiales.pdf
|
||||
|
||||
from the repository root, once you have managed to install the
|
||||
compiler using [the dedicated readme](INSTALL.md). You can then open `examples/allocations_familiales/allocations_familiales.pdf`
|
||||
|
||||
## Languages
|
||||
|
||||
The Catala language should be adapted to any legislative text that follows a general-to-specifics statutes order. Therefore, there exists multiple versions of the Catala surface syntax, adapted to the language of the lefislative text.
|
||||
|
||||
Currently, Catala supports English and French legislations via the `--language=en` or `--language=fr` option. Contact the authors
|
||||
if you are interested in adding support for another language.
|
||||
|
||||
## Limitations and disclaimer
|
||||
|
||||
### Early stage project
|
||||
|
||||
Catala is a research project from Inria, the French National
|
||||
Research Institute for Computer Science. The compiler is yet very
|
||||
unstable and lacks most of its features. Currently, it only
|
||||
parses the surface language to producde the lawyer-readable PDF,
|
||||
no interpreter or compiler backend is provided.
|
||||
|
||||
However, the language is bound to have a complete formal semantics
|
||||
in the near future. This semantics will guide the compiler
|
||||
implementation.
|
||||
"definition-under-conditions" that builds on default logic has been formalized
|
||||
by Professor of Law 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
|
||||
language perfectly adapted to literate legislative programming.
|
||||
|
||||
## Installation
|
||||
|
||||
See [the dedicated readme](INSTALL.md).
|
||||
|
||||
## Test suite
|
||||
## Examples
|
||||
|
||||
See [the dedicated readme](tests/README.md).
|
||||
See [the dedicated readme](examples/README.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
See [the dedicated readme](CONTRIBUTING.md).
|
||||
|
||||
## Test suite
|
||||
|
||||
See [the dedicated readme](tests/README.md).
|
||||
|
||||
## Documentation
|
||||
|
||||
### Formal semantics
|
||||
|
||||
See [the dedicated readme](doc/formalization/README.md).
|
||||
|
||||
### Compiler documentation
|
||||
|
||||
See [the dedicated readme](src/README.md).
|
||||
|
||||
## License
|
||||
|
||||
The library is released under the Apache license (version 2).
|
||||
The library is released under the [Apache license (version 2)](LICENSE.txt).
|
||||
|
||||
## Limitations and disclaimer
|
||||
|
||||
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. Currently, here is the list
|
||||
of existing features:
|
||||
|
||||
* Literate programming output to HTML or LaTeX
|
||||
* Typechecker and interpreter for most of the language
|
||||
|
||||
|
||||
## Pierre Catala
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ description: """
|
||||
The Catala language is designed to be a low-level target for
|
||||
higher-level specification languages for fiscal legislation.
|
||||
"""
|
||||
maintainer: ["denis.merigoux@inria.fr"]
|
||||
maintainer: ["contact@catala-lang.org"]
|
||||
authors: ["Denis Merigoux"]
|
||||
license: "Apache2"
|
||||
homepage: "https://github.com/CatalaLang/catala"
|
||||
@ -17,11 +17,15 @@ depends: [
|
||||
"sedlex" {>= "2.1"}
|
||||
"menhir" {>= "20200211"}
|
||||
"menhirLib" {>= "20200211"}
|
||||
"unionfind" {>= "20200320"}
|
||||
"bindlib" {>= "5.0.1"}
|
||||
"dune-build-info" {>= "2.0.1"}
|
||||
"cmdliner" {>= "1.0.4"}
|
||||
"re" {>= "1.9.0"}
|
||||
"zarith" {>= "1.10"}
|
||||
"dune" {build}
|
||||
"ocamlgraph" {>= "1.8.8"}
|
||||
"odate" {>= "0.6"}
|
||||
]
|
||||
build: [
|
||||
["dune" "subst"] {pinned}
|
||||
|
||||
|
Before Width: | Height: | Size: 167 KiB After Width: | Height: | Size: 167 KiB |
|
Before Width: | Height: | Size: 128 KiB After Width: | Height: | Size: 128 KiB |
|
Before Width: | Height: | Size: 6.5 KiB After Width: | Height: | Size: 6.5 KiB |
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 11 KiB |
@ -8,7 +8,7 @@
|
||||
(homepage https://github.com/CatalaLang/catala)
|
||||
(bug_reports https://github.com/CatalaLang/catala/issues)
|
||||
(authors "Denis Merigoux")
|
||||
(maintainers "denis.merigoux@inria.fr")
|
||||
(maintainers "contact@catala-lang.org")
|
||||
(license Apache2)
|
||||
|
||||
|
||||
@ -24,13 +24,16 @@
|
||||
(sedlex (>= 2.1))
|
||||
(menhir (>= 20200211))
|
||||
(menhirLib (>= 20200211))
|
||||
(unionfind (>= 20200320))
|
||||
(bindlib (>= 5.0.1))
|
||||
(dune-build-info (>= 2.0.1))
|
||||
(cmdliner (>= 1.0.4))
|
||||
(re (>= 1.9.0))
|
||||
(zarith (>= 1.10))
|
||||
(dune (and :build ))
|
||||
(ocamlgraph (>= 1.8.8))
|
||||
(odate (>= 0.6))
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
(using menhir 2.1)
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
#! /usr/bin/env bash
|
||||
|
||||
sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)
|
||||
@ -1,10 +1,14 @@
|
||||
# Catala test suite
|
||||
|
||||
This folder contains Catala source files designed to test the features of the language.
|
||||
This folder contains Catala source files designed to test the features of the
|
||||
language.
|
||||
|
||||
It uses `make` to launch tests and compare the test terminal output with an expected output.
|
||||
It uses `make pass_tests` to launch tests and compare the test terminal output
|
||||
with an expected output.
|
||||
|
||||
When you create a new test, please register it in the `Makefile` following the other examples. Expected outputs are stored using the convention `<name_of_test>.catala.<name_of_scope>.out` in the corresponding test folder.
|
||||
When you create a new test, please register it in the `Makefile` following the
|
||||
other examples. Expected outputs are stored using the convention
|
||||
`<name_of_test>.catala.<name_of_scope>.out` in the corresponding test folder.
|
||||
|
||||
For both workflows: use `CATALA_OPTS="..." make ...` to pass in Catala compiler
|
||||
options when debugging.
|
||||
@ -34,3 +38,8 @@ options when debugging.
|
||||
5. Re-reun `make` to check that everything passes.
|
||||
6. That's it, you've fixed the Catala test suite to adapt for changes in the
|
||||
language.
|
||||
|
||||
If a compiler change causes a lot of regressions (error message formatting changes
|
||||
for instance), you can mass-reset the expected the outputs with `make reset_tests`.
|
||||
**Caution**: use at your own risk, regressions should be fixed one by one in
|
||||
general.
|
||||
Loading…
Reference in New Issue
Block a user