Make stack config parser self-describing

[chrisdone]

There are many options available in Stack's YAML config files. The Stack manual does a good job of documenting a few with examples, but I'd like to be able to programmatically output the schema so that I can immediately see exactly what's available. This would obviously be a great step for Stack to be self-documenting.

This will require:

1. Switching the WarningParser type to be a newtype.
2. Removing the Monad instance from that newtype.
3. Implementing some ApplicativeDo syntax so that we don't have to rewrite all the code in Applicative style (yet?).
4. Adjust the parser to support generating a description of itself, as well as being a parser.
5. Have a flag like --config-help similar to --help which shows all available options for the YAML file using that description.

We could also include said dump in the Stack manual if we wish.

[chrisdone]

Finished a preliminary implementation of this on branch descriptive-parser: https://github.com/commercialhaskell/stack/compare/descriptive-parser?expand=1

Output looks like:

bash-3.2$ stack --config-help
The following YAML settings are supported: 

work-dir: string [optional]
docker: docker options [optional]
nix: nix options [optional]
connection-count: integer [optional]
hide-th-loading: boolean [optional]
latest-snapshot-url: string [optional]
package-indices: list of package indexs [optional]
system-ghc: boolean [optional]
install-ghc: boolean [optional]
skip-ghc-check: boolean [optional]
skip-msys: boolean [optional]
require-stack-version: version range [optional]
os: string [optional]
arch: string [optional]
ghc-variant: GHC variant [optional]
jobs: integer [optional]
extra-include-dirs: set of strings [optional]
extra-lib-dirs: set of strings [optional]
concurrent-tests: boolean [optional]
local-bin-path: string [optional]
image: image options [optional]
templates: object [optional]
templates.params: mapping [optional]
templates.scm-init: SCM [optional]
compiler-check: version check [optional]
ghc-options: mapping [optional]
extra-path: list of strings [optional]
setup-info: setup info location [optional]
pvp-bounds: PVP bounds [optional]
modify-code-page: boolean [optional]
explicit-setup-deps: mapping [optional]
rebuild-ghc-options: boolean [optional]
apply-ghc-options: GHC options [optional]
allow-newer: boolean [optional]

It's only a surface-level listing of options, it doesn't go into sub-objects. I had a go at forcing all FromJSON instances into a FromDescJSON class, but it was far too much work to complete in a reasonable amount of time.

[borsboom]

@drwebb could this potentially be helpful for stack config set as well?

[mboes]

Sounds awesome. @chrisdone what happened to that branch? :)

[chrisdone]

This branch is pretty old. I'd hoped for better results but wasn't very
satisfied with the final approach. The configuration parser is rather large
and ideally would be rewritten. I don't think it should be merged in.

I was thinking it might be easier to just write a fresh YAML parser capable
of preserving comments and layout, capable of generating a schema for help,
and doing modifications. If/when we make other tools (like a new package
format) it would come in handy. Stack's config is pretty intimidatingly
large though.
On 5 Jun 2016 19:57, "Mathieu Boespflug" [email protected] wrote:

Sounds awesome. @chrisdone https://github.com/chrisdone what happened
to that branch? :)

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#1491 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAArC4dKmTrh-9Ci47nvSwyIugw2HbvCks5qIw4egaJpZM4Gyu9Z
.

[Blaisorblade]

Replaced old label in-progress with "in progress". I suspect the label is stale, but I'm bugged by the label overlap.

[borsboom]

@sjakobi: possibly relevant for what we were talking about with an auto-generated man page.