Optional ns-qualified keywords

[vemv]

Hi @PawelStroinski !

Very nice lib - I'm looking forward to use it the next time the need pops up.

It occurred to me that if each keyword had a ns-qualified equivalent, one could:

• have them auto-completed
  • e.g. ::stevia/<TAB> and see what's there
• associate documentation to them
  • If keywords can be mapped 1:1 to a namespace/location, then tools jump to them / show a "docstring"
  • this would be a nice place to e.g. copy the official Docker documentation, so that one can learn about the keywords' semantics.

In practice, this an agnostic pattern that works:

(spec/def ::from string?
  #_"The FROM instruction initializes a new build stage and sets the Base Image for subsequent instructions.
As such, a valid Dockerfile must start with a FROM instruction.
The image can be any valid image – it is especially easy to start by pulling an image from the Public Repositories.")

...the #_ is a minimalistic way to add a docstring even when it's not supported currently at Spec level.

A couple of tools that can work with that:

• CIDER has cider-find-keyword to jump to the 'definition' of the keyword
• clojure-lsp can show the whole source code of something in a popup.

wdyt?

Thanks - V

[PawelStroinski]

Hi @vemv,

Thank you so much for your kind feedback and the idea. In addition to attaching the docstrings and discoverability of the available options, I like it because:

• I am a fan of namespaced keywords in general since they are more precise and can have semantics.
• This maybe could be a first step in creating a more detailed spec than what I had in mind in Args validation #5

My thoughts:

• I would like to have the same docstrings for the functions such as stevia/from, so some form of generation from a single source would be ideal.
• If the specs were generated in a macro we of course wouldn't get the jumping functionality nor code preview in clojure-lsp. A basic alternative would be having a map like {::from "The FROM instruction..."} instead of spec, so Show Usages / Peek References would still find it but this is not as nice as jumping to definition.
• What seems to be left is code generation, so the dockerfile.stevia namespace would be generated and the format implementation moved to dockerfile.stevia.format namespace.
• It would be the easiest if some machine-readable data already existed with all the docstrings. If that doesn't exist, composing an EDN file from the Dockerfile reference or reference.md can be done by parsing / manually.
• The keywords used for Map args #3 could naturally be specced too. For instance ::stevia/copy.link for the --link flag of COPY.
• I agree on optionality. Unnamespaced keywords would still be supported since they are shorter and less verbose (pros and cons...).
• The downside is a significant gain in well... code.

Time-permitting, I will think about implementing this, and of course more feedback or PR(s) would be welcomed. Thank you again for the comment and have a good weekend!

Paweł