Documentation has been written

Alfons.moon

@@ -1,9 +1,9 @@
 tasks:
   --- @task make Install a local version of a version
-  --- @argument make [v] <version:string> Current version
+  --- @option make [v] <version:string> Current version
   make:    => sh "rockbuild -m --delete #{@v}" if @v
   --- @task release Create and upload a release of Alfons using %{magenta}`rockbuild`%{reset}.
-  --- @argument release [v] <version:string> Current version
+  --- @option release [v] <version:string> Current version
   release: => sh "rockbuild -m -t #{@v} u"     if @v
   --- @task compile Compile all MoonScript files
   compile: =>
@@ -17,8 +17,8 @@ tasks:
       continue if (file\match "tasks")
       delete file
   --- @task pack Pack an Alfons build using amalg.lua
-  --- @argument pack [output o] <file> Output file (Default: %{green}"alfons.lua"%{reset})
-  --- @argument pack [entry s] <file> Entry file (Default: %{green}"bin/alfons.lua"%{reset})
+  --- @option pack [output o] <file> Output file (Default: %{green}"alfons.lua"%{reset})
+  --- @option pack [entry s] <file> Entry file (Default: %{green}"bin/alfons.lua"%{reset})
   pack: =>
     show "Packing using amalg.lua"
     @o    or= @output or "alfons.lua"
@@ -33,7 +33,7 @@ tasks:
     tasks.pack!
     tasks.clean!
   --- @task test Run an Alfons test
-  --- @argument test [n] <name> Name of the test to run
+  --- @option test [n] <name> Name of the test to run
   test: => sh "moon test/#{@n or ''}.moon"
   -- dummy tasks
   hello:  => print "hello!"

README.md

@@ -12,11 +12,16 @@
 
 Alfons is a task runner to help you manage your project. It's inspired by the worst use cases of Make (this means using `make` instead of shell scripts), it will read an Alfonsfile, extract the exported functions and run the tasks in order. I would tell you that there is no real reason to use this thing, but it's becoming surprisingly useful, so actually try it out.
 
