Topic ideas for "Dhall cookbook"

Right now I’m brainstorming topic ideas for a Dhall Leanpub book I’m going to write that will collect “How-to” guides for various design patterns that are part of Dhall’s oral tradition but that have never been systematically documented anywhere outside of mailing lists, StackOverflow and GitHub issues.

Here are some topic ideas I have so far (in no particular order) and I also invite people to share their own ideas in this thread, too:

  • What use cases is Dhall appropriate/mature for?
  • How to create an ad-hoc binding to an existing YAML/JSON configuration (i.e. a one-off binding for an internal project)
  • How to create a systematic binding to widely used YAML configuration format (e.g. like dhall-kubernetes)
  • How to check a Dhall configuration file against a schema (i.e. type annotations)
  • How to migrate a Dhall configuration file (i.e. a Dhall function)
  • How to deal with weakly-typed JSON idioms (e.g. the JSON type)
  • How to host a package for others to use (e.g. GitLab/GitHub)
  • How to make a package discoverable (???)
  • How to use/obtain/“install” a remote expression/package (e.g. semantic integrity check)
  • How to organize a package (i.e. a typical record API)
  • How to organize a project (i.e. filesystem layout and managing interdependencies)
  • How to make invalid types unrepresentable (i.e. strongly-typed programming idioms)
  • How to secure a Dhall project (e.g. understanding the threat model)
  • How to share a Dhall configuration file across multiple languages and file
    formats (e.g. various dhall-to-* tools and language bindings)
  • Common idioms (e.g. defaults record + //)
  • Naming conventions (e.g. types/alternatives are typically uppercase)
  • How to integrate with twelve-factor app
  • How to use tools like dhall-to-{json,yaml}/{json,yaml}-to-dhall
  • How to integrate Dhall with CI (i.e. automatic formatting/linting/caching)
  • How to edit Dhall code with IDE support
  • How to cope with an evolving language standard

Also, a lot of this stuff might go obsolete if we add language features to render certain patterns unnecessary (e.g. better support for defaults, as a hypothetical example), but the book will be set up on GitHub in a way to accept pull requests to keep it up-to-date.

4 Likes

Based on some recent issues, should cover Prelude use and maybe an overview of what’s in there would be helpful. Best practises for future proofing such as using the Prelude where possible instead of relying on builtins, etc.

1 Like

Great list! :clap:

A section that is not related with “how to use Dhall” but nice to have (maybe in an appendix) could be “how to write a Dhall interpreter”, that walks through all the different phases that one is supposed to implement, and different evaluation strategies (e.g. naive vs NbE, etc)

How to make a package discoverable (???)

Would it make sense to have a “package directory” repo in the dhall-lang org that collects “published” packages? (by pointing at their git repo and/or HTTP URL)
We could even have CI checking compatibility with the latest version of Dhall so that the set stays up to date (yes this is basically a package set)

1 Like

How to create a systematic binding to widely used YAML configuration format
How to use tools like dhall-to-yaml

As a cookbook, I think it should go further and have explicit examples of working Kubernetes objects, along with idioms like kubectl apply -f <(dhall-to-yaml <<< "..."), because that’s non-obvious (especially to Bash newbies) but it’s key to helping show clear relevance and how Dhall fits into existing scripts / codebases. Particularly in the case of dhall-kubernetes, showing idioms like writing a function for a service which takes a deployment as a parameter, and derives the correct configuration for the service, instead of copying and pasting which is otherwise the norm.

package directory repo in dhall-lang.org that collects published packages

I think this is a wonderful idea, but I’d be very, very wary of the hosting costs if it gets popular. Specifically, I imagine that some kind of API would be set up whereby the package server only answers two kinds of queries: what is the hash for a URI, and what is the normalized expression for a URI given the hash as a required parameter. This more or less requires clients to cache / freeze the expressions and thus reduce load on the package server.

1 Like

I think we should just put published packages on the awesome dhall list for now

I like the idea of having a curated package set that is discoverable and kept up to date with the latest version of the compiler. This also gives us an excellent data set to stress test implementations and to inform how disruptive changes would be.

@ari-becker: I’m not concerned about hosting costs because presumably this would be hosted on GitHub.

Cool! I created the dhall-lang/packages repo :blush:

The idea is that there’s a packages.dhall pointing at various packages - I added only the Prelude for now. Once we add more packages this might become slow to fetch with cold cache, but this is part of the stress test too :smile: (we already had this problem with PureScript package sets)

I think we should also cut releases at the same time of the standard (so feel free to PR packages compatible with Dhall 9 already)

2 Likes

At some point we’ll probably need to build infrastructure for a shared global cache (analogous to cache.nixos.org) so that users can begin from a warm cache. However, that’s low on my list of priorities at the moment.

1 Like

Ooh, I like this idea. Especially once we get mixed records.

Though it might be more useful to have Prelude/package.dhall etc instead of one big record in this case, since presumably you don’t want to actually load every package in existence.