github.com/go-graphite/carbonapi@v0.17.0/doc/development/functions.md (about)

     1  How to add a new function
     2  ===
     3  
     4  What you should take into account
     5  ---
     6  
     7  1. Each function (that behaves differently) must be in a separate file
     8  2. Functions should be stored in `expr/functions/$function_name$` directory.
     9  3. Function-specific tests should be also stored in `expr/functions/$function_name$`
    10  4. Function type should be called exactly the same as package
    11  5. Function type must implement `interfaces.Function`. There is helper `interfaces.FunctionBase` that implements basic `SetEvaluator` and `GetEvaluator` functions
    12  6. There is a way to auto-generate `Description` method from graphite-web's /functions handler output: `scripts/json_to_go_struct.sh`. Script is very hackish, but works most of the time.
    13  7. Each function must have valid description, type, name, etc. Ideally description should contain examples, but that's not a strict requirement
    14  8. All functions and it's aliases must be registered in `func init()`.
    15  9. To create new `expr/functions/glue.go` you can do `cd expr/functions/; go generate > glue.go.new; mv glue.go.new glue.go`. This will automatically add all necessary imports.
    16  
    17  How functions works
    18  ===
    19  
    20  `expr/metadata`
    21  ---
    22  Contains all metadata as a static global variables.
    23  
    24  `func RegisterFunction(name string, function interfaces.Function)` - registers function in metadata
    25  
    26  `FunctionMD` - contains metadata about all known functions
    27  
    28  `FunctionDescriptions map[string]*types.FunctionDescription` - contains descriptions of all known functions
    29  
    30  `FunctionDescriptionsGrouped map[string]map[string]*types.FunctionDescription` - contains descriptions of all known functions, grouped by function group
    31  
    32  `expr/expr.go`
    33  ---
    34  
    35  Contains `EvalExpr` - main expression parser, plus `RewriteExpr` - rewrite phase of expression parsing.
    36  
    37  `EvalExpr` always uses `metadata.FunctionMD` to get list of known functions.
    38  
    39  Functions registered by importing `expr/functions/glue.go`
    40  
    41  `expr/functions/$FUNCTION_NAME$/function.go`
    42  ---
    43  
    44  Contains actual function body.
    45  
    46  You must define following structs and functions:
    47  
    48  * `type $function_name$ struct` - it must statisfy `interfaces.Function`
    49  * `func GetOrder() interfaces.Order` - must return either `interfaces.Any` or `interfaces.Last` - this will define order in which functions will be initialized. Currently the only known case when you might want to return `interfaces.Last` is when you redefine other functions.
    50  * `func New(configFile string) []interfaces.FunctioMetadata` - this function will be called by `expr/functions/glue.go` during initialization. It must return metadata filled for all functions and their aliases. It will also receive config file name if user specify any. It's up to function's developer how to parse it (or if it's needed). Currently the only case where carbonapi uses that - proxy unknown functions to graphite-web where it's specified where to find graphite-web instances.
    51  
    52  
    53  `expr/functions/glue.go`
    54  ---
    55  
    56  Autogenerated by `expr/functions/gen.go`. Calls `New(configFileName)` for each and every function. If user specified custom config, it will be passed to `New()` method.