Improve RuleBuilder documentation and methods
Add a few convenience methods, document all the methods and add
examples that would show up in the godoc if we were to actually
generate it.
Test: rule_builder_test.go
Change-Id: I270fed605ffec34e6f5b36fde0dc9ca52694b741
diff --git a/android/rule_builder_test.go b/android/rule_builder_test.go
index 533b090..c896719 100644
--- a/android/rule_builder_test.go
+++ b/android/rule_builder_test.go
@@ -15,15 +15,103 @@
package android
import (
+ "fmt"
"io/ioutil"
"os"
"path/filepath"
"reflect"
+ "strings"
"testing"
)
+func ExampleRuleBuilder() {
+ rule := NewRuleBuilder()
+
+ rule.Command().Tool("ld").Inputs([]string{"a.o", "b.o"}).FlagWithOutput("-o ", "linked")
+ rule.Command().Text("echo success")
+
+ // To add the command to the build graph:
+ // rule.Build(pctx, ctx, "link", "link")
+
+ fmt.Printf("commands: %q\n", strings.Join(rule.Commands(), " && "))
+ fmt.Printf("tools: %q\n", rule.Tools())
+ fmt.Printf("inputs: %q\n", rule.Inputs())
+ fmt.Printf("outputs: %q\n", rule.Outputs())
+
+ // Output:
+ // commands: "ld a.o b.o -o linked && echo success"
+ // tools: ["ld"]
+ // inputs: ["a.o" "b.o"]
+ // outputs: ["linked"]
+}
+
+func ExampleRuleBuilderCommand() {
+ rule := NewRuleBuilder()
+
+ // chained
+ rule.Command().Tool("ld").Inputs([]string{"a.o", "b.o"}).FlagWithOutput("-o ", "linked")
+
+ // unchained
+ cmd := rule.Command()
+ cmd.Tool("ld")
+ cmd.Inputs([]string{"a.o", "b.o"})
+ cmd.FlagWithOutput("-o ", "linked")
+
+ // mixed:
+ cmd = rule.Command().Tool("ld")
+ cmd.Inputs([]string{"a.o", "b.o"})
+ cmd.FlagWithOutput("-o ", "linked")
+}
+
+func ExampleRuleBuilderCommand_Flag() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("ls").Flag("-l"))
+ // Output:
+ // ls -l
+}
+
+func ExampleRuleBuilderCommand_FlagWithArg() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("ls").
+ FlagWithArg("--sort=", "time"))
+ // Output:
+ // ls --sort=time
+}
+
+func ExampleRuleBuilderCommand_FlagForEachInput() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("turbine").
+ FlagForEachInput("--classpath ", []string{"a.jar", "b.jar"}))
+ // Output:
+ // turbine --classpath a.jar --classpath b.jar
+}
+
+func ExampleRuleBuilderCommand_FlagWithInputList() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("java").
+ FlagWithInputList("-classpath=", []string{"a.jar", "b.jar"}, ":"))
+ // Output:
+ // java -classpath=a.jar:b.jar
+}
+
+func ExampleRuleBuilderCommand_FlagWithInput() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("java").
+ FlagWithInput("-classpath=", "a"))
+ // Output:
+ // java -classpath=a
+}
+
+func ExampleRuleBuilderCommand_FlagWithList() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("ls").
+ FlagWithList("--sort=", []string{"time", "size"}, ","))
+ // Output:
+ // ls --sort=time,size
+}
+
func TestRuleBuilder(t *testing.T) {
- rule := RuleBuilder{}
+ rule := NewRuleBuilder()
cmd := rule.Command().
Flag("Flag").
@@ -112,7 +200,7 @@
}
func testRuleBuilder_Build(ctx BuilderContext, in Path, out WritablePath) {
- rule := RuleBuilder{}
+ rule := NewRuleBuilder()
rule.Command().Tool("cp").Input(in.String()).Output(out.String())