Add terraform state list command

This introduces the terraform state list command to list the resources
within a state. This is the first of many state management commands to
come into 0.7.

This is the first command of many to come that is considered a
"plumbing" command within Terraform (see "plumbing vs porcelain":
http://git.661346.n2.nabble.com/what-are-plumbing-and-porcelain-td2190639.html).
As such, this PR also introduces a bunch of groundwork to support
plumbing commands.

The main changes:

- Main command output is changed to split "common" and "uncommon"
  commands.

- mitchellh/cli is updated to support nested subcommands, since
  terraform state list is a nested subcommand.

- terraform.StateFilter is introduced as a way in core to filter/search
  the state files. This is very basic currently but I expect to make it
  more advanced as time goes on.

- terraform state list command is introduced to list resources in a
  state. This can take a series of arguments to filter this down.

Known issues, or things that aren't done in this PR on purpose:

- Unit tests for terraform state list are on the way. Unit tests for the
  core changes are all there.

command/meta.go

@@ -326,6 +326,9 @@ func (m *Meta) flagSet(n string) *flag.FlagSet {
 	}()
 	f.SetOutput(errW)
 
+	// Set the default Usage to empty
+	f.Usage = func() {}
+
 	return f
 }
 

command/state_command.go

@@ -0,0 +1,40 @@
+package command
+
+import (
+	"strings"
+
+	"github.com/mitchellh/cli"
+)
+
+// StateCommand is a Command implementation that just shows help for
+// the subcommands nested below it.
+type StateCommand struct {
+	Meta
+}
+
+func (c *StateCommand) Run(args []string) int {
+	return cli.RunResultHelp
+}
+
+func (c *StateCommand) Help() string {
+	helpText := `
+Usage: terraform state <subcommand> [options] [args]
+
+  This command has subcommands for advanced state management.
+
+  These subcommands can be used to slice and dice the Terraform state.
+  This is sometimes necessary in advanced cases. For your safety, all
+  state management commands that modify the state create a timestamped
+  backup of the state prior to making modifications.
+
+  The structure and output of the commands is specifically tailored to work
+  well with the common Unix utilities such as grep, awk, etc. We recommend
+  using those tools to perform more advanced state tasks.
+
+`
+	return strings.TrimSpace(helpText)
+}
+
+func (c *StateCommand) Synopsis() string {
+	return "Advanced state management"
+}

command/state_list.go

@@ -0,0 +1,101 @@
+package command
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/hashicorp/terraform/terraform"
+	"github.com/mitchellh/cli"
+)
+
+// StateListCommand is a Command implementation that lists the resources
+// within a state file.
+type StateListCommand struct {
+	Meta
+}
+
+func (c *StateListCommand) Run(args []string) int {
+	args = c.Meta.process(args, true)
+
+	cmdFlags := c.Meta.flagSet("state list")
+	cmdFlags.StringVar(&c.Meta.statePath, "state", DefaultStateFilename, "path")
+	if err := cmdFlags.Parse(args); err != nil {
+		return cli.RunResultHelp
+	}
+	args = cmdFlags.Args()
+
+	state, err := c.State()
+	if err != nil {
+		c.Ui.Error(fmt.Sprintf(errStateLoadingState, err))
+		return cli.RunResultHelp
+	}
+
+	stateReal := state.State()
+	if stateReal == nil {
+		c.Ui.Error(fmt.Sprintf(errStateNotFound))
+		return 1
+	}
+
+	filter := &terraform.StateFilter{State: stateReal}
+	results, err := filter.Filter(args...)
+	if err != nil {
+		c.Ui.Error(fmt.Sprintf(errStateFilter, err))
+		return cli.RunResultHelp
+	}
+
+	for _, result := range results {
+		if _, ok := result.Value.(*terraform.InstanceState); ok {
+			c.Ui.Output(result.Address)
+		}
+	}
+
+	return 0
+}
+
+func (c *StateListCommand) Help() string {
+	helpText := `
+Usage: terraform state list [options] [pattern...]
+
+  List resources in the Terraform state.
+
+  This command lists resources in the Terraform state. The pattern argument
+  can be used to filter the resources by resource or module. If no pattern
+  is given, all resources are listed.
+
+  The pattern argument is meant to provide very simple filtering. For
+  advanced filtering, please use tools such as "grep". The output of this
+  command is designed to be friendly for this usage.
+
+  The pattern argument accepts any resource targeting syntax. Please
+  refer to the documentation on resource targeting syntax for more
+  information.
+
+Options:
+
+  -state=statefile    Path to a Terraform state file to use to look
+                      up Terraform-managed resources. By default it will
+                      use the state "terraform.tfstate" if it exists.
+
+`
+	return strings.TrimSpace(helpText)
+}
+
+func (c *StateListCommand) Synopsis() string {
+	return "List resources in the state"
+}
+
+const errStateFilter = `Error filtering state: %[1]s
+
+Please ensure that all your addresses are formatted properly.`
+
+const errStateLoadingState = `Error loading the state: %[1]s
+
+Please ensure that your Terraform state exists and that you've
+configured it properly. You can use the "-state" flag to point
+Terraform at another state file.`
+
+const errStateNotFound = `No state file was found!
+
+State management commands require a state file. Run this command
+in a directory where Terraform has been run or use the -state flag
+to point the command to a specific state location.`

