logger

type Entity interface {
	// Name returns the logger name.
	Name() string

	// Time returns the log time.
	Time() time.Time

	// TimeString returns the log time string formatted with the default time format.
	TimeString() string

	// Level returns the log level.
	Level() Level

	// Message returns the log message.
	Message() string

	// HasFields determines whether the log contains fields.
	HasFields() bool

	// Fields returns the log fields.
	Fields() map[string]interface{}

	// HasContext determines whether the log contains a context.
	HasContext() bool

	// Context returns the log context.
	Context() context.Context

	// HasCaller determines whether the log contains caller information.
	HasCaller() bool

	// Caller returns the log caller.
	// If it is not enabled, an empty string is always returned.
	Caller() string

	// HasStack determines whether the log contains call stack information.
	HasStack() bool

	// Stack returns the call stack information at the logging location.
	// Returns nil if not enabled.
	Stack() []string

	// Buffer returns the entity buffer instance.
	Buffer() *bytes.Buffer
}

type FormatOutput interface {
	// Format formats the given log entity and returns the writer to which the log needs to be written.
	// If the error returned is not empty, the log will be discarded and the registered log hook will
	// not be triggered. We will output the error information to os.Stderr.
	// If the returned log writer is nil, the default log writer is used.
	Format(e Entity, b *bytes.Buffer) (io.Writer, error)
}

type FormatOutputFunc func(e Entity, b *bytes.Buffer) (io.Writer, error)

type Formatter interface {
	// Format formats the given log entity into character data and writes it to
	// the given buffer. If the error returned is not empty, the log will be discarded
	// and the registered log hook will not be triggered. We will output the error
	// information to os.Stderr.
	Format(Entity, *bytes.Buffer) error
}

type FormatterFunc func(Entity, *bytes.Buffer) error

type Hook interface {
	// Levels returns the log levels associated with the current log hook.
	// This method is only called once when the log hook is added to the logger.
	// If the returned log levels are empty, the hook will not be added.
	// If there are invalid log level in the returned log levels, it will be automatically ignored.
	Levels() []Level

	// Fire receives the summary of the log and performs the full logic of the log hook.
	// This method is called in parallel, and each log is called once.
	// Errors returned by this method are handled by the internal error handler (output to standard
	// error by default), and any errors returned will not prevent log writing.
	// The log summary instance received by this method will be cleaned up and recycled after the
	// log writing is completed. The log hook program should not hold the log summary instance.
	Fire(Summary) error
}

type HookBag interface {
	Hook

	// Add adds the given log hook to the current hook bag.
	Add(Hook)
}

type JSONFormatterObjectPool interface {
	// GetObject creates and returns a new JSON log object from the given log Entity.
	// The returned object must be JSON-Serializable, otherwise the formatter will fail to work.
	GetObject(Entity) interface{}

	// PutObject recycles json serialized objects.
	// This method must clean up the log data bound to the object to free memory.
	PutObject(interface{})
}

type Level uint32

