Skip to main content

edit

In this section, you will find the reference for the Declarative Hook of type edit.


The edit Declarative Hook defines changes made to existing files. See an example definition below:

hooks: 
  - type: edit
    trigger: after-render
    path: src/some-file.txt
    changes:
      - insert:
          line: 0
          value: "# Text inserted in first line\n\n"
          when:
            not-exists: "# Text inserted in first line"
      - search:
          string: "# Text inserted in first line"
          insert-before:
            snippet: snippets/insert-before-first-line.txt
          when:
            not-exists: "# Text inserted before first line"
      - search:
          pattern: (Text )inserted in( first line)
          replace-by:
            value: \1moved from\2
          when:
            not-exists: print(f"Hello {name}!")

Available Actions

path

Defines the path of the file to be edited. The path can contain Jinja expressions.

path: "./some/dir/{{file_name}}"

trigger

Defines triggers that determine when file editing occurs.

before-input
Executes the Declarative Hook before receiving input parameters from the user.

trigger: before-input

before-render
Executes the Declarative Hook before the Template generates project files.

trigger: before-render

after-render
Executes the Declarative Hook after the Template generates project files.

trigger: after-render

changes

Defines the type of action performed on the file. Options are insert and search.

insert

Inserts text into an existing file.

line
Defines the line within the file where insertion occurs. The first line corresponds to index 0. To insert at the last line, use index -1.

value
Defines the text to be inserted.

snippet
Defines a file containing the text to be inserted. The insertion occurs in the file defined in the path field.

when

Conditional action that evaluates whether the insertion should occur. The options not-exists and not-exists-snippet accept text or a file for evaluation.

not-exists
Checks if the text defined in the value field already exists in the target file. If it exists, the insert action is not executed.

not-exists-snippet
Checks if the content of the file defined in the snippet field already exists in the target file. If it exists, the insert action is not executed.

caution

You can use not-exists and not-exists-snippet together. In this case, both conditions are checked. The insert action executes only if neither content (from value nor snippet) is found in the file.

hooks:
  - type: edit
    # ...
    changes:
      - insert:
          line: 0
          value: "# Text inserted in first line\n\n"
          # or 
          snippet: path/to/snippet.txt
          when:
            not-exists: "# Text inserted in first line"
            # and/or
            not-exists-snippet: path/to/snippet.txt

Searches for the first occurrence of a text or pattern in the file to perform an edit.

string
Defines the literal text to search for.

pattern
Defines a regular expression (Regex) pattern to search for.

snippet
Defines a file containing the content to search for.

The string, pattern, and snippet attributes must not be used together in the same search action.

  - search:
      string: "# Text inserted in first line"
      # or
      pattern: (some)\s+(regular)\s+(expression)
      # or
      snippet: snippets/snippet.txt

replace-by

Replaces the first match found with the content of snippet or value.

insert-before

Inserts the value or snippet on the line before the first match found.

insert-after

Inserts the value or snippet on the line after the first match found.

caution

Only one operation (replace-by, insert-before, or insert-after) must be defined per search.

      replace-by:
        snippet: snippets/snippet.txt
      # or  
      insert-before:
        value: some string
      # or
      insert-after:
        snippet: snippets/snippet2.txt

snippet
Defines a file containing the text to be used in the operation.

value
Defines a string to be used in the operation.

caution

The value and snippet attributes must not be used together within the same operation.

      snippet: snippets/snippet.txt
      # or
      value: a string

when

Conditional action that evaluates whether the search and edit should occur.

not-exists
Checks if the text defined in the value field already exists in the file. If it exists, the search action is not executed.

not-exists-snippet
Checks if the content of the file defined in the snippet field already exists in the file. If it exists, the search action is not executed.

Example of edit Declarative Hook with insert action

hooks:
  - type: edit
    trigger: after-render
    path: src/some-file.txt
    changes:
      - insert:
          line: 0
          value: "# Text inserted in first line\n\n"
          when:
            not-exists: "# Text inserted in first line"

Example of edit Declarative Hook with search options

hooks:
  - type: edit
    trigger: after-render
    path: src/some-file.txt
    changes:
      - search:
          string: "# Text inserted in first line"
          # Action options below (choose one):
          replace-by:
            value: \1 \2 \3
          # or
          insert-before:
            snippet: snippets/snippet.txt
          # or
          insert-after:
            value: a string
          # Conditional
          when:
            not-exists: "# Text inserted before first line"