command/state_list_test.go

@@ -0,0 +1,59 @@
+package command
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mitchellh/cli"
+)
+
+func TestStateList(t *testing.T) {
+	state := testState()
+	statePath := testStateFile(t, state)
+
+	p := testProvider()
+	ui := new(cli.MockUi)
+	c := &StateListCommand{
+		Meta: Meta{
+			ContextOpts: testCtxConfig(p),
+			Ui:          ui,
+		},
+	}
+
+	args := []string{
+		"-state", statePath,
+	}
+	if code := c.Run(args); code != 0 {
+		t.Fatalf("bad: %d\n\n%s", code, ui.ErrorWriter.String())
+	}
+
+	// Test that outputs were displayed
+	expected := strings.TrimSpace(testStateListOutput) + "\n"
+	actual := ui.OutputWriter.String()
+	if actual != expected {
+		t.Fatalf("Expected:\n%q\n\nTo equal: %q", actual, expected)
+	}
+}
+
+func TestStateList_noState(t *testing.T) {
+	tmp, cwd := testCwd(t)
+	defer testFixCwd(t, tmp, cwd)
+
+	p := testProvider()
+	ui := new(cli.MockUi)
+	c := &StateListCommand{
+		Meta: Meta{
+			ContextOpts: testCtxConfig(p),
+			Ui:          ui,
+		},
+	}
+
+	args := []string{}
+	if code := c.Run(args); code != 1 {
+		t.Fatalf("bad: %d\n\n%s", code, ui.ErrorWriter.String())
+	}
+}
+
+const testStateListOutput = `
+test_instance.foo
+`

commands.go