+> [!TIP]
+> Check out the 5.2 update!
+> Shell autocompletions, help messages, Taskfile documentations and extra environment functions have been added.
+
 ## Table of contents
 
 - [Alfons 5](#alfons-5)
   - [Table of contents](#table-of-contents)
   - [Changelog](#changelog)
+    - [5.2](#52)
     - [5](#5)
     - [4.4](#44)
     - [4.3](#43)
@@ -37,6 +42,26 @@ Alfons is a task runner to help you manage your project. It's inspired by the wo
 
 ## Changelog
 
+### 5.2
+- **5.2** (08.06.2024) Implemented Taskfile documentation, help messages and autocompletion
+
+- **Taskfile documentation.** You can now document your Taskfiles for automatic help messages and shell completion.
+  - Check [the documentation](docs/documenting.md) for more info.
+- **Help messages.** You can now display a help message with `--help`, or even get help for a specific task with `--help [task]`.
+  - This help message can be automatically generated from the detected tasks in the Taskfile.
+  - It works best when you document your Taskfile, so you can add descriptions and options.
+- **Shell autocompletion.** Shell autocompletion is now available in Zsh and Bash flavors.
+  - The Zsh flavor is by far the most complete, since Zsh's completion system is slightly more capable.
+  - Bash is only able to list tasks, and sometimes options or flags for those tasks. Use Zsh.
+  - Check [the documentation](docs/autocompletion.md) for more info and install instructions.
+- **Additions to the environment.**
+  - `lines`: Split a string into lines
+  - `split`: Split any string by any pattern
+  - `sanitize`: Neutralizes pattern magic characters in strings
+  - `keys`: Get the keys of a table as an array
+  - `slice`: Creates a slice of an array
+  - `map`, `reduce`, `filter` do to arrays what you would expect
+  - `contains` has been rewritten
 ### 5
 
 - **5.0.2** (23.01.2023) Rolled back test mode

docs/api.md

@@ -14,6 +14,8 @@ Starting with 4.2, Alfons provides an API to embed Alfons functionality in your
   - [alfons.provide](#alfonsprovide)
   - [alfons.setfenv](#alfonssetfenv)
   - [alfons.version](#alfonsversion)
+  - [alfons.help](#alfonshelp)
+  - [alfons.parser](#alfonsparser)
   - [alfons.init](#alfonsinit)
     - [initEnv](#initenv)
     - [runString](#runstring)
@@ -53,8 +55,7 @@ The rock also installs optional dependencies for Alfons like `http` or `linotify
 
 ## alfons.file
 
-Contains just two functions, `readLua`, which takes a filename and returns its contents; and `readMoon`, which does the same, but compiling the file contents as MoonScript.
-
+Contains a generic function `readFile` that reads a file content and loads it, an alias `readLua`, and then `readMoon` which compiles MoonScript content from a file before returning the Lua value, and `readTeal` for a Teal equivalent.
 ## alfons.getopt
 
 Contains a single function, `getopt`, which takes a list of arguments, and returns a table of parsed options. 
@@ -81,6 +82,14 @@ Returns a function (not a table). The function is simply a reimplementation of s
 
 Returns a table with a field `VERSION` which contains the current Alfons version.
 
+## alfons.help
+
+Contains functions to generate help messages, including a column formatter.
+
+## alfons.parser
+
+Contains the comment parser for documenting Taskfiles.
+
 ## alfons.init
 
 Provides the main functions required to run a Taskfile.
@@ -197,4 +206,4 @@ env.finalize!
 
 #### Finish
 
-And just like that, we have implemented Alfons! It is a pretty simple tool, despite the looks of it, really.
+And just like that, we have implemented Alfons! It is a pretty simple tool, despite the looks of it, really.

docs/autocompletion.md

@@ -0,0 +1,30 @@
+# Autocompletion
+
+Alfons 5.2 introduced dynamic shell autocompletion. That means that on most shells (but especially Zsh), you will get completions for tasks, task options and maybe even task values.
+
+## Bash
+
+The Bash completion script is very poor. This is because Bash's autocompletion is very poor. It will list the available tasks, and if it can detect a task, also suggest the options for that task.
+
+### Installing
+
+```
+# cp bin/completion.bash /etc/bash_completion.d/alfons
+```
+
+## Zsh
+
+Zsh will autocomplete tasks, task options, and for certain task options, also suggest values.
+
+If a task option has a value of `<file>`, `<user>`, `<group>` or `<path>`, it will use Zsh's internal resolvers to complete suggestions.
+
+### Installing
+
+Move the completion file to anywhere in your `$FPATH`.
+
+```sh
+# Oh my Zsh!
+$ cp bin/completion.zsh $HOME/.oh-my-zsh/completions/_alfons
+# Hopefully cross platform
+$ sudo cp bin/completion.zsh /usr/share/zsh/functions/Completion/_alfons
+```

docs/documenting.md

@@ -0,0 +1,28 @@
+# Documenting
+
+In Alfons 5.2, a new feature was implemented to document your own Taskfiles. Previously, there was no way to generate a help message, or to have shell completion. Thanks to the docstrings, and a little bit of magic, this is now possible.
+
+## Docstrings
+
+Docstrings are comments in the Taskfile that begin with `---`. These are followed by a tag (`@task`, `@argument`, `@flag`) that determines how the rest of the comment will be parsed.
+
+The docstrings are untied from the actual code since it needs to be language-agnostic, and there are many ways within a single language to define tasks. As such, the tasks displayed in the new help message are a mix between documented tasks, and undocumented tasks read from the Taskfile.
+
+## Declaring a task
+
+`--- @task name Description of the task.`
+
+A task is declared using the docstring above.
+
+## Declaring an option for a task
+
+`--- @option task [long s] <value> Description of the option.`
+
+The docstring above has several parts. First, the name of the task that you are referencing. Then, between square brackets, you have to put all the forms of the option, the long preferrably first. Between the angle brackets, you can put each of the expected values. Everything that comes afterward is the description of the option.
+
+## Flagging
+
+`--- @flag * hide`
+`--- @flag task hide`
+
+As of right now, the only flag available is `hide`, which makes either all tasks (`*`) or a task invisible to autocompletion and the help message.