doc: add string style transformation

Author: HerringtonDarkholme

website/guide/rewrite/transform.md

@@ -26,6 +26,14 @@ transform:
       endChar: -1
 ```
 
+ast-grep 0.38.3+ supports string style transformations to simplify rule writing.
+The above example can be simplified to one-line style like:
+
+```yaml
+transfrom:
+  NEW_VAR: replace($VAR_NAME, replace=regex, by=replacement)
+  ANOTHER_NEW_VAR: substring($NEW_VAR, startChar=1, endChar=-1)
+```
 
 ## Example of Converting Generator in Python
 
@@ -164,6 +172,32 @@ If `$$$ARGS` does match nodes, then the replacement regular expression will repl
 This method is invented by [Surma](https://surma.dev/) in a [tweet](https://twitter.com/DasSurma/status/1706086320051794217), so the useful trick is named after him.
 :::
 
+## String Style Transformations
+
+To simplify the syntax of transformations, ast-grep 0.38.3+ supports a new string style transformation syntax. This allows us to write transformations in a more concise and readable way.
+
+The string style transformation syntax is similar to the CSS function call syntax
+
+```yaml
+# illustration of string style transformation syntax
+NEW_VAR: transform($SOURCE_VAR, option1=value1, option2=value2)
+```
+
+The transformation name is followed by parentheses containing the arguments. The first argument is always the source meta-variable, and the rest are the transformation options in the form of key-value pairs.
+
+For example, the transformation examples above can be written as:
+
+```yaml
+transform:
+  LIST: substring($GEN, startChar=1, endChar=-1)
+  KEBABED: convert($OLD_FN, toCase=kebabCase)
+  MAYBE_COMMA: replace($$$ARGS, replace='^.+', by=', ')
+```
+
+:::warning
+The string style transformation syntax is only available in ast-grep 0.38.3 and later versions. If you are using an older version, please use the original object style syntax.
+:::
+
 ## Even More Advanced Transformations
 
 We can use rewriters in the [`rewrite`](/guide/rewrite/rewriter.html) transformation to apply dynamic transformations to the AST. We will cover it in next section.

website/reference/yaml.md

@@ -21,7 +21,7 @@ An ast-grep rule is a YAML object with the following keys:
 
 Unique, descriptive identifier, e.g., `no-unused-variable`.
 
-Example:
+**Example:**
 ```yaml
 id: no-console-log
 ```
@@ -35,7 +35,7 @@ Specify the language to parse and the file extension to include in matching.
 
 Valid values are: `C`, `Cpp`, `CSharp`, `Css`, `Go`, `Html`, `Java`, `JavaScript`, `Kotlin`, `Lua`, `Python`, `Rust`, `Scala`, `Swift`, `Thrift`, `Tsx`, `TypeScript`
 
-Example:
+**Example:**
 ```yaml
 language: JavaScript
 ```
@@ -64,7 +64,7 @@ Additional meta variables pattern to filter matches. The key is matched meta var
 **Note, constraints only applies to the single meta variable like `$ARG`,** not multiple meta variable like `$$$ARGS`.
 So the key name must only refer to a single meta variable.
 
-Example:
+**Example:**
 
 ```yaml
 rule:
@@ -91,7 +91,7 @@ A dictionary of utility rules that can be used in `matches` locally.
 The dictionary key is the utility rule id and the value is the rule object.
 See [utility rule guide](/guide/rule-config/utility-rule).
 
-Example:
+**Example:**
 
 ```yaml
 utils:
@@ -110,18 +110,22 @@ utils:
 * required: false
 
 A dictionary to manipulate meta-variables. The dictionary key is the new variable name.
-The dictionary value is a transformation object that specifies how meta var is processed.
+The dictionary value is a transformation object or transformation string that specifies how meta var is processed.
 
 Please also see [transformation reference](/reference/yaml/transformation) for details.
 
-Example:
+**Example:**
 ```yaml
 transform:
   NEW_VAR_NAME:      # new variable name
     replace:         # transform operation
       source: $ARGS
       replace: '^.+'
       by: ', '
+
+# string style for ast-grep 0.38.3+
+transform:
+  NEW_VAR_NAME: replace($ARGS, replace='^.+', by=', ')
 ```
 
 ### `fix`
@@ -133,15 +137,16 @@ A pattern or a `FixConfig` object to auto fix the issue. See details in [fix obj
 
 It can reference meta variables that appeared in the rule.
 
-Example:
+**Example:**
+
 ```yaml
 fix: logger.log($$$ARGS)
 
 # you can also use empty string to delete match
 fix: ""
 ```
 
-### `rewriters` <Badge type="warning" text="Experimental" />
+### `rewriters`
 * type: `Array<Rewriter>`
 * required: false
 
@@ -151,7 +156,7 @@ A rewriter rule is similar to ordinary YAML rule, but it ony contains _finding_
 
 Please also see [rewriter reference](/reference/yaml/rewriter.html) for details.
 
-Example:
+**Example:**
 ```yaml
 rewriters:
 - id: stringify
