CatalaLang/catala
1
1
Fork 0
mirror of https://github.com/CatalaLang/catala.git synced 2024-11-08 07:51:43 +03:00
Code Issues Projects Releases Wiki Activity

Added more doc

Browse Source
This commit is contained in:
Denis Merigoux 2021-06-25 10:50:49 +02:00
parent 771bc83080
commit ae8ef08b81
No known key found for this signature in database
GPG Key ID: EE99DCFA365C3EE3
8 changed files with 244 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
CONTRIBUTING.md
View File

@ -38,7 +38,7 @@ and articles markers:
### Sub-heading (the more '#', the less important)
#### [Legislative atom]
#### Legislative atom
```
Please look at the code of other examples to see how to format things properly.
@ -53,19 +53,19 @@ to see if you've made any syntax errors. Once the text formatting is done, you
can start to annotate each legislative atom (article, provision, etc.) with
some Catala code. To open up a code section in Catala, simply use
~~~markdown
````markdown
```catala
# In code sections, comments start with #
scope Foo:
<your code goes here>
```
~~~
````
While all the code sections are equivalent in terms of execution, you can
mark some as "metadata" so that they are printed differently on lawyer-facing
documents. Here's how it works:
~~~markdown
````markdown
> Begin metadata # > Début métadonnées en français
```catala
@ -77,7 +77,7 @@ declaration structure FooBar:
```
> End metadata # > Fin métadonnées en français
~~~
````
Again, make sure to regularly check that your example is parsing correctly. The error message from the compiler should help you debug the syntax if need be. You can also
live-test the programs you wrote by feeding them to the interpreter

136
Makefile
View File

@ -115,7 +115,7 @@ vscode_en: ${CURDIR}/syntax_highlighting/en/setup_vscode.sh
vscode: vscode_fr vscode_en
##########################################
# Examples-related rules
# Literate programming and examples
##########################################
EXAMPLES_DIR=examples
@ -154,6 +154,81 @@ literate_polish_taxes: build
literate_examples: literate_allocations_familiales literate_code_general_impots \
literate_us_tax_code literate_tutorial_en literate_tutoriel_fr literate_polish_taxes
##########################################
# French law library
##########################################
#-----------------------------------------
# OCaml
#-----------------------------------------
FRENCH_LAW_OCAML_LIB_DIR=french_law/ocaml
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/allocations_familiales.ml: .FORCE
CATALA_OPTS="$(CATALA_OPTS) -O -t" $(MAKE) -C $(ALLOCATIONS_FAMILIALES_DIR) allocations_familiales.ml
cp -f $(ALLOCATIONS_FAMILIALES_DIR)/allocations_familiales.ml $@
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/unit_tests/tests_allocations_familiales.ml: .FORCE
CATALA_OPTS="$(CATALA_OPTS) -O -t" $(MAKE) -s -C $(ALLOCATIONS_FAMILIALES_DIR) tests/tests_allocations_familiales.ml
cp -f $(ALLOCATIONS_FAMILIALES_DIR)/tests/tests_allocations_familiales.ml $@
#> generate_french_law_library_ocaml : Generates the French law library OCaml sources from Catala
generate_french_law_library_ocaml:\
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/allocations_familiales.ml \
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/unit_tests/tests_allocations_familiales.ml
$(MAKE) format
#> build_french_law_library_ocaml : Builds the OCaml French law library
build_french_law_library_ocaml: generate_french_law_library_ocaml format
dune build $(FRENCH_LAW_OCAML_LIB_DIR)/api.a
run_french_law_library_benchmark_ocaml: generate_french_law_library_ocaml
dune exec --profile release $(FRENCH_LAW_OCAML_LIB_DIR)/bench.exe
run_french_law_library_ocaml_tests: build_french_law_library_ocaml
dune exec $(FRENCH_LAW_OCAML_LIB_DIR)/law_source/unit_tests/run_tests.exe
#-----------------------------------------
# JS
#-----------------------------------------
FRENCH_LAW_JS_LIB_DIR=french_law/js
run_french_law_library_benchmark_js: build_french_law_library_js
$(MAKE) -C $(FRENCH_LAW_JS_LIB_DIR) bench
#> build_french_law_library_js : Builds the JS version of the OCaml French law library
build_french_law_library_js: generate_french_law_library_ocaml format
dune build --profile release $(FRENCH_LAW_OCAML_LIB_DIR)/api_web.bc.js
cp -f $(ROOT_DIR)/_build/default/$(FRENCH_LAW_OCAML_LIB_DIR)/api_web.bc.js $(FRENCH_LAW_JS_LIB_DIR)/french_law.js
#-----------------------------------------
# Python
#-----------------------------------------
FRENCH_LAW_PYTHON_LIB_DIR=french_law/python
$(FRENCH_LAW_PYTHON_LIB_DIR)/src/allocations_familiales.py: .FORCE
CATALA_OPTS="$(CATALA_OPTS) -O -t" $(MAKE) -C $(ALLOCATIONS_FAMILIALES_DIR) allocations_familiales.py
cp -f $(ALLOCATIONS_FAMILIALES_DIR)/allocations_familiales.py $@
#> generate_french_law_library_python : Generates the French law library Python sources from Catala
generate_french_law_library_python:\
$(FRENCH_LAW_PYTHON_LIB_DIR)/src/allocations_familiales.py
. $(FRENCH_LAW_PYTHON_LIB_DIR)/env/bin/activate ;\
$(MAKE) -C $(FRENCH_LAW_PYTHON_LIB_DIR) format
#> type_french_law_library_python : Types the French law library Python sources with mypy
type_french_law_library_python: generate_french_law_library_python
. $(FRENCH_LAW_PYTHON_LIB_DIR)/env/bin/activate ;\
$(MAKE) -C $(FRENCH_LAW_PYTHON_LIB_DIR) type
run_french_law_library_benchmark_python: type_french_law_library_python
. $(FRENCH_LAW_PYTHON_LIB_DIR)/env/bin/activate ;\
$(MAKE) -C $(FRENCH_LAW_PYTHON_LIB_DIR) test
##########################################
# High-level test and benchmarks commands
##########################################
@ -182,65 +257,6 @@ bench_js: run_french_law_library_benchmark_js
bench_python: run_french_law_library_benchmark_python
##########################################
# French law library
##########################################
FRENCH_LAW_OCAML_LIB_DIR=french_law/ocaml
FRENCH_LAW_JS_LIB_DIR=french_law/js
FRENCH_LAW_PYTHON_LIB_DIR=french_law/python
$(FRENCH_LAW_PYTHON_LIB_DIR)/src/allocations_familiales.py: .FORCE
CATALA_OPTS="$(CATALA_OPTS) -O -t" $(MAKE) -C $(ALLOCATIONS_FAMILIALES_DIR) allocations_familiales.py
cp -f $(ALLOCATIONS_FAMILIALES_DIR)/allocations_familiales.py $@
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/allocations_familiales.ml: .FORCE
CATALA_OPTS="$(CATALA_OPTS) -O -t" $(MAKE) -C $(ALLOCATIONS_FAMILIALES_DIR) allocations_familiales.ml
cp -f $(ALLOCATIONS_FAMILIALES_DIR)/allocations_familiales.ml $@
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/unit_tests/tests_allocations_familiales.ml: .FORCE
CATALA_OPTS="$(CATALA_OPTS) -O -t" $(MAKE) -s -C $(ALLOCATIONS_FAMILIALES_DIR) tests/tests_allocations_familiales.ml
cp -f $(ALLOCATIONS_FAMILIALES_DIR)/tests/tests_allocations_familiales.ml $@
#> generate_french_law_library_ocaml : Generates the French law library OCaml sources from Catala
generate_french_law_library_ocaml:\
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/allocations_familiales.ml \
$(FRENCH_LAW_OCAML_LIB_DIR)/law_source/unit_tests/tests_allocations_familiales.ml
$(MAKE) format
#> build_french_law_library_ocaml : Builds the OCaml French law library
build_french_law_library_ocaml: generate_french_law_library_ocaml format
dune build $(FRENCH_LAW_OCAML_LIB_DIR)/api.a
run_french_law_library_benchmark_ocaml: generate_french_law_library_ocaml
dune exec --profile release $(FRENCH_LAW_OCAML_LIB_DIR)/bench.exe
run_french_law_library_ocaml_tests: build_french_law_library_ocaml
dune exec $(FRENCH_LAW_OCAML_LIB_DIR)/law_source/unit_tests/run_tests.exe
run_french_law_library_benchmark_js: build_french_law_library_js
$(MAKE) -C $(FRENCH_LAW_JS_LIB_DIR) bench
#> build_french_law_library_js : Builds the JS version of the OCaml French law library
build_french_law_library_js: generate_french_law_library_ocaml format
dune build --profile release $(FRENCH_LAW_OCAML_LIB_DIR)/api_web.bc.js
cp -f $(ROOT_DIR)/_build/default/$(FRENCH_LAW_OCAML_LIB_DIR)/api_web.bc.js $(FRENCH_LAW_JS_LIB_DIR)/french_law.js
#> generate_french_law_library_python : Generates the French law library Python sources from Catala
generate_french_law_library_python:\
$(FRENCH_LAW_PYTHON_LIB_DIR)/src/allocations_familiales.py
. $(FRENCH_LAW_PYTHON_LIB_DIR)/env/bin/activate ;\
$(MAKE) -C $(FRENCH_LAW_PYTHON_LIB_DIR) format
#> type_french_law_library_python : Types the French law library Python sources with mypy
type_french_law_library_python: generate_french_law_library_python
. $(FRENCH_LAW_PYTHON_LIB_DIR)/env/bin/activate ;\
$(MAKE) -C $(FRENCH_LAW_PYTHON_LIB_DIR) type
run_french_law_library_benchmark_python: type_french_law_library_python
. $(FRENCH_LAW_PYTHON_LIB_DIR)/env/bin/activate ;\
$(MAKE) -C $(FRENCH_LAW_PYTHON_LIB_DIR) test
##########################################
# Website assets

21
README.md
View File

@ -75,21 +75,30 @@ them, use
## Examples
See [the dedicated readme](examples/README.md).
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)
## Contributing
See [the dedicated readme](CONTRIBUTING.md).
To know how you can contribute to the project, see
[the dedicated readme](CONTRIBUTING.md).
## Test suite
See [the dedicated readme](tests/README.md).
To know how to run or improve the Catala reference test suite,
see [the dedicated readme](tests/README.md).
## Documentation
### Formal semantics
See [the dedicated readme](doc/formalization/README.md).
To audit the formal proof of the partial certification of the Catala compiler,
see [the dedicated readme](doc/formalization/README.md).
### Compiler documentation
@ -103,7 +112,9 @@ The documentation is also accessible [online](https://catala-lang.org/ocaml_docs
## License
The library is released under the [Apache license (version 2)](LICENSE.txt).
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.
## Limitations and disclaimer

30
french_law/README.md Normal file
View File

@ -0,0 +1,30 @@
# French Law Libraries
This folder presents a working example of how Catala could be distributed and
deployed inside existing applications. Each sub-folder is specialized for
a particular programming language, and features a ready-to-use library of
all the French public algorithms coded up using Catala so far.
## General principles
Let us say you want to deploy a Catala program inside an application written
in programming language X. The Catala compiler will translate the source
Catala program into X, yielding a new `.x` source code file. This `.x` file
will export functions corresponding to the scopes of the original Catala
program. You can then reuse those exported functions in your application written
in X.
## OCaml
To see how to deploy Catala programs as an OCaml library, see
[the dedicated readme](ocaml/README.md).
## JS
To see how to deploy Catala programs as a JS library, see
[the dedicated readme](js/README.md).
## Python
To see how to deploy Catala programs as a Python library, see
[the dedicated readme](Python/README.md).

26
french_law/js/README.md
View File

@ -1,10 +1,26 @@
# The French Law Javascript Library
# Javascript French Law Library
This Javascript library contains some computations defined by French
legislative texts. The JS code is extracted from OCaml, which is itself
extracted from Catala code (https://catala-lang.org).
This folder contains a ready-to-use Javascript library featuring French public
algorithms coded up in Catala.
## Allocations familiales
## Generating the source files
The JS code is extracted from OCaml using
[`js_of_ocaml`](https://ocsigen.org/js_of_ocaml/). See the
[dedicated README](../ocaml/README.md) of the OCaml library for more precisions
about the OCaml code. The wrapping between OCaml and JS is done by the
`api_web.ml` module.
You can generate the `french_law.js` source JS module by invoking this command
from the root of the repository:
```
make build_french_law_library_js
```
## Available algorithms
### Allocations familiales
The function of the library is `computeAllocationsFamiliales`. This computation
returns the amount of _allocations familiales_ for one household described

50
french_law/ocaml/README.md Normal file
View File

@ -0,0 +1,50 @@
# OCaml French Law Library
This folder contains a ready-to-use OCaml library featuring French public
algorithms coded up in Catala.
## Organization
### Law source
The `law_source` folder contains the files generated by the Catala compiler.
These files are generated using the following rule from the top-level `Makefile`
of this repository:
```
make generate_french_law_library_ocaml
```
They can be compiled using
```
make build_french_law_library_ocaml
```
In particular, `law_source/unit_tests/run_tests.ml` provides an executable
that runs the unit tests coming from the source Catala examples, and that can
be launched with
```
make run_french_law_library_ocaml_tests
```
The `law_source` files rely on the Catala OCaml runtime, located in
`compiler/runtime.{ml, mli}`. This runtime defines the types of the values
manipulated by the Catala programs in OCaml and the operations available for them.
### Wrappers
Then, the `api.{ml, mli}` module provides a wrapper around the functions
exported in `law_source`. These wrappers mostly convert back and forth between
idiomatic OCaml types and the types expected by the Catala programs in OCaml.
`api.web.ml` is used for the JS library (see the [dedicated README](../js/README.md)).
Finally, `bench.ml` provides a simple benchmarking executable that runs the
computations of each algorithm a bunch of times with random inputs. You can run it
from the root of this repository with
```
make run_french_law_library_benchmark_ocaml
```

2
french_law/ocaml/law_source/unit_tests/run_tests.ml
View File

@ -21,4 +21,6 @@ let _ =
try_test "Allocations familiales #6" Tests_allocations_familiales.test6;
try_test "Allocations familiales #7" Tests_allocations_familiales.test7;
try_test "Allocations familiales #8" Tests_allocations_familiales.test8;
try_test "Allocations familiales #9" Tests_allocations_familiales.test9;
try_test "Allocations familiales #10" Tests_allocations_familiales.test10;
exit (if !failure then -1 else 0)

43
french_law/python/README.md Normal file
View File

@ -0,0 +1,43 @@
# Python French Law Library
This folder contains a ready-to-use Python library featuring French public
algorithms coded up in Catala.
The Python version expected to run the Python code is above 3.6. For the commands
noted below to run, you are expected to setup a virtual Python environment with
`virtualenv` by running the `setup_env.sh` script.
## Organization
### Law source
The `src/` folder contains the Python files generated by the Catala compiler.
To update them from the Catala sources, invoke this command from the root
of the repository:
```
make generate_french_law_library_python
```
The Python files generated by the Catala compiler expect the presence of the
`src/catala.py` file which contains the definitions of the values and operations
used by the generated code.
All theses Python files feature type annotations which can be checked against
using
```
make make type_french_law_library_python
```
### Wrappers
To use the algorithms in `src/`, you can take a look at the example provided in
`main.py`. It is very important to wrap all of the input parameters using
`src/catala.py` conversion functions.
You can benchmark the computation using
```
make run_french_law_library_benchmark_python
```