Commit 26cb4df7 authored by Rob Pike's avatar Rob Pike

log: document

R=rsc
DELTA=26  (17 added, 1 deleted, 8 changed)
OCL=25731
CL=25734
parent 0ea27e34
......@@ -5,10 +5,10 @@
// Rudimentary logging package. Defines a type, Logger, with simple
// methods for formatting output to one or two destinations. Also has
// predefined Loggers accessible through helper functions Stdout[f],
// Stderr[f], Exit[f], and Crash[f].
// Stderr[f], Exit[f], and Crash[f], which are easier to use than creating
// a Logger manually.
// Exit exits when written to.
// Crash causes a crash when written to.
package log
import (
......@@ -18,6 +18,7 @@ import (
"time";
)
// These flags define the properties of the Logger and the output they produce.
const (
// Flags
Lok = iota;
......@@ -35,13 +36,18 @@ const (
lAllBits = Ldate | Ltime | Lmicroseconds | Llongfile | Lshortfile;
)
// Logger represents an active logging object.
type Logger struct {
out0 io.Write;
out1 io.Write;
prefix string;
flag int;
out0 io.Write; // first destination for output
out1 io.Write; // second destination for output; may be nil
prefix string; // prefix to write at beginning of each line
flag int; // properties
}
// NewLogger creates a new Logger. The out0 and out1 variables set the
// destinations to which log data will be written; out1 may be nil.
// The prefix appears at the beginning of each generated log line.
// The flag argument defines the logging properties.
func NewLogger(out0, out1 io.Write, prefix string, flag int) *Logger {
return &Logger{out0, out1, prefix, flag}
}
......@@ -115,7 +121,9 @@ func (l *Logger) formatHeader(ns int64, calldepth int) string {
return h;
}
// The calldepth is provided for generality, although at the moment on all paths it will be 2.
// Output writes the output for a logging event. The string s contains the text to print after
// the time stamp; calldepth is used to recover the PC. It is provided for generality, although
// at the moment on all pre-defined paths it will be 2.
func (l *Logger) Output(calldepth int, s string) {
now := time.Nanoseconds(); // get this early.
newline := "\n";
......@@ -135,44 +143,52 @@ func (l *Logger) Output(calldepth int, s string) {
}
}
// Basic methods on Logger, analogous to Printf and Print
// Logf is analogous to Printf() for a Logger.
func (l *Logger) Logf(format string, v ...) {
l.Output(2, fmt.Sprintf(format, v))
}
// Log is analogouts to Print() for a Logger.
func (l *Logger) Log(v ...) {
l.Output(2, fmt.Sprintln(v))
}
// Helper functions for lightweight simple logging to predefined Loggers.
// Stdout is a helper function for easy logging to stdout. It is analogous to Print().
func Stdout(v ...) {
stdout.Output(2, fmt.Sprint(v))
}
// Stderr is a helper function for easy logging to stderr. It is analogous to Fprint(os.Stderr).
func Stderr(v ...) {
stdout.Output(2, fmt.Sprintln(v))
}
// Stdoutf is a helper functions for easy formatted logging to stdout. It is analogous to Printf().
func Stdoutf(format string, v ...) {
stdout.Output(2, fmt.Sprintf(format, v))
}
// Stderrf is a helper function for easy formatted logging to stderr. It is analogous to Fprintf(os.Stderr).
func Stderrf(format string, v ...) {
stderr.Output(2, fmt.Sprintf(format, v))
}
// Exit is equivalent to Stderr() followed by a call to sys.Exit(1).
func Exit(v ...) {
exit.Output(2, fmt.Sprintln(v))
}
// Exitf is equivalent to Stderrf() followed by a call to sys.Exit(1).
func Exitf(format string, v ...) {
exit.Output(2, fmt.Sprintf(format, v))
}
// Crash is equivalent to Stderrf() followed by a call to panic().
func Crash(v ...) {
crash.Output(2, fmt.Sprintln(v))
}
// Crashf is equivalent to Stderrf() followed by a call to panic().
func Crashf(format string, v ...) {
crash.Output(2, fmt.Sprintf(format, v))
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment