go.tools/oracle: change notation for byte offsets to "-pos=file.go:#123-#456"

The previous notation (sans '#') now yields an error but is
"reserved for future use", e.g. to denote line/column offsets.
Will implement as needed.

R=r, crawshaw
CC=golang-dev
https://golang.org/cl/13526043

cmd/oracle/main.go

@@ -4,13 +4,11 @@
 
 // oracle: a tool for answering questions about Go source code.
 //
-// Each query prints its results to the standard output in an
-// editor-friendly format.  Currently this is just text in a generic
-// compiler diagnostic format, but in future we could provide
-// sexpr/json/python formats for the raw data so that editors can
-// provide more sophisticated UIs.
+// With -format=plain, the oracle prints query results to the standard
+// output in an editor-friendly format in which every line of output
+// is of the form "pos: text", where pos = "-" if unknown.
 //
-// Every line of output is of the form "pos: text", where pos = "-" if unknown.
+// With -format=json, the oracle prints structured data in JSON syntax.
 //
 package main
 
@@ -31,11 +29,11 @@ import (
 )
 
 var posFlag = flag.String("pos", "",
-	"Filename and offset or extent of a syntax element about which to query, "+
-		"e.g. foo.go:123-456, bar.go:123.")
+	"Filename and byte offset or extent of a syntax element about which to query, "+
+		"e.g. foo.go:#123-#456, bar.go:#123.")
 
 var modeFlag = flag.String("mode", "",
-	"Mode of query to perform: callers, callees, callstack, callgraph, describe.")
+	"Mode of query to perform: e.g. callers, describe, etc.")
 
 var ptalogFlag = flag.String("ptalog", "",
 	"Location of the points-to analysis log file, or empty to disable logging.")
@@ -47,8 +45,8 @@ Usage: oracle [<flag> ...] [<file.go> ...] [<arg> ...]
 Use -help flag to display options.
 
 Examples:
-% oracle -pos 'hello.go 123' hello.go
-% oracle -pos 'hello.go 123 456' hello.go
+% oracle -pos=hello.go:#123      hello.go
+% oracle -pos=hello.go:#123-#456 hello.go
 `
 
 var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to file")

cmd/oracle/oracle.el

@@ -76,11 +76,11 @@ result."
       (go-oracle-set-scope))
   (let* ((filename (file-truename buffer-file-name))
          (posflag (if (use-region-p)
-                      (format "-pos=%s:%s-%s"
+                      (format "-pos=%s:#%d-#%d"
                               filename
                               (1- (go--position-bytes (region-beginning)))
                               (1- (go--position-bytes (region-end))))
-                    (format "-pos=%s:%s"
+                    (format "-pos=%s:#%d"
                             filename
                             (1- (position-bytes (point))))))
          ;; This would be simpler if we could just run 'go tool oracle'.

cmd/oracle/oracle.vim

@@ -29,7 +29,7 @@ set errorformat+=%f:%l.%c-%*[0-9].%*[0-9]:\ %m
 func! s:RunOracle(mode) abort
   let s:pos = line2byte(line("."))+col(".")
   let s:errfile = tempname()
-  let s:cmd = printf("!%s -mode=%s -pos=%s:%d %s >%s",
+  let s:cmd = printf("!%s -mode=%s -pos=%s:#%d %s >%s",
     \ s:go_oracle, a:mode, bufname(""), s:pos, s:scope, s:errfile)
   execute s:cmd
   execute "cfile " . s:errfile

oracle/oracle.go

@@ -261,16 +261,23 @@ func ptrAnalysis(o *oracle) pointer.CallGraphNode {
 	return root
 }
 
-func parseDecimal(s string) int {
-	if s, err := strconv.ParseInt(s, 10, 32); err == nil {
-		return int(s)
+// parseOctothorpDecimal returns the numeric value if s matches "#%d",
+// otherwise -1.
+func parseOctothorpDecimal(s string) int {
+	if s != "" && s[0] == '#' {
+		if s, err := strconv.ParseInt(s[1:], 10, 32); err == nil {
+			return int(s)
+		}
 	}
 	return -1
 }
 
 // parseQueryPos parses a string of the form "file:pos" or
-// file:start-end" where pos, start, end are decimal integers, and
-// returns the extent to which it refers.
+// file:start-end" where pos, start, end match #%d and represent byte
+// offsets, and returns the extent to which it refers.
+//
+// (Numbers without a '#' prefix are reserved for future use,
+// e.g. to indicate line/column positions.)
 //
 func parseQueryPos(fset *token.FileSet, queryPos string) (start, end token.Pos, err error) {
 	if queryPos == "" {
@@ -287,13 +294,13 @@ func parseQueryPos(fset *token.FileSet, queryPos string) (start, end token.Pos,
 	startOffset := -1
 	endOffset := -1
 	if hyphen := strings.Index(offset, "-"); hyphen < 0 {
-		// e.g. "foo.go:123"
-		startOffset = parseDecimal(offset)
+		// e.g. "foo.go:#123"
+		startOffset = parseOctothorpDecimal(offset)
 		endOffset = startOffset
 	} else {
-		// e.g. "foo.go:123-456"
-		startOffset = parseDecimal(offset[:hyphen])
-		endOffset = parseDecimal(offset[hyphen+1:])
+		// e.g. "foo.go:#123-#456"
+		startOffset = parseOctothorpDecimal(offset[:hyphen])
+		endOffset = parseOctothorpDecimal(offset[hyphen+1:])
 	}
 	if startOffset < 0 || endOffset < 0 {
 		err = fmt.Errorf("invalid -pos offset %q", offset)

oracle/oracle_test.go

@@ -163,7 +163,7 @@ func doQuery(out io.Writer, q *query, useJson bool) {
 	buildContext.GOPATH = "testdata"
 	res, err := oracle.Query([]string{q.filename},
 		q.verb,
-		fmt.Sprintf("%s:%d-%d", q.filename, q.start, q.end),
+		fmt.Sprintf("%s:#%d-#%d", q.filename, q.start, q.end),
 		/*PTA-log=*/ nil, &buildContext)
 	if err != nil {
 		fmt.Fprintf(out, "\nError: %s\n", stripLocation(err.Error()))