add example golang test

Author: Emyrk

convert.go

@@ -37,6 +37,12 @@ type GoParser struct {
 	fileSet       *token.FileSet
 }
 
+// NewGolangParser returns a new GoParser object.
+// This object is responsible for converting Go types into the intermediate
+// typescript AST representation.
+// All configuration of the GoParser should be done before calling
+// 'ToTypescript'.
+// For usage, see 'ExampleGeneration' in convert_test.go.
 func NewGolangParser() (*GoParser, error) {
 	fileSet := token.NewFileSet()
 	config := &packages.Config{
@@ -66,8 +72,18 @@ func (p *GoParser) IncludeCustomDeclaration(mappings map[string]TypeOverride) {
 	}
 }
 
-// IncludeCustom only works for basic literal types and non-parameterized reference types.
-func (p *GoParser) IncludeCustom(mappings map[string]string) error {
+type GolangType = string
+
+// IncludeCustom takes in a remapping of golang types.
+// Both the key and value of the map should be valid golang types.
+// The key is the type to override, and the value is the new type.
+// Typescript will be generated with the new type.
+//
+// Only named types can be overridden.
+// Examples:
+// "github.com/your/repo/pkg.ExampleType": "string"
+// "time.Time": "string"
+func (p *GoParser) IncludeCustom(mappings map[GolangType]GolangType) error {
 	for k, v := range mappings {
 		// Make sure it parses
 		_, err := parseExpression(v)
@@ -114,6 +130,7 @@ func (p *GoParser) Include(directory string, generate bool) error {
 }
 
 // ToTypescript translates the Go types into the intermediate typescript AST
+// The returned typescript object can be mutated before serializing.
 func (p *GoParser) ToTypescript() (*Typescript, error) {
 	typescript := &Typescript{
 		typescriptNodes: make(map[string]*typescriptNode),

convert_test.go

@@ -8,6 +8,7 @@ package guts_test
 
 import (
 	"flag"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -19,6 +20,42 @@ import (
 	"github.com/coder/guts/config"
 )
 
+func ExampleNewGolangParser() {
+	// gen will convert the golang package to the typescript AST.
+	// Configure it before calling ToTypescript().
+	gen, _ := guts.NewGolangParser()
+
+	// Pass in the directory of the package you want to convert.
+	// You can mark a package as 'false' to include it as a reference, but not
+	// generate types for it.
+	_ = gen.Include("github.com/coder/guts/testdata/generics", true)
+
+	// Default type mappings are useful, feel free to add your own
+	gen.IncludeCustomDeclaration(config.StandardMappings())
+	_ = gen.IncludeCustom(map[string]string{
+		// To configure a custom type for a golang type, use the full package path.
+		"github.com/coder/guts/testdata/generics.ExampleType": "string",
+		// You can use golang type syntax to specify a type.
+		"github.com/coder/guts/testdata/generics.AnotherExampleType": "map[string]*string",
+	})
+
+	// ts is the typescript AST. It can be mutated before serializing.
+	ts, _ := gen.ToTypescript()
+
+	ts.ApplyMutations(
+		// Generates a constant which lists all enum values.
+		config.EnumLists,
+		// Adds 'readonly' to all interface fields.
+		config.ReadOnly,
+		// Adds 'export' to all top level types.
+		config.ExportTypes,
+	)
+
+	output, _ := ts.Serialize()
+	// Output is the typescript file text
+	fmt.Println(output)
+}
+
 // updateGoldenFiles is a flag that can be set to update golden files.
 var updateGoldenFiles = flag.Bool("update", false, "Update golden files")