Merge pull request #12057 from hdost/add-parser-documentation

promql: Add a Makefile target for goyacc

.gitignore

@@ -28,3 +28,6 @@ npm_licenses.tar.bz2
 /.build
 
 /**/node_modules
+
+# Ignore parser debug
+y.output

CONTRIBUTING.md

@@ -78,3 +78,20 @@ GO111MODULE=on go mod tidy
 ```
 
 You have to commit the changes to `go.mod` and `go.sum` before submitting the pull request.
+
+## Working with the PromQL parser
+
+The PromQL parser grammar is located in `promql/parser/generated_parser.y` and it can be built using `make parser`.
+The parser is built using [goyacc](https://pkg.go.dev/golang.org/x/tools/cmd/goyacc)
+
+If doing some sort of debugging, then it is possible to add some verbose output. After generating the parser, then you
+can modify the the `./promql/parser/generated_parser.y.go` manually.
+
+```golang
+// As of writing this was somewhere around line 600.
+var (
+	yyDebug        = 0 // This can be be a number 0 -> 5.
+	yyErrorVerbose = false  // This can be set to true.
+)
+
+```

Makefile

@@ -78,6 +78,17 @@ assets-tarball: assets
 	@echo '>> packaging assets'
 	scripts/package_assets.sh
 
+# We only want to generate the parser when there's changes to the grammar.
+.PHONY: parser
+parser:
+	@echo ">> running goyacc to generate the .go file."
+ifeq (, $(shell which goyacc))
+	@echo "goyacc not installed so skipping"
+	@echo "To install: go install golang.org/x/tools/cmd/goyacc@v0.6.0"
+else
+	goyacc -o promql/parser/generated_parser.y.go promql/parser/generated_parser.y
+endif
+
 .PHONY: test
 # If we only want to only test go code we have to change the test target
 # which is called by all.