github.com/TheSpiritXIII/controller-tools@v0.14.1/pkg/loader/doc.go (about) 1 /* 2 Copyright 2019 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 // Package loader defines helpers for loading packages from sources. It wraps 18 // go/packages, allow incremental loading of source code and manual control 19 // over which packages get type-checked. This allows for faster loading in 20 // cases where you don't actually care about certain imports. 21 // 22 // Because it uses go/packages, it's modules-aware, and works in both modules- 23 // and non-modules environments. 24 // 25 // # Loading 26 // 27 // The main entrypoint for loading is LoadRoots, which traverse the package 28 // graph starting at the given patterns (file, package, path, or ...-wildcard, 29 // as one might pass to go list). Packages beyond the roots can be accessed 30 // via the Imports() method. Packages are initially loaded with export data 31 // paths, filenames, and imports. 32 // 33 // Packages are suitable for comparison, as each unique package only ever has 34 // one *Package object returned. 35 // 36 // # Syntax and TypeChecking 37 // 38 // ASTs and type-checking information can be loaded with NeedSyntax and 39 // NeedTypesInfo, respectively. Both are idempotent -- repeated calls will 40 // simply re-use the cached contents. Note that NeedTypesInfo will *only* type 41 // check the current package -- if you want to type-check imports as well, 42 // you'll need to type-check them first. 43 // 44 // # Reference Pruning and Recursive Checking 45 // 46 // In order to type-check using only the packages you care about, you can use a 47 // TypeChecker. TypeChecker will visit each top-level type declaration, 48 // collect (optionally filtered) references, and type-check references 49 // packages. 50 // 51 // # Errors 52 // 53 // Errors can be added to each package. Use ErrFromNode to create an error 54 // from an AST node. Errors can then be printed (complete with file and 55 // position information) using PrintErrors, optionally filtered by error type. 56 // It's generally a good idea to filter out TypeErrors when doing incomplete 57 // type-checking with TypeChecker. You can use MaybeErrList to return multiple 58 // errors if you need to return an error instead of adding it to a package. 59 // AddError will later unroll it into individual errors. 60 package loader