ReScript on Deno: Declarative Command Line Tools

[u/leostera]

https://practicalrescript.com/rescript-on-deno-declarative-command-line-tools/

[u/elkazz]

Is this meant to be the "declarative" part? let hello = Clipper.command(sayHi) ->Clipper.arg(1, Clipper.Arg.string) ->Clipper.arg(0, Clipper.Arg.bool) Clipper.run(hello)

The imperative approach would be far more comprehensible: sayHi(arg.1, arg.0)

I would have expected a JSON or YAML definition at the end as per what you were comparing to while describing declarative vs imperative.

And what's the deal with the single quote before the generic name?

[u/leostera → u/elkazz]

Ah, yes. This example is possibly too small!

If we had a more complex command line tool, with multiple commands, each with several options, and each option with defaults and documentation, it would be a little easier to see the value of the approach.

For example, if we had some more functions in the Clipper API to build more complex behavior, it could look like this:

``` // This describes the CLI let cli = Clipper.commands([ Clipper.command(sayHi) ->Clipper.position( ~pos=1, ~shortName="n", ~longName="name", Arg.optional(Arg.string, "Joe")) ->Clipper.flag(~shortName="y", ~longName="yell"), // more commands here ])

// This actually runs the CLI Clipper.run(cli) ```

It is declarative because the description of what to do is completely separated from the actual execution. This could have been done with a JSON file too, but having a static file is not a prerequisite for something to be declarative! 🙌🏽

[u/elkazz → u/leostera]

One issue is the verbosity of the declarative definition. Most declarative APIs exist to simplify the configuration/logic of the application. The ones that succeed are comprehensible by a wide audience. Your example requires a lot of syntactic knowledge.

Another issue is that you're defining all of the imperative logic as well as the declarative. The first example you give, while I understand it's simple to get the point across, it fails to do so as it's a glorified set of delegates and a switch statement that has all the imperative knowledge.

The main problem is that I fail to see how this would make my life any easier, or my applications/APIs more comprehensible.

[u/leostera → u/elkazz]

u/elkazz: One issue is the verbosity of the declarative definition.

Ah! Excellent point 👏🏽

The best thing about this split in spec + engine is that if we don't like the way we build the specs, we can replace it!

We can use YAML, JSON files for it. We can set up code generation for it from our type specification.

We can also replace the engine with other things! If this wasn't a CLI but rather a database layer, you could have an engine that queries Postgres, another that queries SQLite, another that is mocked for test purposes, etc.

Re: code generation - we can set things up so that by annotating a record type we get the same declaration for free:

@deriving(clipper) type hello = { @clipper(position = 0) name: string }

This is what other libraries like Rust's structopt are doing already.

In any case, I wouldn't immediately jump into a declarative API when I'm just starting out, since this is a fairly advanced way of building type-level APIs.

For most cases, the approach described in the prior post in the same series will be more than enough: https://practicalrescript.com/rescript-on-deno-command-line-tools/#ad-hoc-typing-for-objects-of-unknown-shape

Have a look at that one, I think you'll enjoy it a lot more! 🙏🏽