just/GRAMMAR.md

131 lines
3.5 KiB
Markdown
Raw Permalink Normal View History

2016-10-30 19:15:35 -07:00
justfile grammar
2016-10-30 19:16:33 -07:00
================
2016-10-30 19:15:35 -07:00
2016-10-30 19:40:11 -07:00
Justfiles are processed by a mildly context-sensitive tokenizer
and a recursive descent parser. The grammar is LL(k), for an
unknown but hopefully reasonable value of k.
2016-10-30 19:15:35 -07:00
tokens
2016-10-30 19:16:33 -07:00
------
2016-10-30 19:15:35 -07:00
```
BACKTICK = `[^`]*`
INDENTED_BACKTICK = ```[^(```)]*```
COMMENT = #([^!].*)?$
DEDENT = emitted when indentation decreases
EOF = emitted at the end of the file
INDENT = emitted when indentation increases
LINE = emitted before a recipe line
NAME = [a-zA-Z_][a-zA-Z0-9_-]*
NEWLINE = \n|\r\n
RAW_STRING = '[^']*'
INDENTED_RAW_STRING = '''[^(''')]*'''
STRING = "[^"]*" # also processes \n \r \t \" \\ escapes
INDENTED_STRING = """[^("""]*""" # also processes \n \r \t \" \\ escapes
LINE_PREFIX = @-|-@|@|-
TEXT = recipe text, only matches in a recipe body
2017-11-30 08:44:06 -08:00
```
grammar syntax
--------------
```
| alternation
() grouping
_? option (0 or 1 times)
_* repetition (0 or more times)
_+ repetition (1 or more times)
2016-10-30 19:15:35 -07:00
```
grammar
2016-10-30 19:16:33 -07:00
-------
2016-10-30 19:15:35 -07:00
```
justfile : item* EOF
2023-12-29 12:16:31 -08:00
item : alias
2016-10-30 19:15:35 -07:00
| assignment
2023-12-29 12:16:31 -08:00
| eol
2016-10-30 19:15:35 -07:00
| export
2023-12-29 12:16:31 -08:00
| import
| module
| recipe
| setting
2016-10-30 19:15:35 -07:00
eol : NEWLINE
| COMMENT NEWLINE
alias : 'alias' NAME ':=' NAME
2016-10-30 19:15:35 -07:00
assignment : NAME ':=' expression eol
2019-04-11 12:57:19 -07:00
2016-10-30 19:15:35 -07:00
export : 'export' assignment
2022-10-25 16:57:20 -07:00
setting : 'set' 'allow-duplicate-recipes' boolean?
| 'set' 'allow-duplicate-variables' boolean?
| 'set' 'dotenv-filename' ':=' string
2022-10-25 16:57:20 -07:00
| 'set' 'dotenv-load' boolean?
| 'set' 'dotenv-path' ':=' string
| 'set' 'export' boolean?
| 'set' 'fallback' boolean?
2022-10-25 16:57:20 -07:00
| 'set' 'ignore-comments' boolean?
| 'set' 'positional-arguments' boolean?
| 'set' 'quiet' boolean?
| 'set' 'shell' ':=' '[' string (',' string)* ','? ']'
2023-10-11 21:24:37 -07:00
| 'set' 'tempdir ':=' string
2022-10-25 16:57:20 -07:00
| 'set' 'windows-powershell' boolean?
2022-08-28 22:26:02 -07:00
| 'set' 'windows-shell' ':=' '[' string (',' string)* ','? ']'
2023-12-29 12:16:31 -08:00
import : 'import' '?'? string?
module : 'mod' '?'? NAME string?
boolean : ':=' ('true' | 'false')
2021-05-15 12:10:30 -07:00
expression : 'if' condition '{' expression '}' 'else' '{' expression '}'
2024-05-14 18:55:32 -07:00
| 'assert' '(' condition ',' expression ')'
2022-06-25 02:39:06 -07:00
| value '/' expression
| value '+' expression
2017-11-30 08:44:06 -08:00
| value
condition : expression '==' expression
| expression '!=' expression
value : NAME '(' sequence? ')'
| BACKTICK
| INDENTED_BACKTICK
| NAME
| string
| '(' expression ')'
string : 'x'? STRING
| 'x'? INDENTED_STRING
| 'x'? RAW_STRING
| 'x'? INDENTED_RAW_STRING
sequence : expression ',' sequence
| expression ','?
2016-10-30 19:15:35 -07:00
recipe : attributes* '@'? NAME parameter* variadic? ':' dependency* body?
attributes : '[' attribute* ']' eol
attribute : NAME ( '(' string ')' )?
2016-10-30 19:15:35 -07:00
parameter : '$'? NAME
2021-05-26 16:08:05 -07:00
| '$'? NAME '=' value
2016-10-30 19:15:35 -07:00
variadic : '*' parameter
| '+' parameter
dependency : NAME
| '(' NAME expression* ')'
2016-10-30 19:15:35 -07:00
body : INDENT line+ DEDENT
line : LINE LINE_PREFIX? (TEXT | interpolation)+ NEWLINE
| NEWLINE
2016-10-30 19:15:35 -07:00
interpolation : '{{' expression '}}'
```