Write, save and run scripts in multiple languages from a single source file.
Allows for a granular one-run project generation and transformation.
For smoother development of related code, to keep the source about as closely collocated as possible, or for learning by coding comparatively across languages.
By 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.
Create 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.
As 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:
- first, the file extension for that language, or the full output filename including extension, or the full output path including directory and extension
- 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
For example, a possible tag line with both of these elements and the corresponding script in Elixir:
### exs elixir -r setup
IO.puts("Up and running...")
This 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.
For alternatives to this tag line content, see There's more... below.
For a source file template and a means of appending scripts written in other files via the command line, see Options.
If aliesce is compiled and ready to go (see Getting started below), run the aliesce command, adding the source file path if not the default.
For example, for a source file named only 'src':
aliesce srcThe script files are saved and run in order of appearance in the source file.
The 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 below).
For an output file named 'script.exs', the following would be used:
### script.exs elixir -r setup
For an output directory named 'elixir' holding 'script.exs':
### elixir/script.exs elixir -r setup
For a subdirectory within the default or overridden output directory, a placeholder can be used, by default >. 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:
### >/elixir/script.exs elixir -r setup
For 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 ><. 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":
### exs elixir -r setup >< | sort
The 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':
### exs elixir -r >1< >< | sort
To 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:
### ! script.exs elixir -r setup
To 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:
### script.exs ! elixir -r setup
Alternatively, a specific subset of scripts can be included (see Options below), to avoid the need to add tag line elements to others.
To add a label to a script, include it after the tag head and follow it with the tag tail, which is # by default:
### script label # script.exs elixir -r setup
Spacing between tag head and tail is retained for list entries (see Options below).
The following can be passed to aliesce before any source file path:
--dest/-dDIRNAME, to set the default output dirname ('scripts') toDIRNAME--list/-l, to print for each script in the source (def. 'src.txt') its number and tag line content, without saving or running--only/-oSUBSET, to include only the scripts the numbers of which appear inSUBSET, comma-separated and/or as ranges, e.g.-o 1,3-5--push/-pLINEPATH, to append to the source (def. 'src.txt')LINE, adding the tag head if none, followed by the content atPATHthen exit--edit/-eNLINE, to update the tag line for script number N to LINE, adding the tag head if none, then exit--init/-i, to add a source at the default path ('src.txt') then exit--version/-v, to show name and version number then exit--help/-h, to show usage, flags available and notes then exit
Any 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.
Arguments 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.
Arguments 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.
This is similar to the use of the source file directly via hashbang, described in Getting started below.
One 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.
The 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 below).
The default temporary test directory is defined close to the top of the test module, also in the project source file.
With 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.
The 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'.
A 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 above), it may be possible to use the env binary with its split string option, e.g. #!/bin/env -S aliesce <flag>[ ...]. This inclusion of flags is similar to the approach described in Provision in-file above.
Running the tests after making changes and adding tests to cover new behaviour is recommended.
The tests can be run with the following command:
cargo test -- --test-threads=1For the purpose of testing a subset of CLI options a temporary test directory is created (see Defaults above). The flag setting thread count ensures that the test cases are run in series, allowing for setup and teardown.
The tests themselves are in the test module at the base of the file.
The 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.
- add source file variables available to tag line and script:
- passed to aliesce via CLI
- declared in file, including from the environment
- for defaults
- extend and/or revise the set of placeholders for:
- all default path parts
- use across save path and command
- provide tag line options for:
- multiple save paths
- auxiliary commands
- provide or extend CLI options for:
- output verbosity
- applying a single stage
- listing save paths
- importing a script to an arbitrary position
- interaction with existing scripts:
- reordering
- deleting
- refactor as more idiomatic
- improve error handling
- extend test module