github.com/coveo/gotemplate@v2.7.7+incompatible/docs/doc_test/comments.md (about)

     1  {% include navigation.html %}
     2  {% raw %}
     3  # Comments in gotemplate
     4  
     5  It is important to notice that gotemplate doesn't know the language you are using and any identified gotemplate code is executed no matter where it is. Comments in the
     6  host language mean nothing to gotemplate and will be evaluated.
     7  
     8  ## Pseudo comment
     9  
    10  If you insert gotemplate code into file that contains another kind of code such as hcl, json, yaml, xml, java, c# or any other language, your code editor or linter may complains
    11  because it will detect invalid characters.
    12  
    13  To solve that problem, it is possible to inject pseudo comment into you code to hide the gotemplate code to your editor. The gotemplate is still interpretated, but obfuscated to the editor.
    14  
    15  **It is important to render code that is valid for the host language.**
    16  
    17  * `#!` is a pseudo comment that will removes the `#!` part but render everything after.
    18  * `//!` is also used as pseudo comment and behave exactly as `#!`.
    19  * `/*@ @*/` is used to specify pseudo comment in a multi line context, everything inside is rendered, but `/*@` and `@*/` are removed.
    20  
    21  | Razor expression | Go Template           | Render    | Note
    22  | ---------------- | -----------           | ------    | ----
    23  | `# @(2+2)`       | `# {{ add 2 2 }}`     | `# 4`     | gotemplate code after # comment
    24  | `// @(2+2)`      | `// {{ add 2 2 }}`    | `// 4`    | gotemplate code after // comment
    25  | `/* @(2+2) */`   | `/* {{ add 2 2 }} */` | `/* 4 */` | gotemplate code within /* */ comment
    26  | `#! @(2+2)`      | `{{ add 2 2 }}`       | `4`       | Pseudo comment #!
    27  | `//! @(2+2)`     | `{{ add 2 2 }}`       | `4`       | Pseudo comment //!
    28  | `/*@ @(2+2) @*/` | `{{ add 2 2 }}`       | `4`       | Pseudo block comment with /*@ @*/
    29  
    30  ## Real gotemplate comment
    31  
    32  If you really want to add comment to your file and wish them to not be rendered, you must use the following syntax.
    33  
    34  * `##@` removes every character from `##@` up to the end of line.
    35  * `///@` removes every character from `//@` up to the end of line.
    36  * `@#` generates gotemplate real comment `{{/* comment */}}` enclosing every character after the comment up to the end of line.
    37  * `@//` acts exactly as `@#`.
    38  * `@/* */` is used to generates gotemplate comment in a multi-lines context.
    39  
    40  | Razor expression               | Go Template                                     | Render             | Note
    41  | ----------------               | -----------                                     | ------             | ----
    42  | `@(2+2) ##@ comment @(2*3)`    | `{{ add 2 2 }}`                                 | `4`                | Nothing is rendered after ##
    43  | `@(2+2) ///@ comment @(2*3)`   | `{{ add 2 2 }}`                                 | `4`                | Nothing is rendered after ///
    44  | `@(2+2) @# comment @(2*3)`     | `{{ add 2 2 }} {{/* comment {{ mul 2 3 }} */}}` | `4`                | @# generates a real gotemplate comment
    45  | `@(2+2) @// comment @(2*3)`    | `{{ add 2 2 }} {{/* comment {{ mul 2 3 }} */}}` | `4`                | @// also generates a real gotemplate comment
    46  | `@(2+2) @/* comment @(2*3) */` | `{{ add 2 2 }} {{/* comment {{ mul 2 3 }} */}}` | `4`                | @/* */ is used to generate multi-lines gotemplate comment
    47  
    48  Like most of the gotemplate razor syntax, you can add the minus sign to your `@` command to render space eating gotemplate code.
    49  
    50  | Razor expression | Go Template             | Note
    51  | ---------------- | -----------             | ----
    52  | `@// Comment`    | `{{/* Comment */}}`     | No space eater
    53  | `@-// Comment`   | `{{- /* Comment */}}`   | Left space eater
    54  | `@_-// Comment`  | `{{/* Comment */ -}}`   | Right space eaters
    55  | `@--// Comment`  | `{{- /* Comment */ -}}` | Left and right space eaters
    56  
    57  ## Examples
    58  
    59  ### Example with JSON code
    60  
    61  ```go
    62  /*@ @{value} := 2 + 8 * 15 @*/
    63  {
    64      "Str": "string",
    65      "Int": 123,
    66      "Float": 1.23,
    67      "PiAsString": "@Math.Pi",
    68      "ComputedAsString": "@{value}",
    69  
    70      /* You can use the special << syntax to extract the value from the string delimiter */
    71      "Pi": "<<@Math.Pi",
    72      "Computed": "<<@{value}",
    73  }
    74  ```
    75  
    76  will give :
    77  
    78  ```go
    79  {
    80      "Str": "string",
    81      "Int": 123,
    82      "Float": 1.23,
    83      "PiAsString": "3.141592653589793",
    84      "ComputedAsString": "122",
    85  
    86      /* You can use the special << syntax to extract the value from the string delimiter */
    87      "Pi": 3.141592653589793,
    88      "Computed": 122,
    89  }
    90  ```
    91  
    92  ### Example with HCL code
    93  
    94  ```go
    95  #! @value := 2 + 8 * 15
    96  Str              = "string"
    97  Int              = 123
    98  Float            = 1.23
    99  PiAsString       = "@Math.Pi"
   100  ComputedAsString = "@value"
   101  
   102  // You can use the special << syntax to extract the value from the string delimiter
   103  Pi       = "<<@Math.Pi"
   104  Computed = "<<@value"
   105  ```
   106  
   107  will give:
   108  
   109  ```go
   110  Str              = "string"
   111  Int              = 123
   112  Float            = 1.23
   113  PiAsString       = "3.141592653589793"
   114  ComputedAsString = "122"
   115  
   116  // You can use the special << syntax to extract the value from the string delimiter
   117  Pi       = 3.141592653589793
   118  Computed = 122
   119  ```
   120  
   121  {% endraw %}