ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity
jj/docs/templates.md

231 lines
7.2 KiB
Markdown
Raw Normal View History

docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
# Templates
Jujutsu supports a functional language to customize output of commands.
The language consists of literals, keywords, operators, functions, and
methods.
A couple of `jj` commands accept a template via `-T`/`--template` option.
## Keywords
Keywords represent objects of different types; the types are described in
templater: add special "self" variable to refer to top-level object This allows us to call alias function with the top-level object. For convenience, all self.<method>()s are available as keywords. I don't think we'll want to deprecate them. It would be tedious if we had to specify -T'self.commit_id()' instead of -Tcommit_id.
2024-02-22 09:57:29 +00:00
a follow-up section. In addition to context-specific keywords, the top-level
object can be referenced as `self`.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### Commit keywords
docs: move template keywords list to corresponding types I'm going to introduce the "self" variable, and it will make more sense to document keywords as methods of the self object type.
2024-02-22 11:35:07 +00:00
In `jj log`/`jj obslog` templates, all 0-argument methods of [the `Commit`
templater: add special "self" variable to refer to top-level object This allows us to call alias function with the top-level object. For convenience, all self.<method>()s are available as keywords. I don't think we'll want to deprecate them. It would be tedious if we had to specify -T'self.commit_id()' instead of -Tcommit_id.
2024-02-22 09:57:29 +00:00
type](#commit-type) are available as keywords. For example, `commit_id` is
equivalent to `self.commit_id()`.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### Operation keywords
docs: move template keywords list to corresponding types I'm going to introduce the "self" variable, and it will make more sense to document keywords as methods of the self object type.
2024-02-22 11:35:07 +00:00
In `jj op log` templates, all 0-argument methods of [the `Operation`
templater: add special "self" variable to refer to top-level object This allows us to call alias function with the top-level object. For convenience, all self.<method>()s are available as keywords. I don't think we'll want to deprecate them. It would be tedious if we had to specify -T'self.commit_id()' instead of -Tcommit_id.
2024-02-22 09:57:29 +00:00
type](#operation-type) are available as keywords. For example,
`current_operation` is equivalent to `self.current_operation()`.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
## Operators
The following operators are supported.
* `x.f()`: Method call.
templater: parse negative integer as unary operator and literal Follows up 9702a425e55d "Allow negative numbers in the template grammar." Since we've added parsing rules for operator expressions, it makes sense to parse unary '-' as operator.
2024-02-06 12:57:59 +00:00
* `-x`: Negate integer value.
templater: evaluate logical operator expressions (||, &&, and !) #2924
2024-02-05 11:49:06 +00:00
* `!x`: Logical not.
* `x && y`: Logical and.
* `x || y`: Logical or.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
* `x ++ y`: Concatenate `x` and `y` templates.
## Global functions
The following functions are defined.
templater: add fill(width, content) function The parameter order follows indent()/label() functions, but this might be a bad idea because fill() is more likely to have optional parameters. We can instead add template.fill(width) method as well as .indent(prefix). If we take this approach, we'll probably need to add string.fill()/indent() methods, and/or implicit cast at method resolution. The good thing about the method syntax is that we can add string.refill(), etc. for free, without inventing generic labeled template functions. For #1043, I think it's better to add a config like ui.log-word-wrap = true. We could add term_width/graph_width keywords to the templater, but the implementation would be more complicated, and is difficult to use for the basic use case. Unlike Mercurial, our templater doesn't have a context map to override the graph_width stub.
2023-03-04 14:07:14 +00:00
* `fill(width: Integer, content: Template) -> Template`: Fill lines at
the given `width`.
templater: add indent(prefix, content) function The argument order is different from Mercurial's indent() function. I think indent(prefix, content) is more readable for lengthy content. However, indent(content, prefix, ...) might be better if we want to add an optional firstline_prefix argument.
2023-03-02 08:16:22 +00:00
* `indent(prefix: Template, content: Template) -> Template`: Indent
non-empty lines by the given `prefix`.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
* `label(label: Template, content: Template) -> Template`: Apply label to
the content. The `label` is evaluated as a space-separated string.
* `if(condition: Boolean, then: Template[, else: Template]) -> Template`:
Conditionally evaluate `then`/`else` template content.
* `concat(content: Template...) -> Template`:
Same as `content_1 ++ ... ++ content_n`.
* `separate(separator: Template, content: Template...) -> Template`:
Insert separator between **non-empty** contents.
templater: add surround(prefix, suffix, content) function I'll probably add infix logical operators later, but the surround() function is still useful because we don't have to repeat the condition: if(x || y, "<" ++ separate(" ", x, y) ++ ">") surround("<", ">", separate(" ", x, y)) It can't be used if we want to add placeholder text, though: if(x || y, "<" ++ separate(" ", x, y) ++ ">", "(none)") Closes #2924
2024-02-06 10:28:51 +00:00
* `surround(prefix: Template, suffix: Template, content: Template) -> Template`:
Surround **non-empty** content with texts such as parentheses.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
## Types
### Boolean type
templater: add boolean literals They are implemented as literal expressions so that user cannot override them by false and true aliases.
2023-09-02 08:49:21 +00:00
No methods are defined. Can be constructed with `false` or `true` literal.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
templater: add "parents" keyword in place of "parent_commit_ids" All commit keywords are mapped to nullary methods. No matter if we'll introduce .field syntax and/or self. keyword, this implementation can be reused.
2023-03-19 12:13:47 +00:00
### Commit type
docs: move template keywords list to corresponding types I'm going to introduce the "self" variable, and it will make more sense to document keywords as methods of the self object type.
2024-02-22 11:35:07 +00:00
This type cannot be printed. The following methods are defined.
* `description() -> String`
* `change_id() -> ChangeId`
* `commit_id() -> CommitId`
* `parents() -> List<Commit>`
* `author() -> Signature`
* `committer() -> Signature`
* `working_copies() -> String`: For multi-workspace repository, indicate
working-copy commit as `<workspace name>@`.
* `current_working_copy() -> Boolean`: True for the working-copy commit of the
current workspace.
* `branches() -> List<RefName>`: Local and remote branches pointing to the commit.
A tracking remote branch will be included only if its target is different
from the local one.
* `local_branches() -> List<RefName>`: All local branches pointing to the commit.
* `remote_branches() -> List<RefName>`: All remote branches pointing to the commit.
* `tags() -> List<RefName>`
* `git_refs() -> List<RefName>`
* `git_head() -> List<RefName>`
* `divergent() -> Boolean`: True if the commit's change id corresponds to multiple
visible commits.
* `hidden() -> Boolean`: True if the commit is not visible (a.k.a. abandoned).
* `conflict() -> Boolean`: True if the commit contains merge conflicts.
* `empty() -> Boolean`: True if the commit modifies no files.
* `root() -> Boolean`: True if the commit is the root commit.
templater: add "parents" keyword in place of "parent_commit_ids" All commit keywords are mapped to nullary methods. No matter if we'll introduce .field syntax and/or self. keyword, this implementation can be reused.
2023-03-19 12:13:47 +00:00
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### CommitId / ChangeId type
The following methods are defined.
* `.short([len: Integer]) -> String`
* `.shortest([min_len: Integer]) -> ShortestIdPrefix`: Shortest unique prefix.
### Integer type
No methods are defined.
templater: add "parent_commit_ids" keyword A list type isn't so useful without a map operation, but List<CommitId> is at least printable. Maybe we can experiment with it to craft a map operation. If a map operation is introduced, this keyword might be replaced with "parents.map(|commit| commit.commit_id)", where parents is of List<Commit> type, and the .map() method will probably return List<Template>.
2023-03-06 12:02:57 +00:00
### List type
templater: allow implicit list-to-boolean cast I'm going to change "branches" to return a list instead of formatted string, and I don't think "if(branches, ..)" should be invalidated by that. Perhaps, a container type like String, Vec<T>, Option<T> can implement the cast.
2023-10-27 00:50:32 +00:00
A list can be implicitly converted to `Boolean`. The following methods are
defined.
templater: add list.join(separator) method The implementation is a bit tricky since we have to combine a property (of C -> Vec<Template<()>> type) and a separator of Template<C> type.
2023-03-06 13:02:39 +00:00
* `.join(separator: Template) -> Template`: Concatenate elements with
the given `separator`.
templater: add join method to mapped template
2023-03-14 10:57:03 +00:00
* `.map(|item| expression) -> ListTemplate`: Apply template `expression`
templater: add "parents" keyword in place of "parent_commit_ids" All commit keywords are mapped to nullary methods. No matter if we'll introduce .field syntax and/or self. keyword, this implementation can be reused.
2023-03-19 12:13:47 +00:00
to each element. Example: `parents.map(|c| c.commit_id().short())`
templater: add "parent_commit_ids" keyword A list type isn't so useful without a map operation, but List<CommitId> is at least printable. Maybe we can experiment with it to craft a map operation. If a map operation is introduced, this keyword might be replaced with "parents.map(|commit| commit.commit_id)", where parents is of List<Commit> type, and the .map() method will probably return List<Template>.
2023-03-06 12:02:57 +00:00
templater: add join method to mapped template
2023-03-14 10:57:03 +00:00
### ListTemplate type
The following methods are defined. See also the `List` type.
* `.join(separator: Template) -> Template`
templater: add Operation type and methods There are no keywords or methods that return Operation yet, but we might add "self" keyword that returns the context object.
2024-02-22 08:39:43 +00:00
### Operation type
docs: move template keywords list to corresponding types I'm going to introduce the "self" variable, and it will make more sense to document keywords as methods of the self object type.
2024-02-22 11:35:07 +00:00
This type cannot be printed. The following methods are defined.
* `current_operation() -> Boolean`
* `description() -> String`
* `id() -> OperationId`
* `tags() -> String`
* `time() -> TimestampRange`
* `user() -> String`
* `root() -> Boolean`: True if the commit is the root commit.
templater: add Operation type and methods There are no keywords or methods that return Operation yet, but we might add "self" keyword that returns the context object.
2024-02-22 08:39:43 +00:00
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### OperationId type
The following methods are defined.
* `.short([len: Integer]) -> String`
templater: add types for local/remote ref names Both local and remote refs are backed by the same value type since we'll need some kind of runtime abstraction to represent "branches" keyword (which is a list of local + remote branches.) It's tedious to implement separate local/remote/both ref types. The "unsynced" flag is inverted just because the positive term is slightly easier to document.
2023-10-25 06:36:22 +00:00
### RefName type
The following methods are defined.
* `.name() -> String`: Local branch or tag name.
* `.remote() -> String`: Remote name or empty if this is a local ref.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### ShortestIdPrefix type
The following methods are defined.
* `.prefix() -> String`
* `.rest() -> String`
* `.upper() -> ShortestIdPrefix`
* `.lower() -> ShortestIdPrefix`
### Signature type
The following methods are defined.
* `.name() -> String`
* `.email() -> String`
* `.username() -> String`
* `.timestamp() -> Timestamp`
### String type
A string can be implicitly converted to `Boolean`. The following methods are
defined.
* `.contains(needle: Template) -> Boolean`
* `.first_line() -> String`
templater: add string.lines() method This wouldn't be used much in practice, but is useful for writing tests of list methods.
2023-03-07 09:19:50 +00:00
* `.lines() -> List<String>`: Split into lines excluding newline characters.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
* `.upper() -> String`
* `.lower() -> String`
templates: Add more string methods Add starts_with/ends_with/remove_prefix/remove_suffix/substr methods to string when templating.
2023-08-22 18:40:51 +00:00
* `.starts_with(needle: Template) -> Boolean`
* `.ends_with(needle: Template) -> Boolean`
* `.remove_prefix(needle: Template) -> String`: Removes the passed prefix, if present
* `.remove_suffix(needle: Template) -> String`: Removes the passed suffix, if present
* `.substr(start: Integer, end: Integer) -> String`: Extract substring. Negative values count from the end.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
templates.md docs: Document string literal format We are a little weird about which string escapes we support, and we don't support raw strings. I thought this might be worth documenting. Inspired by https://github.com/martinvonz/jj/pull/2251
2023-09-14 23:43:47 +00:00
#### String literals
String literals must be surrounded by double quotes (`"`). The following escape
sequences starting with a backslash have their usual meaning: `\"`, `\\`, `\n`,
`\r`, `\t`, `\0`. Other escape sequences are not supported. Any UTF-8 characters
are allowed inside a string literal, with two exceptions: unescaped `"`-s and
uses of `\` that don't form a valid escape sequence.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### Template type
templater: add support for unformattable property A property of Commit type won't have a default format.
2023-03-19 11:43:51 +00:00
Most types can be implicitly converted to `Template`. No methods are defined.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### Timestamp type
The following methods are defined.
* `.ago() -> String`: Format as relative timestamp.
templater: add timestamp.format() method A format string is parsed statically due to error handling restriction. I think it covers almost all use cases.
2023-03-14 12:40:36 +00:00
* `.format(format: String) -> String`: Format with [the specified strftime-like
format string](https://docs.rs/chrono/latest/chrono/format/strftime/).
Add UTC format for timestamp formats. Thanks to @rauljordan for these changes. Add tests for new UTC timestamp format Add documentation for timestamp utc Update CHANGELOG.md
2023-08-11 20:31:47 +00:00
* `.utc() -> Timestamp`: Convert timestamp into UTC timezone.
templater: add a local() method on Timestamps (#2900)
2024-02-12 07:09:33 +00:00
* `.local() -> Timestamp`: Convert timestamp into local timezone.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### TimestampRange type
The following methods are defined.
* `.start() -> Timestamp`
* `.end() -> Timestamp`
* `.duration() -> String`
## Configuration
docs: markdown fixups, mostly to remove links pointing outside docs This makes mkdocs compile cleanly
2023-08-13 01:38:57 +00:00
The default templates and aliases() are defined in the `[templates]` and
`[template-aliases]` sections of the config respectively. The exact definitions
can be seen in the `cli/src/config/templates.toml` file in jj's source tree.
<!--- TODO: Find a way to embed the default config files in the docs -->
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
New keywords and functions can be defined as aliases, by using any
combination of the predefined keywords/functions and other aliases.
For example:
```toml
[template-aliases]
'commit_change_ids' = '''
concat(
format_field("Commit ID", commit_id),
format_field("Change ID", commit_id),
)
'''
'format_field(key, value)' = 'key ++ ": " ++ value ++ "\n"'
```
Copy permalink