restic/vendor/cloud.google.com/go/internal/readme/snipmd.awk

124 lines
2.9 KiB
Awk

# Copyright 2017 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# snipmd inserts code snippets from Go source files into a markdown file.
#
# Call with one or more .go files and a .md file:
#
# awk -f snipmd.awk foo.go bar.go template.md
#
# In the Go files, start a snippet with
# //[ NAME
# and end it with
# //]
#
# In the markdown, write
# [snip]:# NAME
# to insert the snippet NAME just below that line.
# If there is already a code block after the [snip]:# line, it will be
# replaced, so a previous output can be used as input.
#
# The following transformations are made to the Go code:
# - The first tab of each line is removed.
# - Trailing blank lines are removed.
# - `ELLIPSIS` and `_ = ELLIPSIS` are replaced by `...`
/^[ \t]*\/\/\[/ { # start snippet in Go file
if (inGo()) {
if ($2 == "") {
die("missing snippet name")
}
curSnip = $2
next
}
}
/^[ \t]*\/\/]/ { # end snippet in Go file
if (inGo()) {
if (curSnip != "") {
# Remove all but one trailing newline.
gsub(/\n+$/, "\n", snips[curSnip])
curSnip = ""
next
} else {
die("//] without corresponding //[")
}
}
}
ENDFILE {
if (curSnip != "") {
die("unclosed snippet: " curSnip)
}
}
# Skip code blocks in the input that immediately follow [snip]:# lines,
# because we just inserted the snippet. Supports round-tripping.
/^```go$/,/^```$/ {
if (inMarkdown() && afterSnip) {
next
}
}
# Matches every line.
{
if (curSnip != "") {
line = $0
# Remove initial tab, if any.
if (line ~ /^\t/) {
line = substr(line, 2)
}
# Replace ELLIPSIS.
gsub(/_ = ELLIPSIS/, "...", line)
gsub(/ELLIPSIS/, "...", line)
snips[curSnip] = snips[curSnip] line "\n"
} else if (inMarkdown()) {
afterSnip = 0
# Copy .md to output.
print
}
}
$1 ~ /\[snip\]:#/ { # Snippet marker in .md file.
if (inMarkdown()) {
# We expect '[snip]:#' to be followed by '(NAME)'
if ($2 !~ /\(.*\)/) {
die("bad snip spec: " $0)
}
name = substr($2, 2, length($2)-2)
if (snips[name] == "") {
die("no snippet named " name)
}
printf("```go\n%s```\n", snips[name])
afterSnip = 1
}
}
function inMarkdown() {
return match(FILENAME, /\.md$/)
}
function inGo() {
return match(FILENAME, /\.go$/)
}
function die(msg) {
printf("%s:%d: %s\n", FILENAME, FNR, msg) > "/dev/stderr"
exit 1
}