@@ -172,7 +177,7 @@ Specify the level of matched result. Available choice: `hint`, `info`, `warning`
 
 When `severity` is `off`, ast-grep will disable the rule in scanning.
 
-Example:
+**Example:**
 ```yaml
 severity: warning
 ```
@@ -187,7 +192,7 @@ but specific enough to be understood without additional context.
 
 It can reference meta-variables that appeared in the rule.
 
-Example:
+**Example:**
 ```yaml
 message: "console.log should not be used in production code"
 ```
@@ -199,7 +204,9 @@ message: "console.log should not be used in production code"
 
 Additional notes to elaborate the message and provide potential fix to the issue.
 
-Example:
+`note` can contains markdown syntax, but it _cannot_ reference meta-variables.
+
+**Example:**
 ```yaml
 note: "Use a logger instead"
 ```
@@ -213,7 +220,7 @@ A dictionary of labels to customize highlighting. The dictionary key is the meta
 * `style`: (required) the style of the label. Available choice: `primary`, `secondary`.
 * `message`: (optional) the message to be displayed in the editor extension.
 
-Example:
+**Example:**
 ```yaml
 labels:
   ARG:
@@ -251,6 +258,7 @@ Be sure to remove `./` to the beginning of your rules. ast-grep will not recogni
 * type: `Array<String>`
 * required: false
 
+**Example:**
 ```yaml
 ignores:
   - test/**/*.js
@@ -281,7 +289,7 @@ To disable this behavior, use [`--no-ignore`](/reference/cli.html#scan) in CLI.
 
 Documentation link to this rule. It will be displayed in editor extension if supported.
 
-Example:
+**Example:**
 
 ```yaml
 url: 'https://ast-grep.github.io/catalog/python/#migrate-openai-sdk'
@@ -295,7 +303,7 @@ Extra information for the rule. This section can include custom data for externa
 
 ast-grep will output `metadata` with matches in [`--json`](/reference/cli/scan.html#json-style) mode if [`--include-metadata`](/reference/cli/scan.html#include-metadata) is on.
 
-Example:
+**Example:**
 
 ```yaml
 metadata:

website/reference/yaml/transformation.md

@@ -49,6 +49,10 @@ transform:
       replace: regex
       by: replacement
       source: $VAR
+
+# string style for ast-grep 0.38.3+
+transform:
+  NEW_VAR: replace($VAR, replace=regex, by=replacement)
 ```
 
 :::tip Pro tip
@@ -93,6 +97,10 @@ transform:
       startChar: 1
       endChar: -1
       source: $VAR
+
+# string style for ast-grep 0.38.3+
+transform:
+  NEW_VAR: substring($VAR, startChar=1, endChar=-1)
 ```
 
 :::tip Pro Tip
@@ -189,6 +197,10 @@ transform:
       toCase: kebabCase
       separatedBy: [underscore]
       source: $VAR
+
+# string style for ast-grep 0.38.3+
+transform:
+  NEW_VAR: convert($VAR, toCase=kebabCase, separatedBy=[underscore])
 ```
 
 Suppose we have a string `ast_Grep` as the input `$VAR`, The example above will convert the string as following:
@@ -198,7 +210,7 @@ Suppose we have a string `ast_Grep` as the input `$VAR`, The example above will
 
 Thank [Aarni Koskela](https://github.com/akx) for proposing and implementing the first version of this feature!
 
-## `rewrite` <Badge type="warning" text="Experimental" />
+## `rewrite`
 
 `rewrite` is an experimental transformation that allows you to selectively transform a meta variable by `rewriter` rules.
 Instead of rewriting the single target node which matches the rule, `rewrite` can rewrite a subset of AST captured by a meta-variable.
@@ -250,6 +262,10 @@ transform:
       source: $VAR
       rewriters: [rule1, rule2]
       joinBy: "\n"
+
+# string style for ast-grep 0.38.3+
+transform:
+  NEW_VAR: rewrite($VAR, rewriters=[rule1, rule2], joinBy='\n')
 ```
 
 Thank [Eitan Mosenkis](https://github.com/emosenkis) for proposing this idea!