api

Documentation

Overview

Package api contains routines to "build up" a "results" datastructure that can easily mapped to JSON (or other) and returned to the client. There are also various JSON manipulation routines.

Index

• func EscapeJSONString(ctrl []byte) (esc []byte)
• func FatalJSONMsg(apiVer string, errMsg Msg) string
• func GetJSONOutput(apiVer string, context string, kind string, verbosity string, fields []string, ...) (string, bool)
• func JSONIndentLevel() int
• func JSONPrefix() string
• func JSONRaw() bool
• func PrettyJSON(b []byte, fmt ...string) (string, error)
• func SetJSONIndentLevel(level int)
• func SetJSONPrefix(pfx string)
• func SetJSONRaw(b bool)
• func SetStoredFatalError(msg Msg)
• func SetStoredNonFatalWarning(msg Msg, defCode ...int)
• func SetStoredNote(msg Msg, defCode ...int)
• type Msg
  • func NewMsg(msg string, code int, level string) Msg

Functions

func EscapeJSONString

func EscapeJSONString(ctrl []byte) (esc []byte)

EscapeJSONString escapes control chars in a string so JSON likes em

func FatalJSONMsg

func FatalJSONMsg(apiVer string, errMsg Msg) string

FatalJSONMsg is for cases where Marshal is failing so we need some JSON we can dump on the output... if we get to this level then what we're generating is a valid JSON error basically (shouldn't happen)

func GetJSONOutput

func GetJSONOutput(apiVer string, context string, kind string, verbosity string, fields []string, items []interface{}) (string, bool)

GetJSONOutput takes the various things needed from a DVLN api call and combines pertinent details into a JSON "results" string (pretty or not depending upon settings) and returns that representation to the caller. It will return a boolean indicating if a fatal occurred (if so the err will be encoded in the JSON being returned already, print the string and exit non-zero basically if you get false back in the boolean)

func JSONIndentLevel

func JSONIndentLevel() int

JSONIndentLevel can be used to get the current indentation level for each "step" in PrettyJSON() output (defaults to 2 currently)

func JSONPrefix

func JSONPrefix() string

JSONPrefix can be used to get the current prefix used for any JSON string being formatted via the PrettyJSON() routine

func JSONRaw

func JSONRaw() bool

JSONRaw can be used to determine if we're in raw JSON output mode (true) or not, true means the PrettyJSON() routine will do nothing

func PrettyJSON

func PrettyJSON(b []byte, fmt ...string) (string, error)

PrettyJSON pretty prints JSON data. Provide the data and that can be followed by two optional arguments, a prefix string and an indent level (both of which are strings). If neither is provided then no prefix used and indent of two spaces is the default (see cfgfile:jsonprefix, cfgfile:jsonindent and the related DVLN_JSONPREFIX, DVLN_JSONINDENT to adjust indentation and prefix as well as cfgfile:jsonraw and DVLN_JSONRAW for skipping pretty printing)

func SetJSONIndentLevel

func SetJSONIndentLevel(level int)

SetJSONIndentLevel can be used to change the indentation level for each "step" in pretty JSOn output being formatted via PrettyJSON()

func SetJSONPrefix

func SetJSONPrefix(pfx string)

SetJSONPrefix can be used to change the string prefix for any JSON string being formatted via the PrettyJSON() routine.

func SetJSONRaw

func SetJSONRaw(b bool)

SetJSONRaw can be used to change the raw JSON output mode so that the JSON is cleaned up and indented so it's human readable with various lines or if it's just "raw" and lumped together....if raw if false then other sections of this module use PrettyJSON to pretty it up.

func SetStoredFatalError

func SetStoredFatalError(msg Msg)

SetStoredFatalError allows one to store a fatal error which will be picked up by any 'api' pkg routine that is building a JSON message... if this is set the message field must NOT be empty (at least) and it will result in a non-zero exit and a -1 'id' field setting in the JSON output along with the "error" JSON field being set

func SetStoredNonFatalWarning

func SetStoredNonFatalWarning(msg Msg, defCode ...int)

SetStoredNonFatalWarning allows one to store a warning message which will be added to any JSON generated via the 'api' package. It's mostly just informative though as it will still encode and return all other results and items in the JSON structure but at least the client can see something of interest might need some follow up with the server hosting side before it becomes a fatal class error perhaps.

func SetStoredNote

func SetStoredNote(msg Msg, defCode ...int)

SetStoredNote allows one to store a "note" message which will be added to any JSON generated via the 'api' package. This is informative and can be used by the client as they see fit. Example, output is logged to some tmp logfile and a note is being attached as to where that log file is. Use api.NewMsg to create a Msg and note that the defCode for dvln should probably be out.DefaultErrCode() (although for notes the code isn't really an error, but it's ok)

Types

type Msg

type Msg struct {
	Message string `json:"message"`
	Code    int    `json:"code,omitempty"`
	Level   string `json:"level,omitempty"`
}

Msg is used typically to store an API error or warning message, set up the basic data and use SetStoredFatalError(), SetStoredNonFatalWarning() and SetStoredNote() routines to stash these.

func NewMsg

func NewMsg(msg string, code int, level string) Msg

NewMsg creates a Msg struct for use in errors and warnings such that they can be stored in JSON format when it is finally dumped