README

cloudeng.io/go/cmd/goannotate

CircleCI Go Report Card

Usage of goannotate

goannotate provides a configurable and extensible set of annotators that can be used to add/remove statements from large bodies of go source code.

Command line flags

-annotation string
    annotation to be applied
-config string
    yaml configuration file (default "config.yaml")
-list
    list available annotators
-list-config
    list available annotations and their configurations
-verbose
    display verbose debug info
-write-dir string
    if set, specify an alternate directory to write modified files to, otherwise files are modified in place.

Available annotators

cloudeng.io/go/cmd/goannotate/annotators.AddLogCall: AddLogCall is an annotator to add function calls that are intended to log entry and exit from functions. The calls will be added as the first statement in the specified function.

type:                name of annotator type.
name:                name of annotation.
packages:            packages to be annotated
concurrency:         the number of goroutines to use, zero for a sensible
                     default.
interfaces:          list of interfaces whose implementations are to be annoated.
functions:           list of functions that are to be annotated.
includeMethods:      if set, methods as well as functions that match the function
                     spec are annotated
atLeastStatements:   the number of statements that must be present in a function
                     in order for it to be annotated.
noAnnotationComment: do not annotate functions that contain this comment
callGenerator:       the spec for the function call to be generated

  Available Call Generators:

  cloudeng.io/go/cmd/goannotate/annotators/functions.LogCallWithContext
  cloudeng.io/go/cmd/goannotate/annotators/functions.SimpleLogCall

  cloudeng.io/go/cmd/goannotate/annotators/functions.LogCallWithContext:
  LogCallWithContext provides a functon call generator for generating calls to
  functions with the following signature:

    func (ctx <contextType>, functionName, format string, arguments ...interface{}) func(ctx <contextType>, format string, namedResults ...interface{})

  These are invoked via defer as show below:

    defer <call>(ctx, "<function-name>",  "<format>", <parameters>....)(ctx, "<format>", <results>)

  The actual type of the context is determined by the ContextType configuration
  field. The parameters and named results are captured and passed to the logging
  call according to cloudeng.io/go/derive.ArgsForParams and ArgsForResults.
  The logging function must return a function that is defered to capture named
  results and log them on function exit.
    type:         name of annotator type.
    importPath:   import path for the logging function.
    functionName: name of the function to be invoked.
    contextType:  type for the context parameter and result.

  cloudeng.io/go/cmd/goannotate/annotators/functions.SimpleLogCall:
  SimpleLogCall provides a functon call generator for generating calls to
  functions with the same signature log.Callf and fmt.Printf.
    type:         name of annotator type.
    importPath:   import path for the logging function.
    functionName: name of the function to be invoked.
    contextType:  type for the context parameter and result.

cloudeng.io/go/cmd/goannotate/annotators.EnsureCopyrightAndLicense: an annotator that ensures that a copyright and license notice is present at the top of all files. It will not remove existing notices.

type:            name of annotator type.
name:            name of annotation.
packages:        packages to be annotated
concurrency:     the number of goroutines to use, zero for a sensible default.
copyright:       desired copyright notice.
exclusions:      regular expressions for files to be excluded.
license:         desired license notice.
updateCopyright: set to true to update existing copyright notice
updateLicense:   set to true to update existing license notice

cloudeng.io/go/cmd/goannotate/annotators.RmLogCall: an annotator that removes instances of calls to functions.

type:           name of annotator type.
name:           name of annotation.
packages:       packages to be annotated
concurrency:    the number of goroutines to use, zero for a sensible default.
interfaces:     list of interfaces whose implementations are to be annoated.
functions:      list of functions that are to be annotated.
includeMethods: if set, methods as well as functions that match the function
                spec are annotated
functionNameRE: the function call (regexp) to be removed
comment:        optional comment that must appear in the comments associated
                with the function call if it is to be removed.
deferred:       if set requires that the function to be removed must be defered.
Expand ▾ Collapse ▴

Documentation

