Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add more examples for toml tasks #3491

Merged
merged 10 commits into from
Dec 12, 2024
Merged

docs: Add more examples for toml tasks #3491

Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b4523cc
docs: Add more examples for toml tasks
hverlin Dec 12, 2024
c70356d
update
hverlin Dec 12, 2024
1a2236b
[autofix.ci] apply automated fixes
autofix-ci[bot] Dec 12, 2024
4f72f90
fix
hverlin Dec 12, 2024
4402938
update
hverlin Dec 12, 2024
d3e43f7
update
hverlin Dec 12, 2024
3503311
[autofix.ci] apply automated fixes
autofix-ci[bot] Dec 12, 2024
8b8e6ea
code group
hverlin Dec 12, 2024
ac1d845
wip
hverlin Dec 12, 2024
6685c06
[autofix.ci] apply automated fixes
autofix-ci[bot] Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 51 additions & 3 deletions docs/tasks/toml-tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,6 @@ dir = "{{cwd}}" # run in user's cwd, default is the project's base directory
[tasks.lint]
description = 'Lint with clippy'
env = { RUST_BACKTRACE = '1' } # env vars for the script
# specify a shell command to run the script with (default is 'sh -c')
shell = 'bash -c'
# you can specify a multiline script instead of individual commands
run = """
#!/usr/bin/env bash
Expand Down Expand Up @@ -134,7 +132,7 @@ run = 'cargo test {{option(name="file")}}'
Flags are like options except they don't take values. They are defined in scripts with <span v-pre>
`{{flag()}}`</span>.

Example:
Examples:

```toml
[tasks.echo]
Expand All @@ -143,10 +141,60 @@ run = 'echo {{flag(name=("myflag")}}'
# runs: echo true
```

```toml
[tasks.maybeClean]
run = """if [ '{{flag(name='clean')}}' = 'true' ]; then echo 'cleaning' ; fi""",
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

seems like a missed opportunity to show how multiline strings work in toml. The comma at the end is also a syntax error

# execute: mise run maybeClean --clean
# runs: echo cleaning
```

- `name`: The name of the flag. This is used for help/error messages.

The value will be `true` if the flag is passed, and `false` otherwise.

## Shell

You can specify a shell command to run the script with (default is `sh -c`).

```toml
[tasks.lint]
shell = 'bash -c'
run = "cargo clippy"
```

Here is another example with `deno`:

```toml
[tools]
deno = 'latest'

[tasks.download_task]
description = "Shows that you can use deno in a task"
shell = 'deno eval'
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while this works, it can also be done with a shebang:

run = """
#!/usr/bin/env -S deno run --allow-env
"""

which I prefer even though users need to understand env -S (which I don't see as a downside, env -S is great). I think we should show both methods.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know this for sure, but I suspect a shebang would also be easier for IDEs to syntax highlight, so I think that should be our preferred method here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking that this solution is more portable, maybe? Need to try on windows to see what happens.

I am not sure if it makes a diff for syntax highlighting for languages that don't have # comments
image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah wait, this is mise parsing the script actually, so it should work on window then.

mise/src/task/task_script_parser.rs

Lines 312 to 314 in d5781be

let shell_type: Option<ShellType> = shell_from_shebang(script)
.or(task.shell())
.unwrap_or(SETTINGS.default_inline_shell()?)[0]

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that is only partially done, the shell_type there is only used for knowing whether or not it should escape args but I plan to soon make it actually parse and execute the shebang directly instead of going through sh -c. I would still document it this way, the windows issue I'll fix soon.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if only I knew the mise-vscode maintainer ;)

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do think syntax highlighting with shebangs would be a killer feature, or even if you got it to default to multiline strings as bash

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

btw we should add your extension to the docs

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I will make a PR next week. Want to check the windows support first

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be worth waiting until I get the shebang parsing fully in place—right now it almost certainly will fail with any shebang—though a user could work around that with run_windows

run = """
import ProgressBar from "jsr:@deno-library/progress";
import { delay } from "jsr:@std/async";

if (!confirm('Start download?')) {
Deno.exit(1);
}

const progress = new ProgressBar({ title: "downloading:", total: 100 });
let completed = 0;
async function download() {
while (completed <= 100) {
await progress.render(completed++);
await delay(10);
}
}
await download();
"""
# ❯ mise run download_task
# [download_task] $ import ProgressBar from "jsr:@deno-library/progress";
# Start download? [y/N] y
# downloading: ...
```

## Windows

You can specify an alternate command to run on Windows by using the `run_windows` key:
Expand Down
Loading