github.com/alex123012/deckhouse-controller-tools@v0.0.0-20230510090815-d594daf1af8c/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