type Log interface {
	// Name returns the logger name.
	Name() string

	// WithMessagePrefix adds a fixed message prefix to the current log.
	WithMessagePrefix(string) Log

	// WithField adds the given extended data to the log.
	WithField(string, interface{}) Log

	// WithError adds the given error to the log.
	// This method is relative to WithField("error", error).
	WithError(error) Log

	// WithFields adds the given multiple extended data to the log.
	WithFields(map[string]interface{}) Log

	// WithFieldPairs adds the given key-value pairs to the log.
	WithFieldPairs(pairs ...interface{}) Log

	// WithContext adds the given context to the log.
	WithContext(context.Context) Log

	// WithCaller forces the caller report of the current log to be enabled.
	WithCaller(...int) Log

	// WithStack adds call stack information to the current log.
	WithStack() Log

	// IsLevelEnabled checks whether the given log level is enabled.
	// Always returns false if the given log level is invalid.
	IsLevelEnabled(Level) bool

	// IsPanicLevelEnabled checks whether the PanicLevel is enabled.
	IsPanicLevelEnabled() bool

	// IsFatalLevelEnabled checks whether the FatalLevel is enabled.
	IsFatalLevelEnabled() bool

	// IsErrorLevelEnabled checks whether the ErrorLevel is enabled.
	IsErrorLevelEnabled() bool

	// IsWarnLevelEnabled checks whether the WarnLevel is enabled.
	IsWarnLevelEnabled() bool

	// IsInfoLevelEnabled checks whether the InfoLevel is enabled.
	IsInfoLevelEnabled() bool

	// IsDebugLevelEnabled checks whether the DebugLevel is enabled.
	IsDebugLevelEnabled() bool

	// IsTraceLevelEnabled checks whether the TraceLevel is enabled.
	IsTraceLevelEnabled() bool

	// Log uses the given parameters to record a log of the specified level.
	// If the given log level is PanicLevel, the given panic function will be
	// called automatically after logging is completed.
	// If the given log level is FatalLevel, the given exit function will be
	// called automatically after logging is completed.
	// If the given log level is invalid, the log will be discarded.
	Log(Level, ...interface{})

	// Logln uses the given parameters to record a log of the specified level.
	// If the given log level is PanicLevel, the given panic function will be
	// called automatically after logging is completed.
	// If the given log level is FatalLevel, the given exit function will be
	// called automatically after logging is completed.
	// If the given log level is invalid, the log will be discarded.
	Logln(Level, ...interface{})

	// Logf uses the given parameters to record a log of the specified level.
	// If the given log level is PanicLevel, the given panic function will be
	// called automatically after logging is completed.
	// If the given log level is FatalLevel, the given exit function will be
	// called automatically after logging is completed.
	// If the given log level is invalid, the log will be discarded.
	Logf(Level, string, ...interface{})

	// Trace uses the given parameters to record a TraceLevel log.
	Trace(...interface{})

	// Traceln uses the given parameters to record a TraceLevel log.
	Traceln(...interface{})

	// Tracef uses the given parameters to record a TraceLevel log.
	Tracef(string, ...interface{})

	// Print uses the given parameters to record a TraceLevel log.
	Print(...interface{})

	// Println uses the given parameters to record a TraceLevel log.
	Println(...interface{})

	// Printf uses the given parameters to record a TraceLevel log.
	Printf(string, ...interface{})

	// Debug uses the given parameters to record a DebugLevel log.
	Debug(...interface{})

	// Debugln uses the given parameters to record a DebugLevel log.
	Debugln(...interface{})

	// Debugf uses the given parameters to record a DebugLevel log.
	Debugf(string, ...interface{})

	// Info uses the given parameters to record a InfoLevel log.
	Info(...interface{})

	// Infoln uses the given parameters to record a InfoLevel log.
	Infoln(...interface{})

	// Infof uses the given parameters to record a InfoLevel log.
	Infof(string, ...interface{})

	// Echo uses the given parameters to record a InfoLevel log.
	Echo(...interface{})

	// Echoln uses the given parameters to record a InfoLevel log.
	Echoln(...interface{})

	// Echof uses the given parameters to record a InfoLevel log.
	Echof(string, ...interface{})

	// Warn uses the given parameters to record a WarnLevel log.
	Warn(...interface{})

	// Warnln uses the given parameters to record a WarnLevel log.
	Warnln(...interface{})

	// Warnf uses the given parameters to record a WarnLevel log.
	Warnf(string, ...interface{})

	// Warning uses the given parameters to record a WarnLevel log.
	Warning(...interface{})

	// Warningln uses the given parameters to record a WarnLevel log.
	Warningln(...interface{})

	// Warningf uses the given parameters to record a WarnLevel log.
	Warningf(string, ...interface{})

	// Error uses the given parameters to record a ErrorLevel log.
	Error(...interface{})

	// Errorln uses the given parameters to record a ErrorLevel log.
	Errorln(...interface{})

	// Errorf uses the given parameters to record a ErrorLevel log.
	Errorf(string, ...interface{})

	// Fatal uses the given parameters to record a FatalLevel log.
	// After the log record is completed, the system will automatically call
	// the exit function given in advance.
	Fatal(...interface{})

	// Fatalln uses the given parameters to record a FatalLevel log.
	// After the log record is completed, the system will automatically call
	// the exit function given in advance.
	Fatalln(...interface{})

	// Fatalf uses the given parameters to record a FatalLevel log.
	// After the log record is completed, the system will automatically call
	// the exit function given in advance.
	Fatalf(string, ...interface{})

	// Panic uses the given parameters to record a PanicLevel log.
	// After the log record is completed, the system will automatically call
	// the panic function given in advance.
	Panic(...interface{})

	// Panicln uses the given parameters to record a PanicLevel log.
	// After the log record is completed, the system will automatically call
	// the panic function given in advance.
	Panicln(...interface{})

	// Panicf uses the given parameters to record a PanicLevel log.
	// After the log record is completed, the system will automatically call
	// the panic function given in advance.
	Panicf(string, ...interface{})
}

