{"id":20668074,"url":"https://github.com/daelvn/alfons","last_synced_at":"2025-04-19T17:10:07.016Z","repository":{"id":54596848,"uuid":"157604325","full_name":"daelvn/alfons","owner":"daelvn","description":"🚀 Task runner for Lua and MoonScript.","archived":false,"fork":false,"pushed_at":"2024-10-19T21:18:08.000Z","size":725,"stargazers_count":26,"open_issues_count":9,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T10:43:16.467Z","etag":null,"topics":["build-tool","lua","moonscript","task-runner","taskfiles"],"latest_commit_sha":null,"homepage":"","language":"MoonScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daelvn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-14T20:05:19.000Z","updated_at":"2025-02-13T09:01:47.000Z","dependencies_parsed_at":"2024-08-09T11:54:08.019Z","dependency_job_id":null,"html_url":"https://github.com/daelvn/alfons","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daelvn%2Falfons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daelvn%2Falfons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daelvn%2Falfons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daelvn%2Falfons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daelvn","download_url":"https://codeload.github.com/daelvn/alfons/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249746041,"owners_count":21319581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-tool","lua","moonscript","task-runner","taskfiles"],"created_at":"2024-11-16T19:47:32.958Z","updated_at":"2025-04-19T17:10:06.999Z","avatar_url":"https://github.com/daelvn.png","language":"MoonScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alfons 5\n\n\u003ca href=\"https://discord.gg/3KGDznrEjC\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=discord\u0026message=chat\u0026color=brightgreen\u0026style=flat-square\"\u003e\u003c/a\u003e\n![GitHub stars](https://img.shields.io/github/stars/daelvn/alfons?style=flat-square)\n![GitHub tag (latest SemVer pre-release)](https://img.shields.io/github/v/tag/daelvn/alfons?include_prereleases\u0026label=release\u0026style=flat-square)\n![LuaRocks](https://img.shields.io/luarocks/v/daelvn/alfons?style=flat-square)\n\n\u003cimg align=\"left\" width=\"128\" height=\"128\" src=\".github/alfons-logo.svg\"\u003e\n\u003c!-- \u003cimg src=\".github/alfons-banner.png\"\u003e --\u003e\n\n\u003e Alfons 5 is a rewrite of the original Alfons, written to be much more modular and usable. For the old Alfons 3, see the [`three`](https://github.com/daelvn/alfons/tree/three) GitHub branch.\n\nAlfons 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.\n\n\u003e [!TIP]\n\u003e Check out the 5.2 update!\n\u003e Shell autocompletions, help messages, Taskfile documentations and extra environment functions have been added.\n\n## Table of contents\n\n- [Alfons 5](#alfons-5)\n  - [Table of contents](#table-of-contents)\n  - [Changelog](#changelog)\n    - [5.3](#53)\n    - [5.2](#52)\n    - [5](#5)\n    - [4.4](#44)\n    - [4.3](#43)\n    - [4.2](#42)\n    - [4.1](#41)\n  - [Usage](#usage)\n    - [Defining tasks](#defining-tasks)\n    - [Calling tasks](#calling-tasks)\n    - [Arguments](#arguments)\n    - [Migrating from Alfons 3](#migrating-from-alfons-3)\n      - [Missing functions](#missing-functions)\n      - [Importable tasks](#importable-tasks)\n  - [Installing](#installing)\n    - [Extra features](#extra-features)\n  - [Projects using Alfons](#projects-using-alfons)\n  - [License](#license)\n  - [Goodbye?](#goodbye)\n\n## Changelog\n\n### 5.3\n\n- **5.3.1** (02.09.2024) Fixed argument parser bug. `alfons --a --b` is now `a = true; b = true` instead of `a = \"--b\"`.\n- **5.3** (09.08.2024) Added [Yuescript](https://yuescript.org) support. Added a few functions.\n\n- **Yuescript support.** You can now use `Alfons.yue` files (or any taskfile that ends in `.yue`) to load in Yuescript tasks.\n- **Additions to the environment.**\n  - `values`: Get the values of a table as an array\n  - `entries`: Turns a table into an array of key-value tuples\n  - `fromEntries`: Reverses the process of `entries`\n\n### 5.2\n\n- **5.2.2** (09.08.2024) Fixed the `reduce` implementation\n- **5.2** (08.06.2024) Implemented Taskfile documentation, help messages and autocompletion\n\n- **Taskfile documentation.** You can now document your Taskfiles for automatic help messages and shell completion.\n  - Check [the documentation](docs/documenting.md) for more info.\n- **Help messages.** You can now display a help message with `--help`, or even get help for a specific task with `--help [task]`.\n  - This help message can be automatically generated from the detected tasks in the Taskfile.\n  - It works best when you document your Taskfile, so you can add descriptions and options.\n- **Shell autocompletion.** Shell autocompletion is now available in Zsh, Bash and Fish flavors.\n  - The Zsh and Fish flavors are by far the most complete, since Zsh's and Fish's completion systems are slightly more capable.\n  - Bash is only able to list tasks, and sometimes options or flags for those tasks. Use Zsh.\n  - Check [the documentation](docs/autocompletion.md) for more info and install instructions.\n- **Additions to the environment.**\n  - `lines`: Split a string into lines\n  - `split`: Split any string by any pattern\n  - `sanitize`: Neutralizes pattern magic characters in strings\n  - `keys`: Get the keys of a table as an array\n  - `slice`: Creates a slice of an array\n  - `map`, `reduce`, `filter` do to arrays what you would expect\n  - `contains` has been rewritten\n\n### 5\n\n- **5.0.2** (23.01.2023) Rolled back test mode\n- **5.0.1** (23.01.2023) Fixed rockspec dependencies\n- **5.0** (23.01.2023) Switched out [filekit](https://github.com/daelvn/filekit) in favor of [lpath](https://github.com/starwing/lpath).\n\nI am back to life and filekit errored on me. Filekit is terribly inefficient anyway and I don't know why I ever made it. Now I am using an actually good filesystem library. It's a breaking change, though.\n\n- **Compatibility with ComputerCraft has been removed.** Alfons 5 is not compatible with it.\n- **Replaced filekit with lpath**\n  - `fs` in the environment no longer points to `filekit`, but to `path.fs`\n  - `path`, `fsinfo` and `env` have been added to the environment, corresponding to `path`, `path.info` and `path.env` respectively.\n- Additions to the environment\n  - `safeOpen`: Open IO handles safely\n  - `listAll`: Returns a list of all files and directories recursively.\n  - `copy`: Recursive file copy\n  - `delete`: Recursive delete\n  - `isEmpty`: Checks if a directory is empty\n- Changes to the environment\n  - All FS operations don't deal in absolute paths anymore\n  - `wildcard` and `iwildcard` may exhibit slightly different behavior.\n\n### 4.4\n\n- **4.4** (04.02.2021) Added [`exists`](docs/environment.md) and **Experimental Teal Support**.\n\nSome critical bugs in the loading of taskfiles and the invocation of tasks have been fixed.\n\n### 4.3\n\n- **4.3** (26.01.2021) Added [`calls`](docs/arguments.md#calls) and [`npairs`](docs/provide.md#npairs).\n\n### 4.2\n\n- **4.2** (02.10.2020) Internal overhaul.\n\nAlfons 4.2 changes the whole way that Alfons works on the inside. Please refer to [Loading](docs/loading.md) and [API](docs/api.md) for the most notable work.\n\n### 4.1\n\n- **4.1.4** (12.09.2020) - Bugfix on `default` task.\n- **4.1.3** (11.09.2020) - Funny Homestuck Number update. Fix `inotify` dependency.\n- **4.1.2** (29.08.2020) - More bugfixes\n- **4.1.1** (27.08.2020) - Bugfixes\n- **4.1** (27.08.2020) - Added [`uses`](docs/arguments.md)\n\n## Usage\n\nRun `alfons` in a directory with an `Alfons.lua` or `Alfons.moon` file. Using MoonScript (obviously) requires installing MoonScript via LuaRocks.\n\nTo see the documentation, check out the [`docs/`](docs/) folder of this repo.\n\nTo get started using Alfons, check out the [Tutorial](docs/tutorial.md) or the [Recipes](docs/recipes.md).\n\n### Defining tasks\n\nTasks are obtained by either returning a table `{tasks={}}` where the empty table is a list of named functions, or by exporting globals. The preferred mode for Lua is exporting globals, and the preferred mode for MoonScript is returning a table, although both work in both languages.\n\n**Lua:**\n\n```lua\n-- Exporting globals\nfunction always(self) print(self.name) end\n-- Returning table\nreturn { tasks = {\n  always = function(self) print(self.name) end\n}}\n```\n\n**MoonScript**\n\n```moon\n-- Exporting globals\nexport always ==\u003e print @name\n-- Returning table\ntasks:\n  always: =\u003e @name\n```\n\n### Calling tasks\n\nFrom the command line, simply pass the name of the task you wish to run. Alternatively, use `tasks.TASK` to call `TASK` if it's loaded.\n\n**Lua:**\n\n```lua\nfunction test (self)\n  print(\"I am \" .. self.name .. \" and \" .. self.caller .. \" called me.\")\nend\n\nfunction call (self)\n  tasks.test{caller = self.name}\nend\n```\n\n**MoonScript:**\n\n```moon\ntasks:\n  test: =\u003e print \"I am #{@name} and #{@caller} called me.\"\n  call: =\u003e tasks.test caller: @name\n```\n\n### Arguments\n\nArguments are passed in the `self` table of every function, which contains a field called `name` which is, well, uh, its own name. You can also use the `args` table to see the whole tree of arguments. Feel free to play with and abuse this!\n\n### Migrating from Alfons 3\n\nSome functions are either not implemented or not yet ported.\n\n#### Missing functions\n\n`moonc`, `git`, `clone` and `toflags` do not exist anymore. The first three may be implemented at a later time, and the last won't be implemented due to the changes in Alfons' argument system. For now, you will have to use their command-line counterparts, so `moonc file` becomes `sh \"moonc #{file}\"` and such.\n\n#### Importable tasks\n\n`fetch`/`fetchs` is now just `fetch`, and `ms-compile` has been removed and will probably not come back. Write a compile task manually. This should work as a dropin replacement:\n\n**Lua:**\n\n```lua\ncompile = function()\n  for file in wildcard \"**.moon\" do sh \"moonc \".. file end\nend\n```\n\n**MoonScript:**\n\n```moon\ncompile: =\u003e sh \"moonc #{file}\" for file in wildcard \"**.moon\"\n```\n\n## Installing\n\n~~Since this is not upstream yet, you can't install through the LuaRocks server. However, you can install Alfons using itself.~~\n\nAlfons 4 is now available on LuaRocks!\n\n```sh\n$ luarocks install alfons\n```\n\n### Extra features\n\nThe preincluded task `fetch` depends on [lua-http](https://github.com/daurnimator/lua-http) to be used. The `watch` function depends on [linotify](https://github.com/hoelzro/linotify) and will not work on platforms other than Linux.\n\n```sh\n$ luarocks install http     # lua-http\n$ luarocks install inotify  # linotify\n```\n\n## Projects using Alfons\n\n- [Moonbuild](https://github.com/natnat-mc/moonbuild) by the one and only [Codinget](https://github.com/natnat-mc)\n- [awlua](https://github.com/Le0Developer/awluas) by [Le0Developer](https://github.com/Le0Developer)\n- [VNDS-LOVE](https://github.com/ajusa/VNDS-LOVE) by [ajusa](https://github.com/ajusa)\n\nThanks for using the project \\\u003c3.\n\n## License\n\nThrowing it to the public domain. Check out the [license](https://github.com/daelvn/alfons/blob/rewrite/LICENSE.md).\n\n## Goodbye?\n\ngoodbye.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaelvn%2Falfons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaelvn%2Falfons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaelvn%2Falfons/lists"}