@@ -10,6 +10,7 @@ import (
 
 // Commands is the mapping of all the available Terraform commands.
 var Commands map[string]cli.CommandFactory
+var PlumbingCommands map[string]struct{}
 
 // Ui is the cli.Ui used for communicating to the outside world.
 var Ui cli.Ui
@@ -34,6 +35,10 @@ func init() {
 		Ui:          Ui,
 	}
 
+	PlumbingCommands = map[string]struct{}{
+		"state": struct{}{}, // includes all subcommands
+	}
+
 	Commands = map[string]cli.CommandFactory{
 		"apply": func() (cli.Command, error) {
 			return &command.ApplyCommand{
@@ -137,6 +142,22 @@ func init() {
 				Meta: meta,
 			}, nil
 		},
+
+		//-----------------------------------------------------------
+		// Plumbing
+		//-----------------------------------------------------------
+
+		"state": func() (cli.Command, error) {
+			return &command.StateCommand{
+				Meta: meta,
+			}, nil
+		},
+
+		"state list": func() (cli.Command, error) {
+			return &command.StateListCommand{
+				Meta: meta,
+			}, nil
+		},
 	}
 }
 

help.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"sort"
+	"strings"
+
+	"github.com/mitchellh/cli"
+)
+
+// helpFunc is a cli.HelpFunc that can is used to output the help for Terraform.
+func helpFunc(commands map[string]cli.CommandFactory) string {
+	// Determine the maximum key length, and classify based on type
+	porcelain := make(map[string]cli.CommandFactory)
+	plumbing := make(map[string]cli.CommandFactory)
+	maxKeyLen := 0
+	for key, f := range commands {
+		if len(key) > maxKeyLen {
+			maxKeyLen = len(key)
+		}
+
+		if _, ok := PlumbingCommands[key]; ok {
+			plumbing[key] = f
+		} else {
+			porcelain[key] = f
+		}
+	}
+
+	var buf bytes.Buffer
+	buf.WriteString("usage: terraform [--version] [--help] <command> [args]\n\n")
+	buf.WriteString(
+		"The available commands for execution are listed below.\n" +
+			"The most common, useful commands are shown first, followed by\n" +
+			"less common or more advanced commands. If you're just getting\n" +
+			"started with Terraform, stick with the common commands. For the\n" +
+			"other commands, please read the help and docs before usage.\n\n")
+	buf.WriteString("Common commands:\n")
+	buf.WriteString(listCommands(porcelain, maxKeyLen))
+	buf.WriteString("\nAll other commands:\n")
+	buf.WriteString(listCommands(plumbing, maxKeyLen))
+	return buf.String()
+}
+
+// listCommands just lists the commands in the map with the
+// given maximum key length.
+func listCommands(commands map[string]cli.CommandFactory, maxKeyLen int) string {
+	var buf bytes.Buffer
+
+	// Get the list of keys so we can sort them, and also get the maximum
+	// key length so they can be aligned properly.
+	keys := make([]string, 0, len(commands))
+	for key, _ := range commands {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	for _, key := range keys {
+		commandFunc, ok := commands[key]
+		if !ok {
+			// This should never happen since we JUST built the list of
+			// keys.
+			panic("command not found: " + key)
+		}
+
+		command, err := commandFunc()
+		if err != nil {
+			log.Printf("[ERR] cli: Command '%s' failed to load: %s",
+				key, err)
+			continue
+		}
+
+		key = fmt.Sprintf("%s%s", key, strings.Repeat(" ", maxKeyLen-len(key)))
+		buf.WriteString(fmt.Sprintf("    %s    %s\n", key, command.Synopsis()))
+	}
+
+	return buf.String()
+}

main.go

@@ -113,7 +113,7 @@ func wrappedMain() int {
 	cli := &cli.CLI{
 		Args:       args,
 		Commands:   Commands,
-		HelpFunc:   cli.BasicHelpFunc("terraform"),
+		HelpFunc:   helpFunc,
 		HelpWriter: os.Stdout,
 	}
 

terraform/resource_address.go

@@ -38,6 +38,35 @@ func (r *ResourceAddress) Copy() *ResourceAddress {
 	return n
 }
 
+// String outputs the address that parses into this address.
+func (r *ResourceAddress) String() string {
+	var result []string
+	for _, p := range r.Path {
+		result = append(result, "module", p)
+	}
+
+	if r.Type != "" {
+		result = append(result, r.Type)
+	}
+
+	if r.Name != "" {
+		name := r.Name
+		switch r.InstanceType {
+		case TypeDeposed:
+			name += ".deposed"
+		case TypeTainted:
+			name += ".tainted"
+		}
+
+		if r.Index >= 0 {
+			name += fmt.Sprintf("[%d]", r.Index)
+		}
+		result = append(result, name)
+	}
+
+	return strings.Join(result, ".")
+}
+
 func ParseResourceAddress(s string) (*ResourceAddress, error) {
 	matches, err := tokenizeResourceAddress(s)
 	if err != nil {