go.tools/cmd/oracle: use -pos=file:#start,#end syntax to indicate half-open [start,end) extent of byte offsets.

Also: improve help message.

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

cmd/oracle/main.go

@@ -25,13 +25,12 @@ import (
 	"runtime"
 	"runtime/pprof"
 
-	"code.google.com/p/go.tools/importer"
 	"code.google.com/p/go.tools/oracle"
 )
 
 var posFlag = flag.String("pos", "",
 	"Filename and byte offset or extent of a syntax element about which to query, "+
-		"e.g. foo.go:#123-#456, bar.go:#123.")
+		"e.g. foo.go:#123,#456, bar.go:#123.")
 
 var modeFlag = flag.String("mode", "",
 	"Mode of query to perform: e.g. callers, describe, etc.")
@@ -42,13 +41,21 @@ var ptalogFlag = flag.String("ptalog", "",
 var formatFlag = flag.String("format", "plain", "Output format: 'plain' or 'json'.")
 
 const usage = `Go source code oracle.
-Usage: oracle [<flag> ...] <args> ...
+Usage: oracle [<flag> ...] [<arg> ...]
 Use -help flag to display options.
 
+The -mode flag is required; the -pos flag is required in most modes.
+
 Examples:
-% oracle -pos=hello.go:#123      hello.go
-% oracle -pos=hello.go:#123-#456 hello.go
-` + importer.InitialPackagesUsage
+
+Describe the syntax at offset 532 in this file (an import spec):
+% oracle -mode=describe -pos=src/code.google.com/p/go.tools/cmd/oracle/main.go:#532 \
+   code.google.com/p/go.tools/cmd/oracle
+
+Print the callgraph of the trivial web-server in JSON format:
+% oracle -mode=callgraph -format=json src/pkg/net/http/triv.go
+
+`
 
 var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to file")
 
@@ -77,7 +84,7 @@ func main() {
 	var ptalog io.Writer
 	if *ptalogFlag != "" {
 		if f, err := os.Create(*ptalogFlag); err != nil {
-			log.Fatal(err.Error())
+			log.Fatalf(err.Error())
 		} else {
 			buf := bufio.NewWriter(f)
 			ptalog = buf
@@ -107,7 +114,7 @@ func main() {
 	// Ask the oracle.
 	res, err := oracle.Query(args, *modeFlag, *posFlag, ptalog, &build.Default)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "%s\n", err)
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
 		os.Exit(1)
 	}
 
@@ -116,7 +123,7 @@ func main() {
 	case "json":
 		b, err := json.Marshal(res)
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "JSON error: %s\n", err)
+			fmt.Fprintf(os.Stderr, "JSON error: %s\n", err.Error())
 			os.Exit(1)
 		}
 		var buf bytes.Buffer

cmd/oracle/oracle.el

@@ -76,7 +76,7 @@ result."
       (go-oracle-set-scope))
   (let* ((filename (file-truename buffer-file-name))
          (posflag (if (use-region-p)
-                      (format "-pos=%s:#%d-#%d"
+                      (format "-pos=%s:#%d,#%d"
                               filename
                               (1- (go--position-bytes (region-beginning)))
                               (1- (go--position-bytes (region-end))))

cmd/oracle/oracle.vim

@@ -27,6 +27,7 @@ let s:go_oracle = "$GOROOT/bin/oracle"
 set errorformat+=%f:%l.%c-%*[0-9].%*[0-9]:\ %m
 
 func! s:RunOracle(mode) abort
+  " TODO(adonovan): support selections, not just positions.
   let s:pos = line2byte(line("."))+col(".")
   let s:errfile = tempname()
   let s:cmd = printf("!%s -mode=%s -pos=%s:#%d %s >%s",

oracle/oracle.go

@@ -281,7 +281,7 @@ func parseOctothorpDecimal(s string) int {
 }
 
 // parseQueryPos parses a string of the form "file:pos" or
-// file:start-end" where pos, start, end match #%d and represent byte
+// 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,
@@ -301,12 +301,12 @@ func parseQueryPos(fset *token.FileSet, queryPos string) (start, end token.Pos,
 	filename, offset := queryPos[:colon], queryPos[colon+1:]
 	startOffset := -1
 	endOffset := -1
-	if hyphen := strings.Index(offset, "-"); hyphen < 0 {
+	if hyphen := strings.Index(offset, ","); hyphen < 0 {
 		// e.g. "foo.go:#123"
 		startOffset = parseOctothorpDecimal(offset)
 		endOffset = startOffset
 	} else {
-		// e.g. "foo.go:#123-#456"
+		// e.g. "foo.go:#123,#456"
 		startOffset = parseOctothorpDecimal(offset[:hyphen])
 		endOffset = parseOctothorpDecimal(offset[hyphen+1:])
 	}

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()))