attr.go

     1  // Copyright 2022 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package slog
     6  
     7  import (
     8  	"time"
     9  )
    10  
    11  // An Attr is a key-value pair.
    12  type Attr struct {
    13  	Key   string
    14  	Value Value
    15  }
    16  
    17  // String returns an Attr for a string value.
    18  func String(key, value string) Attr {
    19  	return Attr{key, StringValue(value)}
    20  }
    21  
    22  // Int64 returns an Attr for an int64.
    23  func Int64(key string, value int64) Attr {
    24  	return Attr{key, Int64Value(value)}
    25  }
    26  
    27  // Int converts an int to an int64 and returns
    28  // an Attr with that value.
    29  func Int(key string, value int) Attr {
    30  	return Int64(key, int64(value))
    31  }
    32  
    33  // Uint64 returns an Attr for a uint64.
    34  func Uint64(key string, v uint64) Attr {
    35  	return Attr{key, Uint64Value(v)}
    36  }
    37  
    38  // Float64 returns an Attr for a floating-point number.
    39  func Float64(key string, v float64) Attr {
    40  	return Attr{key, Float64Value(v)}
    41  }
    42  
    43  // Bool returns an Attr for a bool.
    44  func Bool(key string, v bool) Attr {
    45  	return Attr{key, BoolValue(v)}
    46  }
    47  
    48  // Time returns an Attr for a [time.Time].
    49  // It discards the monotonic portion.
    50  func Time(key string, v time.Time) Attr {
    51  	return Attr{key, TimeValue(v)}
    52  }
    53  
    54  // Duration returns an Attr for a [time.Duration].
    55  func Duration(key string, v time.Duration) Attr {
    56  	return Attr{key, DurationValue(v)}
    57  }
    58  
    59  // Group returns an Attr for a Group [Value].
    60  // The first argument is the key; the remaining arguments
    61  // are converted to Attrs as in [Logger.Log].
    62  //
    63  // Use Group to collect several key-value pairs under a single
    64  // key on a log line, or as the result of LogValue
    65  // in order to log a single value as multiple Attrs.
    66  func Group(key string, args ...any) Attr {
    67  	return Attr{key, GroupValue(argsToAttrSlice(args)...)}
    68  }
    69  
    70  // GroupAttrs returns an Attr for a Group [Value]
    71  // consisting of the given Attrs.
    72  //
    73  // GroupAttrs is a more efficient version of [Group]
    74  // that accepts only [Attr] values.
    75  func GroupAttrs(key string, attrs ...Attr) Attr {
    76  	return Attr{key, GroupValue(attrs...)}
    77  }
    78  
    79  func argsToAttrSlice(args []any) []Attr {
    80  	var (
    81  		attr  Attr
    82  		attrs []Attr
    83  	)
    84  	for len(args) > 0 {
    85  		attr, args = argsToAttr(args)
    86  		attrs = append(attrs, attr)
    87  	}
    88  	return attrs
    89  }
    90  
    91  // Any returns an Attr for the supplied value.
    92  // See [AnyValue] for how values are treated.
    93  func Any(key string, value any) Attr {
    94  	return Attr{key, AnyValue(value)}
    95  }
    96  
    97  // Equal reports whether a and b have equal keys and values.
    98  func (a Attr) Equal(b Attr) bool {
    99  	return a.Key == b.Key && a.Value.Equal(b.Value)
   100  }
   101  
   102  func (a Attr) String() string {
   103  	return a.Key + "=" + a.Value.String()
   104  }
   105  
   106  // isEmpty reports whether a has an empty key and a nil value.
   107  // That can be written as Attr{} or Any("", nil).
   108  func (a Attr) isEmpty() bool {
   109  	return a.Key == "" && a.Value.num == 0 && a.Value.any == nil
   110  }
   111
View as plain text