[Experiment] A way to put configuration in the same file as its command

[wolfgang42]

I haven't decided if this is a good idea or not, but I've been trying out a way to put configuration for a command in that command's file, rather than centralizing everything into bashly.yml. The advantage of this approach is that all of the information about the command, its flags, etc. is stored in the file, where it's much easier to see than switching between files (particularly, I got confused a couple of times and was looking at the wrong command in the config file, which is much harder to do when you can only see one config at a time). The disadvantage, of course, is that Bashly doesn't actually support this.

I've implemented this with the simplest approach possible; I've defined a special kind of comment (#: ) which should contain the YAML; these comments all get extracted and concatenated together to produce the bashly.yml file for ingestion. It looks something like this:

initialize.sh

#: name: cli
#: help: Sample application
#: version: 0.1.0
#: 
#: environment_variables:
#: - name: api_key
#:   help: Set your API key

## Code here runs inside the initialize() function

download_command.sh

#: name: download
#: short: d
#: help: Download a file
#: 
#: args:
#: - name: source
#:   required: true
#:   help: URL to download from
#: - name: target
#:   help: "Target filename (default: same as source)"
#: 
#: flags:
#: - long: --force
#:   short: -f
#:   help: Overwrite existing files
#: 
#: examples:
#: - cli download example.com
#: - cli download example.com ./output -f

inspect_args

Presumably I ought to be doing some sort of front-matter extraction and parsing so that I can point syntax errors at individual files and so on, but in practice I just use the following script:

(
	cat src/initialize.sh
	echo '#:'
	echo '#: commands:'
	for cmd in src/*_command.sh; do
		echo '#: '
		echo '#: -'
		sed 's%^#:%#:  %' "$cmd"
	done
) | grep -E '^#:' | sed 's%^#: \?%%' \
> src/bashly.yml

As it stands this only works properly if you have exactly one level of subcommands, and also doesn't interact with command groups very well (since the commands end up in filesystem—usually alphabetical—order, and Bashly expects them to be clumped together with the group key on only the first item in the group; so there's mostly no way to do that under this system).

Not sure if this is worth pursuing any further but I thought it might at least provoke an interesting discussion.

[DannyBen]

Interesting point. I also asked myself the same question (although not in bashly's context): is it better to have one file contain multiple information types, or have a separate file for each data structure/concept.

To me, the arguments for each side are usually almost equally weighted, which automatically gives priority to the simple approach of having each concept in its own file.

Now, bashly needs bashly.yml, and this is unlikely (although not impossible) to change soon.

However, there might be a way to alleviate some of the issues, and perhaps even satisfy this feature. Not sure yet it will work or be 100% straight forward to implement, but here goes.

1. I have another small gem called extended_yaml, which lets you "include" other YAML snippets inherit other YAMLs in the primary YAML. We can use this for inspiration.
2. We can allow some form of special directive (like in extended_yaml) that loads front matter from the respective command file.

In other words, imagine these two files:

# bashly.yml
name: cli

commands:
  - load: src/download
  - load: src/upload

# either `src/download.yml` or front matter in `src/download_command.sh`
name: download
short: d
help: Download a file

args:
- ...
- ...

now, the only thing left to implement is the removal of front matter from the shell scripts.

What do you think? Worth exploring further?

[wolfgang42]

Hm, that is an interesting idea. It's certainly a lot less hacky than my current implementation, and it solves the problems with nested commands, ordering, and so on. If you already have the gem I'd say it's worth a try.

From a pragmatic perspective, download.yml seems likely to be easier to implement. I'd prefer the front matter (it's easier to work with one file than two, especially since most of my commands are very short so everything fits on one screen even when combined) but it does require more thinking about how to represent it, and has the disadvantage that text editors aren't going to know what's going on.

[DannyBen]

Yeah, well I thought my gem could help, but I doubt it. It was meant to "extend" YAMLs, not "include" snippets.

But still - I think that having a special, YAML-compatible command (like load: file) is easy enough to add to bashly itself.

As for the decision to load other YAMLs or front matter - I am thinking about supporting both use cases, so people can decide which to use. For example, some users might like to continue using YAML, but would prefer to separate it to multiple YAML files - this is why I included the full path in my load: src/... example - to allow people to bring YAMLs from wherever they want.

I will kick off a PR, see where it goes.

[DannyBen]

The PR is ready: #154