github.com/myhau/pulumi/pkg/v3@v3.70.2-0.20221116134521-f2775972e587/codegen/go/doc.go (about) 1 // Copyright 2016-2020, Pulumi Corporation. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // Pulling out some of the repeated strings tokens into constants would harm readability, so we just ignore the 16 // goconst linter's warning. 17 // 18 // nolint: lll, goconst 19 package gen 20 21 import ( 22 "fmt" 23 "os" 24 "strings" 25 26 "github.com/golang/glog" 27 "github.com/pulumi/pulumi/pkg/v3/codegen" 28 "github.com/pulumi/pulumi/pkg/v3/codegen/schema" 29 ) 30 31 const pulumiSDKVersion = "v3" 32 33 // DocLanguageHelper is the Go-specific implementation of the DocLanguageHelper. 34 type DocLanguageHelper struct { 35 packages map[string]*pkgContext 36 } 37 38 var _ codegen.DocLanguageHelper = DocLanguageHelper{} 39 40 // GetDocLinkForPulumiType returns the doc link for a Pulumi type. 41 func (d DocLanguageHelper) GetDocLinkForPulumiType(pkg *schema.Package, typeName string) string { 42 version := pulumiSDKVersion 43 if info, ok := pkg.Language["go"].(GoPackageInfo); ok { 44 if info.PulumiSDKVersion == 1 { 45 return fmt.Sprintf("https://pkg.go.dev/github.com/pulumi/pulumi/sdk/go/pulumi?tab=doc#%s", typeName) 46 } 47 if info.PulumiSDKVersion != 0 { 48 version = fmt.Sprintf("v%d", info.PulumiSDKVersion) 49 } 50 } 51 return fmt.Sprintf("https://pkg.go.dev/github.com/pulumi/pulumi/sdk/%s/go/pulumi?tab=doc#%s", version, typeName) 52 } 53 54 // GetDocLinkForResourceType returns the godoc URL for a type belonging to a resource provider. 55 func (d DocLanguageHelper) GetDocLinkForResourceType(pkg *schema.Package, moduleName string, typeName string) string { 56 path := fmt.Sprintf("%s/%s", packageName(pkg), moduleName) 57 typeNameParts := strings.Split(typeName, ".") 58 typeName = typeNameParts[len(typeNameParts)-1] 59 typeName = strings.TrimPrefix(typeName, "*") 60 61 moduleVersion := "" 62 if pkg.Version != nil { 63 if pkg.Version.Major > 1 { 64 moduleVersion = fmt.Sprintf("v%d/", pkg.Version.Major) 65 } 66 } 67 68 return fmt.Sprintf("https://pkg.go.dev/github.com/pulumi/pulumi-%s/sdk/%sgo/%s?tab=doc#%s", pkg.Name, moduleVersion, path, typeName) 69 } 70 71 // GetDocLinkForResourceInputOrOutputType returns the godoc URL for an input or output type. 72 func (d DocLanguageHelper) GetDocLinkForResourceInputOrOutputType(pkg *schema.Package, moduleName, typeName string, input bool) string { 73 link := d.GetDocLinkForResourceType(pkg, moduleName, typeName) 74 if !input { 75 return link + "Output" 76 } 77 return link + "Args" 78 } 79 80 // GetDocLinkForFunctionInputOrOutputType returns the doc link for an input or output type of a Function. 81 func (d DocLanguageHelper) GetDocLinkForFunctionInputOrOutputType(pkg *schema.Package, moduleName, typeName string, input bool) string { 82 link := d.GetDocLinkForResourceType(pkg, moduleName, typeName) 83 if !input { 84 return link 85 } 86 return link + "Args" 87 } 88 89 // GetLanguageTypeString returns the Go-specific type given a Pulumi schema type. 90 func (d DocLanguageHelper) GetLanguageTypeString(pkg *schema.Package, moduleName string, t schema.Type, input bool) string { 91 modPkg, ok := d.packages[moduleName] 92 if !ok { 93 glog.Errorf("cannot calculate type string for type %q. could not find a package for module %q", t.String(), moduleName) 94 os.Exit(1) 95 } 96 return modPkg.typeString(t) 97 } 98 99 // GeneratePackagesMap generates a map of Go packages for resources, functions and types. 100 func (d *DocLanguageHelper) GeneratePackagesMap(pkg *schema.Package, tool string, goInfo GoPackageInfo) { 101 d.packages = generatePackageContextMap(tool, pkg, goInfo, nil) 102 } 103 104 // GetPropertyName returns the property name specific to Go. 105 func (d DocLanguageHelper) GetPropertyName(p *schema.Property) (string, error) { 106 return strings.Title(p.Name), nil 107 } 108 109 // GetEnumName returns the enum name specific to Go. 110 func (d DocLanguageHelper) GetEnumName(e *schema.Enum, typeName string) (string, error) { 111 name := fmt.Sprintf("%v", e.Value) 112 if e.Name != "" { 113 name = e.Name 114 } 115 return makeSafeEnumName(name, typeName) 116 } 117 118 func (d DocLanguageHelper) GetFunctionName(modName string, f *schema.Function) string { 119 funcName := tokenToName(f.Token) 120 pkg, ok := d.packages[modName] 121 if !ok { 122 return funcName 123 } 124 125 if override, ok := pkg.functionNames[f]; ok { 126 funcName = override 127 } 128 return funcName 129 } 130 131 // GetResourceFunctionResultName returns the name of the result type when a function is used to lookup 132 // an existing resource. 133 func (d DocLanguageHelper) GetResourceFunctionResultName(modName string, f *schema.Function) string { 134 funcName := d.GetFunctionName(modName, f) 135 return funcName + "Result" 136 } 137 138 func (d DocLanguageHelper) GetMethodName(m *schema.Method) string { 139 return Title(m.Name) 140 } 141 142 func (d DocLanguageHelper) GetMethodResultName(pkg *schema.Package, modName string, r *schema.Resource, 143 m *schema.Method) string { 144 145 if info, ok := pkg.Language["go"].(GoPackageInfo); ok { 146 if info.LiftSingleValueMethodReturns && m.Function.Outputs != nil && len(m.Function.Outputs.Properties) == 1 { 147 t := m.Function.Outputs.Properties[0].Type 148 modPkg, ok := d.packages[modName] 149 if !ok { 150 glog.Errorf("cannot calculate type string for type %q. could not find a package for module %q", 151 t.String(), modName) 152 os.Exit(1) 153 } 154 return modPkg.outputType(t) 155 } 156 } 157 return fmt.Sprintf("%s%sResultOutput", rawResourceName(r), d.GetMethodName(m)) 158 } 159 160 // GetModuleDocLink returns the display name and the link for a module. 161 func (d DocLanguageHelper) GetModuleDocLink(pkg *schema.Package, modName string) (string, string) { 162 var displayName string 163 var link string 164 if modName == "" { 165 displayName = packageName(pkg) 166 } else { 167 displayName = fmt.Sprintf("%s/%s", packageName(pkg), modName) 168 } 169 link = d.GetDocLinkForResourceType(pkg, modName, "") 170 return displayName, link 171 }