github.com/cockroachdb/cockroachdb-parser@v0.23.3-0.20240213214944-911057d40c9a/pkg/sql/parser/help.awk (about)

     1  # Copyright 2017 The Cockroach Authors.
     2  #
     3  # Licensed under the Apache License, Version 2.0 (the "License");
     4  # you may not use this file except in compliance with the License.
     5  # You may obtain a copy of the License at
     6  #
     7  #     http:#www.apache.org/licenses/LICENSE-2.0
     8  #
     9  # Unless required by applicable law or agreed to in writing, software
    10  # distributed under the License is distributed on an "AS IS" BASIS,
    11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    12  # implied. See the License for the specific language governing
    13  # permissions and limitations under the License.
    14  #
    15  
    16  # This file extracts inline help specifications from the grammar file
    17  # (sql.y) into a Go map[string]HelpMessageBody suitable for building
    18  # messages towards clients.
    19  #
    20  # See README.md for details.
    21  
    22  # Hint, to help read awk code: remember in awk strings are 1-indexed!
    23  
    24  BEGIN {
    25      # inhelp serves to assert below that the special
    26      # directives follow an initial "%Help:" marker,
    27      # and do not appear after "%End".
    28      inhelp = 0
    29      # helpkey is the current help key, used for error messages.
    30      helpkey = ""
    31      # instring indicates whether we are currently accumulating
    32      # text for a Go string. If this is set, then we
    33      # first must close the string before generating more code.
    34      instring = 0
    35  
    36      # Header in the generated code.
    37      print "// Code generated by help.awk. DO NOT EDIT."
    38      print "// GENERATED FILE DO NOT EDIT"
    39      print
    40      print "package parser"
    41      print
    42      print "var helpMessages = map[string]HelpMessageBody{"
    43  }
    44  
    45  /^\/\/ %Help:/ && inhelp == 1 { printf "%d: unexpected: %s (last: %s)", NR, $0, helpkey >"/dev/stderr";    exit 1 }
    46  
    47  /^\/\/ %Help:/ && inhelp == 0 {
    48      inhelp = 1
    49      instring = 0
    50      # // %Help:   SOMEKEY - sometext
    51      #          ^^^^^^^^^^^^^^^^^^^^^  take this
    52      helprest = substr($0, index($0, ":")+1)
    53  
    54      # Remove spaces at the beginning.
    55      sub("^[ \t]*", "", helprest)
    56  
    57      # Now split the key from the summary, if there's one.
    58      helpkey = helprest
    59      summary = ""
    60      has_summary = index(helprest, "-")
    61      if (has_summary > 0) {
    62          # SOMEKEY - sometext
    63          #          ^^^^^^^^^ take this
    64          summary = substr(helprest, has_summary+1)
    65          # Remove spaces at the beginning.
    66          sub("^[ \t]*", "", summary)
    67          # SOMEKEY     - sometext
    68          # ^^^^^^^^^^^ take this
    69          helpkey = substr(helprest, 1, has_summary-1)
    70      }
    71      # Remove trailing spaces.
    72      sub("[ \t]*$", "", helpkey)
    73  
    74      # Output a line marker so that errors in the generated code
    75      # properly refer to the original file.
    76      print "  //line sql.y:", NR
    77  
    78      # Generate the code.
    79      printf "  `%s`: {\n", helpkey
    80      if (summary != "") {
    81          printf "    ShortDescription: `%s`,\n", summary
    82      }
    83      next
    84  }
    85  
    86  /^\/\/ %/ && inhelp == 0 { printf "%d: unexpected: %s (last: %s)", NR, $0, helpkey >"/dev/stderr"; exit 1 }
    87  
    88  /^\/\/ %Category:/ && inhelp == 1 {
    89      # // %Category:   HELLO WORLD
    90      #              ^^^^^^^^^^^^^^ take this
    91      key = substr($0, index($0, ":")+1)
    92      # Remove heading spaces.
    93      sub("^[ \t]*", "", key)
    94      # If we were accumulating a string, close it.
    95      if (instring == 1) {
    96          print "`,"
    97      }
    98      # Emit the category marker.
    99      print "    //line sql.y:", NR
   100      printf "    Category: h%s,\n", key
   101      instring = 0
   102      next
   103  }
   104  
   105  /^\/\/ %[^:]*:/ && inhelp == 1 {
   106      # // %SomeKey:   hello world
   107      #     ^^^^^^^ take this
   108      key = substr($0, index($0, "%")+1, index($0,":")-index($0, "%")-1)
   109      # // %SomeKey:   hello world
   110      #             ^^^^^^^^^^^^^^ take this
   111      rest = substr($0, index($0, ":")+1)
   112      # Remove heading spaces.
   113      sub("^[ \t]*", "", rest)
   114      # If we were accumulating a string, close it.
   115      if (instring == 1) {
   116          print "`,"
   117      }
   118      # Emit the key/string pair.
   119      print "    //line sql.y:", NR
   120      printf "    %s: `%s\n", key, rest
   121      instring = 1
   122      next
   123  }
   124  
   125  (/^[^\/]/ || /^\/\/ %End/) && inhelp == 1 {
   126      # If we were accumulating a string, close it.
   127      if (instring == 1) {
   128          print "`,"
   129      }
   130      # Finish the Go dictionary entry.
   131      print "  },"
   132      inhelp = 0
   133      instring = 0
   134      next
   135  }
   136  
   137  /^\/\// && inhelp == 1 {
   138      # We are accumulating content, whatever it is.
   139      # Put it in the generated code.
   140      print substr($0, 4)
   141      next
   142  }
   143  
   144  END {
   145      if (inhelp == 1) {
   146          printf "missing %% End (last: %s)\n", helpkey >"/dev/stderr"
   147          exit 1
   148      }
   149      print "}"
   150  }