1# es2panda_lib generation
2
3### How to run:
4```bash
5ninja gen_api   # only generates es2panda_lib.cpp and es2panda_lib.h
6
7ninja es2panda-public   # compiles es2panda_lib
8```
9
10### Tests:
11Tests are located in `ets_frontend/ets2panda/test/unit/public`, their names start with "e2p_test_plugin".
12
13Run tests:
14```bash
15ninja es2panda-plugin-test
16```
17
18
19## Notes, how to work with cppToCTypes.yaml
20In the c++ code of es2panda, there are types that are not presents in c. es2panda_lib must have a c interface. cppToCTypes.yaml describes the translation of complex types from c++ to c.
21
22Why do we describe working with arguments and not with types? Because 1 argument from c++ can expand into several c arguments. For example, `std::vector<int> A` in c will be represented as `int* A, int ALen`.
23
24
25Let's look at the example of `std::pair<type_1, type_2> some_name` how to use this yaml:
26
27
28### es2panda_arg
29This is the key field that is used for pattern matching! Patterns in the form of `|some_identifier|`.
30
31```
32- es2panda_arg:
33    name: '|arg_name|'
34    type:
35        name: std::pair
36        template_args:
37        - type: '|first_type|'
38        - type: '|seond_type|'
39```
40
41Let's assume that in .rb, the search for arguments suitable for this template takes place using validation:
42`es2panda_arg["type"]["name"] == candidate_arg["type"]["name"]`.
43
44Suppose our candidate is `std::pair<int*, int> A`.
45Parsed to yaml is:
46```
47- name: A
48  type:
49    name: std::pair
50    template_args:
51    - type:
52        name: int
53        ptr_depth: 1
54    - type:
55        name: int
56```
57
58es2panda_arg ONLY serves to match templates for the desired type from c++.
59
60In our example we'll have:
61```
62|arg_name| = A
63|first_type| = {"name": int, "ptr_depth": 1}
64|second_type| = {"name": int}
65```
66
67In any subsequent fields in cppToCTypes.yaml we can use these templates. They will be replaced with the desired values.
68
69IMPORTANT! The raw argument from es2panda will be saved intact and will not be changed. Therefore, it is not necessary to describe all possible fields for an argument in es2panda_arg, only those that are used to match templates of the form `|some_field|` and filter the argument that fits this template (usually `es2panda["type"]["name"]`) are needed.
70
71### Features
72Not in es2panda args you can use `|some_code|` pattern like .rb code snippet. 
73
74Example:
75```rb
76|es2panda_arg.type.ptr_depth|
77# or
78|new_args.0.type.ptr_depth|
79```
80
81Note: Recall that es2panda_arg is used only for pattern matching, and after matching, the raw es2panda argument is copied in its entirety. Therefore, even if you did not describe the ptr_depth field in es2panda_arg, but it is in the raw argument itself, you will be able to get this value.
82