diff --git a/.github/workflows/check.yaml b/.github/workflows/check.yaml new file mode 100644 index 0000000..4267959 --- /dev/null +++ b/.github/workflows/check.yaml @@ -0,0 +1,27 @@ +name: check + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + check: + runs-on: ubuntu-latest + + strategy: + matrix: + deno-version: [canary] + + steps: + - uses: actions/checkout@v2 + + - uses: denoland/setup-deno@v1 + with: + deno-version: ${{ matrix.deno-version }} + + - run: deno task lint && git diff --exit-code + - run: deno task fmt && git diff --exit-code + - run: deno task generate && git diff --exit-code + - run: deno task udd && git diff --exit-code diff --git a/cli/help.ts b/cli/help.ts index 5c9fc44..96693aa 100644 --- a/cli/help.ts +++ b/cli/help.ts @@ -1,100 +1,100 @@ -/** - * HELP is the help text for the generate command. - */ -export const HELP = - `Automate code generation by running procedures defined in comment annotations. - -Usage: - deno https://deno.land/x/generate/main.ts [...] [options] - -Options: - -n, --dry-run Print the commands that would be run without - actually running them. - -r, --run Select directives to run by matching against the - directive text as-is. - -s, --skip Select directives to skip by matching against the - directive text as-is. - -v, --verbose Print the module specifier and directive text of - each directive when running the corresponding - generator. - -x, --trace Print the commands as they are run. - -Examples: - deno-generate - deno-generate myfile1.ts - deno-generate myfile1.ts myfile2.ts - deno-generate myfile1.ts --dry-run - -Deno generate scans a module graph for directives, which are lines starting -with the comment: - - //deno:generate [arguments...] - -where command is the generator corresponding to an executable file that can be -run locally. To run, arguments are passed to the generator. The generator is run -from the directory containing the directive. - -Note: No space in between "//" and "deno:generate". - -The deno generate command does not parse the file, so lines that look like -directives in comments or strings will be treated as directives. - -The arguments to the directive are space-separated tokens or double-quoted -strings passed to the generator as arguments. Quoted strings are evaluated -before execution. - -To convey to humans and tools that code is generated, generated source files -should have a comment of the form: - - ^// Code generated .* DO NOT EDIT\.$ - -The line must appear before the first non-comment, non-blank line of the file. - -Deno generate sets several variables when running generators: - - $DENO_OS The operating system of the host running deno generate. - $DENO_MODULE The module specifier of the module containing the directive. - $DENO_LINE The line number of the directive within the file. - $DENO_CHARACTER The character number of the directive within the file. - $DENO_DIR The directory containing the file containing the directive. - $DOLLAR A dollar sign ($). This is useful for escaping the $ in shell commands. - Literature: https://go-review.googlesource.com/c/go/+/8091 - -A directive may define a command alias for the file: - - //deno:generate -command [arguments...] - -where, for the remainder of this source file, the command is replaced -by the arguments. This can be used to create aliases for long commands or to -define arguments that are common to multiple directives. For example: - - //deno:generate -command cat deno run --allow-read https://deno.land/std/examples/cat.ts - (...) - //deno:generate deno run ./generate_code.ts - -The -command directive may appear anywhere in the file, but it is usually placed -at the top of the file, before any directives that use it. - -The --run flag specifies a regular expression to select directives to run by -matching against the directive text as-is. The regular expression does not need -to match the entire text of the directive, but it must match at least one -character. The default is to run all directives. - -The --skip flag specifies a regular expression to select directives to skip by -matching against the directive text as-is. The regular expression does not need -to match the entire text of the directive, but it must match at least one -character. The default is to not skip any directives. - -The --dry-run flag (-n) prints the commands that would be run without actually -running them. - -The --verbose flag (-v) prints the module specifier and directive -text of each directive when running the corresponding generator. - -The --trace flag (-x) prints the commands as they are run. - -You can also combine these flags to modify deno generate's behavior in different -ways. For example, deno generate -n -v mod.ts will run generate in dry run mode -and print more detailed information about the commands that it would run, while -deno generate -v -x will run generate in verbose mode and print the commands -that it is running as it runs them.`; +/** + * HELP is the help text for the generate command. + */ +export const HELP = + `Automate code generation by running procedures defined in comment annotations. + +Usage: + deno https://deno.land/x/generate/main.ts [...] [options] + +Options: + -n, --dry-run Print the commands that would be run without + actually running them. + -r, --run Select directives to run by matching against the + directive text as-is. + -s, --skip Select directives to skip by matching against the + directive text as-is. + -v, --verbose Print the module specifier and directive text of + each directive when running the corresponding + generator. + -x, --trace Print the commands as they are run. + +Examples: + deno-generate + deno-generate myfile1.ts + deno-generate myfile1.ts myfile2.ts + deno-generate myfile1.ts --dry-run + +Deno generate scans a module graph for directives, which are lines starting +with the comment: + + //deno:generate [arguments...] + +where command is the generator corresponding to an executable file that can be +run locally. To run, arguments are passed to the generator. The generator is run +from the directory containing the directive. + +Note: No space in between "//" and "deno:generate". + +The deno generate command does not parse the file, so lines that look like +directives in comments or strings will be treated as directives. + +The arguments to the directive are space-separated tokens or double-quoted +strings passed to the generator as arguments. Quoted strings are evaluated +before execution. + +To convey to humans and tools that code is generated, generated source files +should have a comment of the form: + + ^// Code generated .* DO NOT EDIT\.$ + +The line must appear before the first non-comment, non-blank line of the file. + +Deno generate sets several variables when running generators: + + $DENO_OS The operating system of the host running deno generate. + $DENO_MODULE The module specifier of the module containing the directive. + $DENO_LINE The line number of the directive within the file. + $DENO_CHARACTER The character number of the directive within the file. + $DENO_DIR The directory containing the file containing the directive. + $DOLLAR A dollar sign ($). This is useful for escaping the $ in shell commands. + Literature: https://go-review.googlesource.com/c/go/+/8091 + +A directive may define a command alias for the file: + + //deno:generate -command [arguments...] + +where, for the remainder of this source file, the command is replaced +by the arguments. This can be used to create aliases for long commands or to +define arguments that are common to multiple directives. For example: + + //deno:generate -command cat deno run --allow-read https://deno.land/std/examples/cat.ts + (...) + //deno:generate deno run ./generate_code.ts + +The -command directive may appear anywhere in the file, but it is usually placed +at the top of the file, before any directives that use it. + +The --run flag specifies a regular expression to select directives to run by +matching against the directive text as-is. The regular expression does not need +to match the entire text of the directive, but it must match at least one +character. The default is to run all directives. + +The --skip flag specifies a regular expression to select directives to skip by +matching against the directive text as-is. The regular expression does not need +to match the entire text of the directive, but it must match at least one +character. The default is to not skip any directives. + +The --dry-run flag (-n) prints the commands that would be run without actually +running them. + +The --verbose flag (-v) prints the module specifier and directive +text of each directive when running the corresponding generator. + +The --trace flag (-x) prints the commands as they are run. + +You can also combine these flags to modify deno generate's behavior in different +ways. For example, deno generate -n -v mod.ts will run generate in dry run mode +and print more detailed information about the commands that it would run, while +deno generate -v -x will run generate in verbose mode and print the commands +that it is running as it runs them.`; diff --git a/deno.jsonc b/deno.jsonc index b67aee5..b3e597e 100644 --- a/deno.jsonc +++ b/deno.jsonc @@ -3,6 +3,8 @@ "tasks": { "lint": "deno lint", "fmt": "deno fmt", + "generate": "deno task generate:example-01", + "generate:example-01": "deno run -A cli/main.ts --verbose ./examples/with_generate_docs.ts", "udd": "deno run -r -A https://deno.land/x/udd/main.ts dev_deps.ts deps.ts && deno task lock", "lock": "deno cache --lock=deno.lock --lock-write dev_deps.ts deps.ts", "all": "deno task udd && deno task lint && deno task fmt"