outline: Make reading source from stdin uniform across operating syst…

…ems (#760)

* outline: Make reading source from stdin uniform across operating systems

Let's say that there is an IDE plugin that calls `gingko outline`. It will
likely pipe the document contents via stdin. And the IDE will likely run on
multiple operating systems. With the `-` alias for stdin, the plugin can use
the same ginkgo command on every operating system. This alias is common, but
not ubiquituous. Users can continue to use operating system-specific filenames
for stdin.

Example:

```shell
> cat outline/_testdata/normal_test.go | ./ginkgo outline -format=indent -
```

```shell
Name,Text,Start,End,Spec,Focused,Pending
Describe,NormalFixture,116,605,false,false,false
    Describe,normal,152,244,false,false,false
        It,normal,182,240,true,false,false
            By,step 1,207,219,false,false,false
            By,step 2,223,235,false,false,false
    Context,normal,247,307,false,false,false
        It,normal,276,303,true,false,false
    When,normal,310,367,false,false,false
        It,normal,336,363,true,false,false
    It,normal,370,396,true,false,false
    Specify,normal,399,430,true,false,false
    Measure,normal,433,480,true,false,false
    DescribeTable,normal,483,541,false,false,false
        Entry,normal,522,537,true,false,false
    DescribeTable,normal,544,602,false,false,false
        Entry,normal,583,598,true,false,false
```

* outline: Remove duplicate definition of the short usage message

ginkgo/outline_command.go

@@ -14,6 +14,10 @@ import (
 const (
 	// indentWidth is the width used by the 'indent' output
 	indentWidth = 4
+	// stdinAlias is a portable alias for stdin. This convention is used in
+	// other CLIs, e.g., kubectl.
+	stdinAlias   = "-"
+	usageCommand = "ginkgo outline <filename>"
 )
 
 func BuildOutlineCommand() *Command {
@@ -24,9 +28,11 @@ func BuildOutlineCommand() *Command {
 	return &Command{
 		Name:         "outline",
 		FlagSet:      flagSet,
-		UsageCommand: "ginkgo outline <filename>",
+		UsageCommand: usageCommand,
 		Usage: []string{
-			"Outline of Ginkgo symbols for the file",
+			"Create an outline of Ginkgo symbols for a file",
+			"To read from stdin, use: `ginkgo outline -`",
+			"Accepts the following flags:",
 		},
 		Command: func(args []string, additionalArgs []string) {
 			outlineFile(args, format)
@@ -36,20 +42,32 @@ func BuildOutlineCommand() *Command {
 
 func outlineFile(args []string, format string) {
 	if len(args) != 1 {
-		println("usage: ginkgo outline <filename>")
+		println(fmt.Sprintf("usage: %s", usageCommand))
 		os.Exit(1)
 	}
 
 	filename := args[0]
+	var src *os.File
+	if filename == stdinAlias {
+		src = os.Stdin
+	} else {
+		var err error
+		src, err = os.Open(filename)
+		if err != nil {
+			println(fmt.Sprintf("error opening file: %s", err))
+			os.Exit(1)
+		}
+	}
+
 	fset := token.NewFileSet()
 
-	src, err := parser.ParseFile(fset, filename, nil, 0)
+	parsedSrc, err := parser.ParseFile(fset, filename, src, 0)
 	if err != nil {
 		println(fmt.Sprintf("error parsing source: %s", err))
 		os.Exit(1)
 	}
 
-	o, err := outline.FromASTFile(src)
+	o, err := outline.FromASTFile(parsedSrc)
 	if err != nil {
 		println(fmt.Sprintf("error creating outline: %s", err))
 		os.Exit(1)