diff --git a/site/docs/reference/dsl/example.png b/site/docs/reference/dsl/example.png new file mode 100644 index 000000000..10c0f8088 Binary files /dev/null and b/site/docs/reference/dsl/example.png differ diff --git a/site/docs/reference/rules.md b/site/docs/reference/dsl/graphs.md similarity index 97% rename from site/docs/reference/rules.md rename to site/docs/reference/dsl/graphs.md index 3ab8c4423..39f325329 100644 --- a/site/docs/reference/rules.md +++ b/site/docs/reference/dsl/graphs.md @@ -1,7 +1,7 @@ --- -id: rules -label: Piranha DSL -title: Piranha DSL +id: graphs +label: Graph Language +title: Graph Language --- Piranha Polyglot uses a domain-specific language (DSL) to specify program transformations. The DSL is used to define rules, scopes, and edges between rules. diff --git a/site/docs/reference/dsl/rules.md b/site/docs/reference/dsl/rules.md new file mode 100644 index 000000000..289dc23e7 --- /dev/null +++ b/site/docs/reference/dsl/rules.md @@ -0,0 +1,34 @@ +--- +id: rules +label: Rule Languages +title: Rule Languages +--- + +Piranha offers support for three distinct rule languages for matching code. + +# Tree-sitter Queries + +The Tree-sitter queries language is one of the rule languages that Piranha supports. For a detailed understanding of the syntax, refer to the [Tree-sitter Syntax Reference](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries). + +# Regular Expressions (Regex) + +Regex forms another rule language supported by Piranha. To create a rule in regex, prepend your query with `rgx `. For instance: `rgx `. Piranha supports the regex syntax derived from the [regex](https://docs.rs/regex/) crate. + +# Concrete Syntax + +Piranha's Concrete Syntax is a custom rule language designed for matching and replacing code. Concrete Syntax operates at the parse tree level, similar to [comby](https://comby.dev/), yet with a distinct difference: it will only match a node if it is possible to traverse the corresponding its parse tree from start to finish using the concrete syntax template. + +Template variables `:[x], :[y], ...` are used as placeholders to match arbitrary nodes (i.e., syntactically meaningful constructs). + +Consider the following code snippet: +```java +exp.isTreated("SHOW_MENU") +``` +To match this code snippet, we can use the concrete syntax (cs) template: +```java +cs :[object].isTreated(:[string]) +``` + +which matches the method invocation nodes as follows: + +![example.png](example.png) diff --git a/site/sidebars.js b/site/sidebars.js index 510575967..43c1c4b38 100644 --- a/site/sidebars.js +++ b/site/sidebars.js @@ -16,7 +16,15 @@ const sidebars = { 'reference/getting-started/demos', ], }, - 'reference/rules', + { + type: 'category', + label: 'Piranha DSL', + collapsed: false, + items: [ + 'reference/dsl/graphs', + 'reference/dsl/rules', + ], + }, 'reference/api', 'reference/cli', {