mirror of
https://github.com/CatalaLang/catala.git
synced 2024-09-19 16:28:12 +03:00
Update READMEs
This commit is contained in:
parent
b6d9d7cf5f
commit
d704998f81
@ -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
|
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,
|
specific competences as a socio-fiscal lawyer or a programming language specialist,
|
||||||
please [contact the authors](mailto:contact@catala-lang.org).
|
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;
|
Please note that the copyright of this code is owned by Inria;
|
||||||
by contributing, you disclaim all copyright interests in favor of 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
|
Both the code for the compiler and the examples in this repository are
|
||||||
distributed under the Apache2 license.
|
distributed under the Apache2 license.
|
||||||
|
|
||||||
### Writing Catala code
|
## Writing Catala code
|
||||||
|
|
||||||
Before writing Catala code, please read the
|
Before writing Catala code, please read the
|
||||||
[tutorial](https://catala-lang.org/en/examples/tutorial). You can run 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.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
|
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
|
[online OCaml documentation](https://catala-lang.org/ocaml_docs/) for the
|
||||||
different modules' interfaces as well as high-level architecture documentation.
|
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.
|
Using another version may cause spurious diffs to appear in your pull requests.
|
||||||
|
|
||||||
### Example: adding a builtin function
|
### 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`
|
- in `dcalc/interpreter.ml`, function `evaluate_operator`
|
||||||
- Update the syntax guide in `doc/syntax/syntax.tex` with your new builtin
|
- 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
|
The Catala language should be adapted to any legislative text that follows a
|
||||||
general-to-specifics statutes order. Therefore, there exists multiple versions
|
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.
|
`--language=en`, `--language=fr` or `--language=pl` options.
|
||||||
|
|
||||||
To add support for a new language:
|
To add support for a new language:
|
||||||
|
|
||||||
- the basic syntax localisation is defined in
|
- the basic syntax localisation is defined in
|
||||||
`compiler/surface/lexer_xx.cppo.ml` where `xx` is the language code (`en`,
|
`compiler/surface/lexer_xx.cppo.ml` where `xx` is the language code (`en`,
|
||||||
`fr`...)
|
`fr`...)
|
||||||
- copy the files from another language, e.g.
|
- copy the files from another language, e.g.
|
||||||
[english](compiler/surface/lexer_en.cppo.ml), then replace the strings with your
|
[english](compiler/surface/lexer_en.cppo.ml), then replace the strings with your
|
||||||
translations. Be careful with the following:
|
translations. Be careful with the following:
|
||||||
|
|
||||||
- The file must be encoded in latin-1
|
- The file must be encoded in latin-1
|
||||||
- For a given token `FOO`, define `MS_FOO` to be the string version of the
|
- For a given token `FOO`, define `MS_FOO` to be the string version of the
|
||||||
keyword. Due to the encoding, use `\xNN` [escape
|
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
|
- If the string contains spaces or non-latin1 characters, you need to define
|
||||||
`MR_FOO` as well with a regular expression in [sedlex
|
`MR_FOO` as well with a regular expression in [sedlex
|
||||||
format](https://github.com/ocaml-community/sedlex#lexer-specifications).
|
format](https://github.com/ocaml-community/sedlex#lexer-specifications).
|
||||||
Replace spaces with `", space_plus, "`, and unicode characters with `",
|
Replace spaces with `", space_plus, "`, and unicode characters with `", 0xNNNN, "` where `NNNN` is the hexadecimal unicode codepoint.
|
||||||
0xNNNN, "` where `NNNN` is the hexadecimal unicode codepoint.
|
|
||||||
|
|
||||||
**Hint:** You may get syntax errors with unhelpful locations because of
|
**Hint:** You may get syntax errors with unhelpful locations because of
|
||||||
`sedlex`. In that case the command `ocamlc
|
`sedlex`. In that case the command `ocamlc _build/default/compiler/surface/lexer_xx.ml` may point you to the source of the
|
||||||
_build/default/compiler/surface/lexer_xx.ml` may point you to the source of the
|
|
||||||
error.
|
error.
|
||||||
|
|
||||||
- add your translation to the compilation rules:
|
- add your translation to the compilation rules:
|
||||||
- in `compiler/surface/dune`, copying another `parser_xx.cppo.ml` rule
|
- in `compiler/surface/dune`, copying another `parser_xx.cppo.ml` rule
|
||||||
- in the `extensions` list in `compiler/driver.ml`
|
- in the `extensions` list in `compiler/driver.ml`
|
||||||
|
49
README.md
49
README.md
@ -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
|
embeds default logic as a first-class feature, which is why it is the only
|
||||||
language perfectly adapted to literate legislative programming.
|
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
|
## Building and installation
|
||||||
|
|
||||||
Catala is available as an [opam package](https://opam.ocaml.org/packages/catala/)!
|
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
|
### Catala
|
||||||
|
|
||||||
Use `catala --help` if you have installed it to get more information about the command line
|
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.
|
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
|
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,
|
after `make build`. The `clerk` binary corresponds to the Catala build system,
|
||||||
responsible for testing among other things.
|
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
|
## Examples
|
||||||
|
|
||||||
To explore the different programs written in Catala, see
|
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,
|
To know how to run or improve the Catala reference test suite,
|
||||||
see [the dedicated readme](tests/README.md).
|
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
|
## License
|
||||||
|
|
||||||
The compiler and all the code contained in this repository is released under
|
The compiler and all the code contained in this repository is released under
|
||||||
|
@ -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
|
ou des personnes ayant déjà programmé, même si des juristes avec des appétences
|
||||||
en informatique devraient pouvoir s'en sortir.
|
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
|
### Programmation littéraire
|
||||||
|
|
||||||
Pour commencer à écrire un programme Catala, vous devez partir du texte
|
Pour commencer à écrire un programme Catala, vous devez partir du texte
|
||||||
|
Loading…
Reference in New Issue
Block a user