Overview

    Usage of goannotate:

    goannotate provides a configurable and extensible set of annotators that can be used to add/remove statements from large bodies of go source code.

    Command line flags:

    -annotation string
      	annotation to be applied
    -config string
      	yaml configuration file (default "config.yaml")
    -list
      	list available annotators
    -list-config
      	list available annotations and their configurations
    -verbose
      	display verbose debug info
    -write-dir string
      	if set, specify an alternate directory to write modified files to, otherwise files are modified in place.
    

    Available annotators:

    cloudeng.io/go/cmd/goannotate/annotators.AddLogCall: AddLogCall is an annotator to add function calls that are intended to log entry and exit from functions. The calls will be added as the first statement in the specified function.

    type:                name of annotator type.
    name:                name of annotation.
    packages:            packages to be annotated
    concurrency:         the number of goroutines to use, zero for a sensible
                         default.
    interfaces:          list of interfaces whose implementations are to be annoated.
    functions:           list of functions that are to be annotated.
    includeMethods:      if set, methods as well as functions that match the function
                         spec are annotated
    atLeastStatements:   the number of statements that must be present in a function
                         in order for it to be annotated.
    noAnnotationComment: do not annotate functions that contain this comment
    callGenerator:       the spec for the function call to be generated
    
      Available Call Generators:
    
      cloudeng.io/go/cmd/goannotate/annotators/functions.LogCallWithContext
      cloudeng.io/go/cmd/goannotate/annotators/functions.SimpleLogCall
    
      cloudeng.io/go/cmd/goannotate/annotators/functions.LogCallWithContext:
      LogCallWithContext provides a functon call generator for generating calls to
      functions with the following signature:
    
        func (ctx <contextType>, functionName, format string, arguments ...interface{}) func(ctx <contextType>, format string, namedResults ...interface{})
    
      These are invoked via defer as show below:
    
        defer <call>(ctx, "<function-name>",  "<format>", <parameters>....)(ctx, "<format>", <results>)
    
      The actual type of the context is determined by the ContextType configuration
      field. The parameters and named results are captured and passed to the logging
      call according to cloudeng.io/go/derive.ArgsForParams and ArgsForResults.
      The logging function must return a function that is defered to capture named
      results and log them on function exit.
        type:         name of annotator type.
        importPath:   import path for the logging function.
        functionName: name of the function to be invoked.
        contextType:  type for the context parameter and result.
    
      cloudeng.io/go/cmd/goannotate/annotators/functions.SimpleLogCall:
      SimpleLogCall provides a functon call generator for generating calls to
      functions with the same signature log.Callf and fmt.Printf.
        type:         name of annotator type.
        importPath:   import path for the logging function.
        functionName: name of the function to be invoked.
        contextType:  type for the context parameter and result.
    

    cloudeng.io/go/cmd/goannotate/annotators.EnsureCopyrightAndLicense: an annotator that ensures that a copyright and license notice is present at the top of all files. It will not remove existing notices.

    type:            name of annotator type.
    name:            name of annotation.
    packages:        packages to be annotated
    concurrency:     the number of goroutines to use, zero for a sensible default.
    copyright:       desired copyright notice.
    exclusions:      regular expressions for files to be excluded.
    license:         desired license notice.
    updateCopyright: set to true to update existing copyright notice
    updateLicense:   set to true to update existing license notice
    

    cloudeng.io/go/cmd/goannotate/annotators.RmLogCall: an annotator that removes instances of calls to functions.

    type:           name of annotator type.
    name:           name of annotation.
    packages:       packages to be annotated
    concurrency:    the number of goroutines to use, zero for a sensible default.
    interfaces:     list of interfaces whose implementations are to be annoated.
    functions:      list of functions that are to be annotated.
    includeMethods: if set, methods as well as functions that match the function
                    spec are annotated
    functionNameRE: the function call (regexp) to be removed
    comment:        optional comment that must appear in the comments associated
                    with the function call if it is to be removed.
    deferred:       if set requires that the function to be removed must be defered.
    

    Directories

    Path Synopsis