{"id":23219636,"url":"https://github.com/barcek/aliesce","last_synced_at":"2025-10-27T19:08:22.518Z","repository":{"id":41188755,"uuid":"458212030","full_name":"barcek/aliesce","owner":"barcek","description":"min dev | multilingual source file processing | command-line tool | Rust (std only)","archived":false,"fork":false,"pushed_at":"2025-01-09T13:01:45.000Z","size":133,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T15:12:03.606Z","etag":null,"topics":["automation","build-management","cicd","command-line-tool","dx","polyglot-programming","rust","scripting","single-source"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barcek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-02-11T14:09:02.000Z","updated_at":"2025-01-14T12:51:27.000Z","dependencies_parsed_at":"2024-08-02T21:28:42.860Z","dependency_job_id":"98407c1f-d199-4540-bf3b-9a47465943ee","html_url":"https://github.com/barcek/aliesce","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/barcek/aliesce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Faliesce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Faliesce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Faliesce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Faliesce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barcek","download_url":"https://codeload.github.com/barcek/aliesce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Faliesce/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265443569,"owners_count":23766417,"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":["automation","build-management","cicd","command-line-tool","dx","polyglot-programming","rust","scripting","single-source"],"created_at":"2024-12-18T21:36:12.349Z","updated_at":"2025-10-27T19:08:22.414Z","avatar_url":"https://github.com/barcek.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aliesce\n\nWrite, save and run scripts in multiple languages from a single source file.\n\nAllows for a granular one-run project generation and transformation.\n\n- [Why?](#why)\n- [How?](#how)\n  - [Source file setup](#source-file-setup)\n  - [Running aliesce](#running-aliesce)\n  - [There's more...](#theres-more)\n    - [Specifying paths](#specifying-paths)\n    - [Extending commands](#extending-commands)\n    - [Avoiding stages](#avoiding-stages)\n    - [Labelling scripts](#labelling-scripts)\n- [Options](#options)\n  - [Provision in-file](#provision-in-file)\n- [Streams](#streams)\n- [Defaults](#defaults)\n- [Getting started](#getting-started)\n- [Making changes](#making-changes)\n  - [Tests](#tests)\n- [Development plan](#development-plan)\n\n## Why?\n\nFor smoother development of related code, to keep the source about as closely collocated as possible, or for learning by coding comparatively across languages.\n\n## How?\n\nBy preceding each script in the source file with a single line, called a tag line, which can hold values used to save and run the script. These values might be the output file extension and the name of the executable. For example, `### exs elixir` could be the tag line to save and run a simple Elixir script.\n\n### Source file setup\n\nCreate a file to hold the scripts. Give it any name, and any file extension or none. Use the current default name - 'src.txt' - to avoid passing an argument later.\n\nAs you add each script to the file, insert above it a tag line starting by default with `###`. A tag line might include the following elements separated by one or more spaces:\n\n- first, the file extension for that language, or the full output filename including extension, or the full output path including directory and extension\n- next, the command to be run, if any, e.g. the program to be used to run the file as well as any arguments to pass to that program - note that the path to the output file is added as the final argument by default\n\nFor example, a possible tag line with both of these elements and the corresponding script in Elixir:\n\n```\n### exs elixir -r setup\n\nIO.puts(\"Up and running...\")\n```\n\nThis tells aliesce to save the script below the tag line in a file with the `exs` extension, then run that file with the `elixir` command, applying one option, to require a file named 'setup'. For convenience, this required file could be generated as part of the same run from an earlier script in the source.\n\nFor alternatives to this tag line content, see [There's more...](#theres-more) below.\n\nFor a source file template and a means of appending scripts written in other files via the command line, see [Options](#options).\n\n### Running aliesce\n\nIf aliesce is compiled and ready to go (see [Getting started](#getting-started) below), run the `aliesce` command, adding the source file path if not the default.\n\nFor example, for a source file named only 'src':\n\n```shell\naliesce src\n```\n\nThe script files are saved and run in order of appearance in the source file.\n\n### There's more...\n\n#### Specifying paths\n\nThe stem of the output filename will be the stem of the source filename, i.e. 'src' by default. The file is saved by default to a folder in the current directory named `scripts`, which is created if not present. This default directory can be overridden via the command line (see [Options](#options) below).\n\nFor an output file named 'script.exs', the following would be used:\n\n```\n### script.exs elixir -r setup\n```\n\nFor an output directory named 'elixir' holding 'script.exs':\n\n```\n### elixir/script.exs elixir -r setup\n```\n\nFor a subdirectory within the default or overridden output directory, a placeholder can be used, by default `\u003e`. For an output path of 'scripts/elixir/script.exs', i.e. with the default output directory name and the subdirectory and script named as above:\n\n```\n### \u003e/elixir/script.exs elixir -r setup\n```\n\n#### Extending commands\n\nFor a command in which the path to the file is not the last argument, e.g. when piping to another program, a placeholder can be used, by default `\u003e\u003c`. The whole is then run by the default program-flag pair `bash -c`. For a command of `bash -c \"elixir -r setup scripts/src.exs | sort\"`:\n\n```\n### exs elixir -r setup \u003e\u003c | sort\n```\n\nThe output path of a different script can be selected by using its number in the placeholder. For the output path of script no. 1, rather than the fixed 'setup':\n\n```\n### exs elixir -r \u003e1\u003c \u003e\u003c | sort\n```\n\n#### Avoiding stages\n\nTo avoid a script being saved and run, simply include the `!` signal as a tag line element, before the extension or full output filename or path:\n\n```\n### ! script.exs elixir -r setup\n```\n\nTo save the script but avoid the run stage, include the `!` signal as an element after the extension or full output filename or path but before the command to run the code:\n\n```\n### script.exs ! elixir -r setup\n```\n\nAlternatively, a specific subset of scripts can be included (see [Options](#options) below), to avoid the need to add tag line elements to others.\n\n#### Labelling scripts\n\nTo add a label to a script, include it after the tag head and follow it with the tag tail, which is `#` by default:\n\n```\n### script label # script.exs elixir -r setup\n```\n\nSpacing between tag head and tail is retained for list entries (see [Options](#options) below).\n\n## Options\n\nThe following can be passed to `aliesce` before any source file path:\n\n- `--dest` / `-d`  `DIRNAME`, to set the default output dirname ('scripts') to `DIRNAME`\n- `--list` / `-l`, to print for each script in the source (def. 'src.txt') its number and tag line content, without saving or running\n- `--only` / `-o`  `SUBSET`, to include only the scripts the numbers of which appear in `SUBSET`, comma-separated and/or as ranges, e.g. `-o 1,3-5`\n- `--push` / `-p`  `LINE` `PATH`, to append to the source (def. 'src.txt') `LINE`, adding the tag head if none, followed by the content at `PATH` then exit\n- `--edit` / `-e`  `N` `LINE`, to update the tag line for script number N to LINE, adding the tag head if none, then exit\n- `--init` / `-i`, to create a source (def. 'src.txt') then exit\n- `--version` / `-v`, to show name and version number then exit\n- `--help` / `-h`, to show usage, flags available and notes then exit\n\n### Provision in-file\n\nAny or all of the options above can also be selected by providing their arguments in the source file itself, avoiding the need to list them with each use of the `aliesce` command.\n\nArguments provided in-file are simply placed above the initial tag line, arranged in the usual order, whether on a single line or multiple. They are processed each time the file is handled by aliesce.\n\nArguments passed directly on the command line are processed first, followed by those in the file, with the latter overriding the former in the event that an option is selected using both approaches.\n\nThis is similar to the use of the source file directly via hashbang, described in [Getting started](#getting-started) below.\n\n## Streams\n\nOne or more paths can be piped to `aliesce` to append the content at each to the source file as a script, auto-preceded by a tag line including the `!` signal, then exit.\n\n## Defaults\n\nThe default core path, tag, signal, placeholder and command values are defined close to the top of the project source file, i.e. 'src/main.rs', should you prefer to modify any pre-compilation (see [Getting started](#getting-started) below).\n\nThe default temporary test directory is defined close to the top of the test module, also in the project source file.\n\n## Getting started\n\nWith Rust and Cargo installed, at the root of the aliesce directory run `cargo build --release` to compile. The binary is created in the 'target/release' directory.\n\nThe binary can be run with the command `./aliesce` while in the same directory, and from elsewhere using the pattern `path/to/aliesce`. It can be run from any directory with `aliesce` by placing it in a directory listed in `$PATH`, presumably '/bin' or '/usr/bin'.\n\nA source file can be used directly by adding to the top of the file a hashbang with the path to the aliesce binary, e.g. `#!/usr/bin/aliesce`. If flags are to be passed (see [Options](#options) above), it may be possible to use the `env` binary with its split string option, e.g. `#!/bin/env -S aliesce \u003cflag\u003e[ ...]`. This inclusion of flags is similar to the approach described in [Provision in-file](#provision-in-file) above.\n\n## Making changes\n\nRunning the tests after making changes and adding tests to cover new behaviour is recommended.\n\n### Tests\n\nThe tests can be run with the following command:\n\n```shell\ncargo test -- --test-threads=1\n```\n\nFor the purpose of testing a subset of CLI options a temporary test directory is created (see [Defaults](#defaults) above). The flag setting thread count ensures that the test cases are run in series, allowing for setup and teardown.\n\nThe tests themselves are in the test module at the base of the file.\n\n## Development plan\n\nThe following are the expected next steps in the development of the code base. The general medium-term aim is a convenient parallel scripting tool. Pull requests are welcome for these and other potential improvements.\n\n- add source file variables available to tag line and script:\n  - passed to aliesce via CLI\n  - declared in file, including from the environment\n  - for defaults\n- extend and/or revise the set of placeholders for:\n  - all default path parts\n  - use across save path and command\n- provide tag line options for:\n  - multiple save paths\n  - auxiliary commands\n- provide or extend CLI options for:\n  - output verbosity\n  - applying a single stage\n  - listing save paths\n  - importing a script to an arbitrary position\n  - interaction with existing scripts:\n    - reordering\n    - deleting\n- refactor as more idiomatic\n- improve error handling\n- extend test module\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarcek%2Faliesce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarcek%2Faliesce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarcek%2Faliesce/lists"}