CatalaLang/catala
1
1
Fork 0
mirror of https://github.com/CatalaLang/catala.git synced 2024-09-16 14:57:13 +03:00
Code Issues Projects Releases Wiki Activity

Update READMEs

Browse Source
This commit is contained in:
Denis Merigoux 2022-02-13 23:40:23 +01:00
parent b6d9d7cf5f
commit d704998f81
No known key found for this signature in database
GPG Key ID: EE99DCFA365C3EE3
3 changed files with 49 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
CONTRIBUTING.md
View File

@ -10,14 +10,14 @@ any questions about the project.
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.
The Catala team meets over visioconference once every week.
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.
### Writing Catala code
## Writing Catala code
Before writing Catala code, please read the
[tutorial](https://catala-lang.org/en/examples/tutorial). You can run the
@ -47,6 +47,8 @@ using for instance
```
make -C examples/foo foo.tex
make -C examples/foo foo.py
make -C examples/foo foo.ml
```
to see if you've made any syntax errors. Once the text formatting is done, you
@ -87,7 +89,7 @@ You can look at the
[online OCaml documentation](https://catala-lang.org/ocaml_docs/) for the
different modules' interfaces as well as high-level architecture documentation.
Please note that the `ocamlformat` version this project uses is `0.18.0`.
Please note that the `ocamlformat` version this project uses is `0.19.0`.
Using another version may cause spurious diffs to appear in your pull requests.
### Example: adding a builtin function
@ -114,7 +116,7 @@ need more, here is how one can be added:
- in `dcalc/interpreter.ml`, function `evaluate_operator`
- Update the syntax guide in `doc/syntax/syntax.tex` with your new builtin
## Internationalization
### Internationalization of the Catala syntax
The Catala language should be adapted to any legislative text that follows a
general-to-specifics statutes order. Therefore, there exists multiple versions
@ -124,12 +126,14 @@ Currently, Catala supports English, French and Polish legislative text via the
`--language=en`, `--language=fr` or `--language=pl` options.
To add support for a new language:
- the basic syntax localisation is defined in
`compiler/surface/lexer_xx.cppo.ml` where `xx` is the language code (`en`,
`fr`...)
- copy the files from another language, e.g.
[english](compiler/surface/lexer_en.cppo.ml), then replace the strings with your
translations. Be careful with the following:
- The file must be encoded in latin-1
- For a given token `FOO`, define `MS_FOO` to be the string version of the
keyword. Due to the encoding, use `\xNN` [escape
@ -138,13 +142,12 @@ To add support for a new language:
- If the string contains spaces or non-latin1 characters, you need to define
`MR_FOO` as well with a regular expression in [sedlex
format](https://github.com/ocaml-community/sedlex#lexer-specifications).
Replace spaces with `", space_plus, "`, and unicode characters with `",
0xNNNN, "` where `NNNN` is the hexadecimal unicode codepoint.
Replace spaces with `", space_plus, "`, and unicode characters with `", 0xNNNN, "` where `NNNN` is the hexadecimal unicode codepoint.
**Hint:** You may get syntax errors with unhelpful locations because of
`sedlex`. In that case the command `ocamlc
_build/default/compiler/surface/lexer_xx.ml` may point you to the source of the
`sedlex`. In that case the command `ocamlc _build/default/compiler/surface/lexer_xx.ml` may point you to the source of the
error.
- add your translation to the compilation rules:
- in `compiler/surface/dune`, copying another `parser_xx.cppo.ml` rule
- in the `extensions` list in `compiler/driver.ml`

49
README.md
View File

@ -87,6 +87,12 @@ 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.
## 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.
## Building and installation
Catala is available as an [opam package](https://opam.ocaml.org/packages/catala/)!
@ -108,7 +114,8 @@ want to compile it from the sources of this repository or use nix. For that, see
### Catala
Use `catala --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_catala`
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`
after `make build`. The `catala` binary corresponds to the Catala compiler.
The top-level `Makefile` contains a lot of useful targets to run. To display
@ -123,6 +130,29 @@ options available. To get the development version of the help, run `make help_cl
after `make build`. The `clerk` binary corresponds to the Catala build system,
responsible for testing among other things.
## Documentation
### Syntax cheat sheet
A complete and handy reference of the Catala syntax can be found in the
[cheat sheet](doc/syntax/syntax.pdf) (for French and English versions
of the syntax).
### 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 compiler documentation is auto-generated from its source code using
`dune` and `odoc`. Use
make doc
to generate the documentation, then open the `doc/odoc.html` file in any browser.
The documentation is also accessible [online](https://catala-lang.org/ocaml_docs/).
## Examples
To explore the different programs written in Catala, see
@ -143,23 +173,6 @@ To know how you can contribute to the project, see
To know how to run or improve the Catala reference test suite,
see [the dedicated readme](tests/README.md).
## Documentation
### 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 compiler documentation is auto-generated from its source code using
`dune` and `odoc`. Use
make doc
to generate the documentation, then open the `doc/odoc.html` file in any browser.
The documentation is also accessible [online](https://catala-lang.org/ocaml_docs/).
## License
The compiler and all the code contained in this repository is released under

7
examples/tutoriel_fr/tutoriel_fr.catala_fr
View File

@ -6,6 +6,13 @@ législatifs avec ce langage. Ce document s'adresse principalement à des dével
ou des personnes ayant déjà programmé, même si des juristes avec des appétences
en informatique devraient pouvoir s'en sortir.
```catala
# Attention, ce tutoriel en français n'est peut-être pas à jour avec
# les dernières fonctionnalités du langage. En effet, le tutoriel en anglais
# disponible sur https://catala-lang.org/en/examples/tutorial constitue
# la référence pour le langage.
```
### Programmation littéraire
Pour commencer à écrire un programme Catala, vous devez partir du texte