type Logger interface {
	Log

	// GetLevel returns the current logger level.
	GetLevel() Level

	// SetLevel sets the current logger level.
	// When the given log level is invalid, this method does nothing.
	SetLevel(Level) Logger

	// SetLevelString sets the current logger level by string.
	SetLevelString(s string) error

	// ForceSetLevelString sets the current logger level by string.
	// When the given log level string is invalid, this method does nothing.
	ForceSetLevelString(s string) Logger

	// SetOutput sets the current logger output writer.
	// If the given writer is nil, os.Stdout is used.
	SetOutput(io.Writer) Logger

	// SetLevelOutput sets the current logger level output writer.
	// The level output writer is used to write log data of a given level.
	// If the given writer is nil, the level writer will be disabled.
	SetLevelOutput(Level, io.Writer) Logger

	// SetLevelsOutput sets the current logger levels output writer.
	// The level output writer is used to write log data of a given level.
	// If the given writer is nil, the levels writer will be disabled.
	SetLevelsOutput([]Level, io.Writer) Logger

	// SetOutputInterceptor sets the output interceptor for the current logger.
	// If the given interceptor is nil, the log data is written to the output writer.
	SetOutputInterceptor(func(Summary, io.Writer) (int, error)) Logger

	// SetNowFunc sets the function that gets the current time.
	// If the given function is nil, time.Now is used.
	SetNowFunc(func() time.Time) Logger

	// SetExitFunc sets the exit function of the current logger.
	// If the given function is nil, the exit function is disabled.
	// The exit function is called automatically after the FatalLevel level log is recorded.
	// By default, the exit function we use is os.Exit.
	SetExitFunc(func(int)) Logger

	// SetPanicFunc sets the panic function of the current logger.
	// If the given function is nil, the panic function is disabled.
	// The panic function is called automatically after the PanicLevel level log is recorded.
	// By default, the panic function we use is func(s string) { panic(s) }.
	SetPanicFunc(func(string)) Logger

	// SetFormatter sets the log formatter for the current logger.
	// If the given log formatter is nil, we will record the log in JSON format.
	SetFormatter(Formatter) Logger

	// SetFormatOutput sets the log format output.
	// After setting the format output, the format and output of the logger will be controlled by this structure,
	// and the bound log output and log level output will no longer be used.
	// If format output needs to be disabled, set to nil and the logger will back to the original behavior.
	SetFormatOutput(FormatOutput) Logger

	// SetDefaultTimeFormat sets the default log time format for the current logger.
	// If the given time format is empty string, internal.DefaultTimeFormat is used.
	SetDefaultTimeFormat(string) Logger

	// EnableCaller enables caller reporting on all levels of logs.
	EnableCaller(...int) Logger

	// EnableLevelCaller enables caller reporting on logs of a given level.
	EnableLevelCaller(Level, ...int) Logger

	// EnableLevelsCaller enables caller reporting on logs of the given levels.
	EnableLevelsCaller([]Level, ...int) Logger

	// AddHook adds the given log hook to the current logger.
	AddHook(Hook) Logger

	// AddHookFunc adds the given log hook function to the current logger.
	AddHookFunc([]Level, func(Summary) error) Logger

	// EnableHook enables or disables the log hook.
	EnableHook(bool) Logger

	// AsLog converts current Logger to Log instances, which is unidirectional.
	AsLog() Log

	// AsStandardLogger converts the current logger to a standard library logger instance.
	AsStandardLogger() *stdlog.Logger

	// SetStackPrefixFilter sets the call stack prefix filter rules.
	SetStackPrefixFilter(...string) Logger
}

type Summary interface {
	Entity
	io.Reader

	// Bytes returns the log content bytes.
	// This method returns the content processed by the formatter.
	Bytes() []byte

	// String returns the log content string.
	// This method returns the content processed by the formatter.
	String() string

	// Size returns the log content size.
	Size() int

	// Clone returns a copy of the current log summary (excluding context).
	Clone() Summary

	// CloneWithContext returns a copy of the current log summary and sets its context to the given value.
	CloneWithContext(context.Context) Summary
}

type UnimplementedFormatter struct{}