Ast_pattern: augment API with `ebool`, `pbool` helper, and a new `map`.

[panglesd]

estring, echar, efloat, ... helpers are created using functions generated from the constant type.

However, this type does not contain boolean constants, such as true and false. Indeed, such constants are defined as constructors (without argument, nor uppercase), as seen using utop -dparsetree:

utop # true ;;
Ptop_def
  [
    structure_item (//toplevel//[1,0+0]..[1,0+4])
      Pstr_eval
      expression (//toplevel//[1,0+0]..[1,0+4])
        Pexp_construct "true" (//toplevel//[1,0+0]..[1,0+4])
        None
  ]

As a consequence, ebool was not added to the Ast_pattern API, even though it is useful (as illustrated here)

It would be useful to have such values in the API:

val ebool : (bool, 'a, 'b) t -> (expression, 'a, 'b) t
val pbool : (bool, 'a, 'b) t -> (pattern, 'a, 'b) t

While looking at this, I noticed that we are also missing two maps:

val map_value : f:('a -> 'b) -> ('b, 'c, 'd) t -> ('a, 'c, 'd) t
val map_value' : f:(location -> 'a -> 'b) -> ('b, 'c, 'd) t -> ('a, 'c, 'd) t

with which it is simple to generate ebool and pbool, and that should be added to the API as well!

[Burnleydev1]

Hello @panglesd, please I would like to work on this issue.

[panglesd]

Hello @Burnleydev1!

Great, feel free to ask me any question you would have: Ast_pattern can be confusing!

[Burnleydev1]

Thanks @panglesd, my first question may be offtopic, I wish to ask if there is a way for me to locally build the API website.

[panglesd]

Sure! You can run dune build @doc. This will generate the doc, the entry point to it is _build/default/_doc/index.html.

[panglesd]

Some potentially useful information: some part of the code of Ast_pattern is generated in the Ast_pattern_generated module.
If you want to see what it looks like, you can find it at _build/default/src/ast_pattern_generated.ml after having run dune build.

[Burnleydev1]

Thanks, @panglesd, if I am not mistaken, it means that I need to add those values in such a way that it shows on the api in the manner you described in the comment above?

[Burnleydev1]

Hello @panglesd, please correct me if I am wrong, I think I understand now, what we want to do is to add a constant like pconst_bool so that it can be used to achieve something like this val ebool : (bool, 'a, 'b) t -> (expression, 'a, 'b) t
I noticed that the only bool was pdir_bool, but it is not compatible with pexp_constant.

[Burnleydev1]

I may be totally wrong, but the reason I stated the above observation is because when i use pdir_bool, i get this error

(bool, 'a, 'b) t -> (directive_argument, 'a, 'b) t

This expression has type (directive_argument, 'a, 'b) t
but an expression was expected of type (constant, 'c, 'd) t
Type directive_argument is not compatible with type constant

[panglesd]

It is important to understand well the AST types in order to solve this issue!

The AST type can be found here: https://ocaml.org/p/ppxlib/latest/doc/Astlib/Ast_500/Parsetree/index.html
Most types and constructors are explained with a small example to what they correspond to. For instance, the constant type has several variant: Pconst_integer, Pconst_char, ... which correspond to different type of constants: for instance 14 would be represented as Pconst_integer(14, None).

If you look at directive_argument, you can see that they correspond to arguments to toplevel phrases. (toplevel phrases are used to control the toplevel behavior, see it in the manual).
This has nothing to do with what we are interested in (expression), so let's ignore it now!

We are interested in how to turn a bool into an expression.
If you look at the expression type, there are many ways to build an expression. For constants, you use Pexp_constant, but as you can see in the constant type, this is not what is used to define the true and false constant booleans.

If you want to know the AST that corresponds to a specific expression, you can run utop with the -dparsetree option. This will make the toplevel to pretty print the AST value corresponding to what you sent to the toplevel. You can also use https://astexplorer.net/ for this.

If you use any of the tool to know the AST corresponding to true, you will see that true is represented using Pexp_construct, the variant to represent constructors!

Before adding ebool and pbool to Ast_pattern, I think it would be a good warm-up to add ebool and pbool to Ast_builder. Ast_builder and Ast_pattern are quite similar, but the former one is easier to manipulate, and less confusing. You can find some documentation on Ast_builder here!

So, the function to add to Ast_builder would have type:

(* in Ast_builder.Default *)
val ebool : ~loc:location -> bool -> expression
val pbool : ~loc:location -> bool -> pattern

(* in Ast_builder.Make *)
val ebool : bool -> expression
val pbool : bool -> pattern

They would respectively build an expression or a pattern representing a boolean, from such a boolean. To build such values, you can use other values of Ast_builder such as pexp_construct, or directly the AST type. (You won't need the map I was referring to in Ast_pattern, forget about this one for now!)

When I say "add to the API", I mean:

• Add an implementation of the functions in the .ml file,
• Add the signature of the function to the .mli file, so that they are accessible by other modules

and that's it! They will automatically appear in the documentation.

I hope it is clearer what you have to do, and how!

[Burnleydev1]

@panglesd, Thanks a lot for the pointers, I will get on it right away.

[Burnleydev1]

Hello @panglesd, I noticed that ebool and pbool already exist on ast_builder.Default and Ast_builder.Make.

[panglesd]

Good point, sorry I missed that!

In this case, you can try the Ast_pattern version.

[Burnleydev1]

Okay @panglesd, I will get on that right away.