Inline annotations

[nvasilakis]

There are cases when a user might want to provide an annotation for a custom command or even override (force) a behavior on an existing command. In these cases, writing a full JSON in a custom directory is inconvenient. A more convenient approach would be to provide an inline annotation, which PaSh could read and expand appropriately during its pre-processing stage:

# bigram_aux_map :: (pure, args[0], args[1:4])
bigram_aux_map() {
  #...
}

Most annotations will fall under a few distinct categories, and thus expressiveness can be optimized towards the common case—after all, developers can always fall back to the JSON for the full expressive power of the annotation subsystem. This infrastructure and associated annotation economy may accelerate research in annotations.

[angelhof]

That is a great idea! A thought:

To start quickly (and avoid implementing a parser), we could just make a few nop bash functions that express the annotation and then wrap commands with them. PaSh could then simply determine the class based on the wrapper function and remove it before execution. Example:

## pash_stateless could be a `nop` function where 
## its first argument indicates the following command's inputs, 
## and the second argument indicates the following command's outputs.
pash_stateless stdin stdout grep ...

## or
pash_pure args[:] stdout sort ...

[nvasilakis]

This is a great idea. My only (minor) worry is that if this script is not executed by PaSh, but rather by bash or zsh, it would break. A cool feature of annotations (both as JSON or comments) is that they live "on the side", not interfering with the normal execution of the script (a script that could, for example, be sourced by another Bash script).

[angelhof]

That is true, however, it could be easily solved by sourcing a pash-annotation.sh library at the beginning of scripts that use that, that instantiate these functions as nops. I agree that this is still not ideal though, it is just a first solution that would enable solving the PaSh internal issues related to annotations, and only then moving to the parsing issues.

If parsing is simple, we should go straight to it :)

[nvasilakis]

This is a great idea!

(Reading your message I also realized you're talking about the simplest way to get started whereas I was talking about something closer to the final design — so I fully agree with you!)

[mgree]

I see two options that keep compliance:

(1) use environment variables, e.g., PASH_ANNOTATIONS in some format that lets you extend it, like the path
(2) overload the noop command : so that commands of the form : pash-annotate ... will get interpreted by us.

[angelhof]

In the same vein like this, we could configure other PaSh related stuff too like this (like set but for PaSh). For example, toggling PaSh's assert compiler success on and off.

[mgree]

Yes, agreed! I think the : form is the absolute simplest, though it would add a form of invisible dynamic scoping (i.e., the last : pash-config FOO command wins). The variables pollute the environment, but you can lexically override them (PASH_CONFIG=FOO op will scope just to the function/command op) which is nice.