ufmt.gno

  1// Package ufmt provides utility functions for formatting strings, similarly to
  2// the Go package "fmt", of which only a subset is currently supported (hence
  3// the name µfmt - micro fmt). It includes functions like Printf, Sprintf,
  4// Fprintf, and Errorf.
  5// Supported formatting verbs are documented in the Sprintf function.
  6package ufmt
  7
  8import (
  9	"errors"
 10	"io"
 11	"strconv"
 12	"strings"
 13	"unicode/utf8"
 14)
 15
 16// buffer accumulates formatted output as a byte slice.
 17type buffer []byte
 18
 19func (b *buffer) write(p []byte) {
 20	*b = append(*b, p...)
 21}
 22
 23func (b *buffer) writeString(s string) {
 24	*b = append(*b, s...)
 25}
 26
 27func (b *buffer) writeByte(c byte) {
 28	*b = append(*b, c)
 29}
 30
 31func (b *buffer) writeRune(r rune) {
 32	*b = utf8.AppendRune(*b, r)
 33}
 34
 35// printer holds state for formatting operations.
 36type printer struct {
 37	buf buffer
 38}
 39
 40func newPrinter() *printer {
 41	return &printer{}
 42}
 43
 44// Sprint formats using the default formats for its operands and returns the resulting string.
 45// Sprint writes the given arguments with spaces between arguments.
 46func Sprint(a ...any) string {
 47	p := newPrinter()
 48	p.doPrint(a)
 49	return string(p.buf)
 50}
 51
 52// doPrint formats arguments using default formats and writes to printer's buffer.
 53// Spaces are added between arguments.
 54func (p *printer) doPrint(args []any) {
 55	for argNum, arg := range args {
 56		if argNum > 0 {
 57			p.buf.writeRune(' ')
 58		}
 59
 60		switch v := arg.(type) {
 61		case string:
 62			p.buf.writeString(v)
 63		case (interface{ String() string }):
 64			p.buf.writeString(v.String())
 65		case error:
 66			p.buf.writeString(v.Error())
 67		case float64:
 68			p.buf.writeString(Sprintf("%f", v))
 69		case int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64:
 70			p.buf.writeString(Sprintf("%d", v))
 71		case bool:
 72			if v {
 73				p.buf.writeString("true")
 74			} else {
 75				p.buf.writeString("false")
 76			}
 77		case nil:
 78			p.buf.writeString("<nil>")
 79		default:
 80			p.buf.writeString("(unhandled)")
 81		}
 82	}
 83}
 84
 85// doPrintln appends a newline after formatting arguments with doPrint.
 86func (p *printer) doPrintln(a []any) {
 87	p.doPrint(a)
 88	p.buf.writeByte('\n')
 89}
 90
 91// Sprintf offers similar functionality to Go's fmt.Sprintf, or the sprintf
 92// equivalent available in many languages, including C/C++.
 93// The number of args passed must exactly match the arguments consumed by the format.
 94// A limited number of formatting verbs and features are currently supported.
 95//
 96// Supported verbs:
 97//
 98//	%s: Places a string value directly.
 99//	    If the value implements the interface interface{ String() string },
100//	    the String() method is called to retrieve the value. Same about Error()
101//	    string.
102//	%c: Formats the character represented by Unicode code point
103//	%d: Formats an integer value using package "strconv".
104//	    Currently supports only uint, uint64, int, int64.
105//	%f: Formats a float value, with a default precision of 6.
106//	%e: Formats a float with scientific notation; 1.23456e+78
107//	%E: Formats a float with scientific notation; 1.23456E+78
108//	%F: The same as %f
109//	%g: Formats a float value with %e for large exponents, and %f with full precision for smaller numbers
110//	%G: Formats a float value with %G for large exponents, and %F with full precision for smaller numbers
111//	%t: Formats a boolean value to "true" or "false".
112//	%x: Formats an integer value as a hexadecimal string.
113//	    Currently supports only uint8, []uint8, [32]uint8.
114//	%c: Formats a rune value as a string.
115//	    Currently supports only rune, int.
116//	%q: Formats a string value as a quoted string.
117//	%T: Formats the type of the value.
118//	%v: Formats the value with a default representation appropriate for the value's type
119//	    - nil: <nil>
120//	    - bool: true/false
121//	    - integers: base 10
122//	    - float64: %g format
123//	    - string: verbatim
124//	    - types with String()/Error(): method result
125//	    - others: (unhandled)
126//	%%: Outputs a literal %. Does not consume an argument.
127//
128// Unsupported verbs or type mismatches produce error strings like "%!d(string=foo)".
129func Sprintf(format string, a ...any) string {
130	p := newPrinter()
131	p.doPrintf(format, a)
132	return string(p.buf)
133}
134
135// doPrintf parses the format string and writes formatted arguments to the buffer.
136func (p *printer) doPrintf(format string, args []any) {
137	sTor := []rune(format)
138	end := len(sTor)
139	argNum := 0
140	argLen := len(args)
141
142	for i := 0; i < end; {
143		isLast := i == end-1
144		c := sTor[i]
145
146		if isLast || c != '%' {
147			// we don't check for invalid format like a one ending with "%"
148			p.buf.writeRune(c)
149			i++
150			continue
151		}
152
153		verb := sTor[i+1]
154		if verb == '%' {
155			p.buf.writeRune('%')
156			i += 2
157			continue
158		}
159
160		if argNum >= argLen {
161			panic("ufmt: not enough arguments")
162		}
163		arg := args[argNum]
164		argNum++
165
166		switch verb {
167		case 'v':
168			writeValue(p, verb, arg)
169		case 's':
170			writeString(p, verb, arg)
171		case 'c':
172			writeChar(p, verb, arg)
173		case 'd':
174			writeInt(p, verb, arg)
175		case 'e', 'E', 'f', 'F', 'g', 'G':
176			writeFloat(p, verb, arg)
177		case 't':
178			writeBool(p, verb, arg)
179		case 'x':
180			writeHex(p, verb, arg)
181		case 'q':
182			writeQuotedString(p, verb, arg)
183		case 'T':
184			writeType(p, arg)
185		// % handled before, as it does not consume an argument
186		default:
187			p.buf.writeString("(unhandled verb: %" + string(verb) + ")")
188		}
189
190		i += 2
191	}
192
193	if argNum < argLen {
194		panic("ufmt: too many arguments")
195	}
196}
197
198// writeValue handles %v formatting
199func writeValue(p *printer, verb rune, arg any) {
200	switch v := arg.(type) {
201	case nil:
202		p.buf.writeString("<nil>")
203	case bool:
204		writeBool(p, verb, v)
205	case int:
206		p.buf.writeString(strconv.Itoa(v))
207	case int8:
208		p.buf.writeString(strconv.Itoa(int(v)))
209	case int16:
210		p.buf.writeString(strconv.Itoa(int(v)))
211	case int32:
212		p.buf.writeString(strconv.Itoa(int(v)))
213	case int64:
214		p.buf.writeString(strconv.Itoa(int(v)))
215	case uint:
216		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
217	case uint8:
218		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
219	case uint16:
220		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
221	case uint32:
222		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
223	case uint64:
224		p.buf.writeString(strconv.FormatUint(v, 10))
225	case float64:
226		p.buf.writeString(strconv.FormatFloat(v, 'g', -1, 64))
227	case string:
228		p.buf.writeString(v)
229	case []byte:
230		p.buf.write(v)
231	case []rune:
232		p.buf.writeString(string(v))
233	case (interface{ String() string }):
234		p.buf.writeString(v.String())
235	case error:
236		p.buf.writeString(v.Error())
237	default:
238		p.buf.writeString(fallback(verb, v))
239	}
240}
241
242// writeString handles %s formatting
243func writeString(p *printer, verb rune, arg any) {
244	switch v := arg.(type) {
245	case (interface{ String() string }):
246		p.buf.writeString(v.String())
247	case error:
248		p.buf.writeString(v.Error())
249	case string:
250		p.buf.writeString(v)
251	default:
252		p.buf.writeString(fallback(verb, v))
253	}
254}
255
256// writeChar handles %c formatting
257func writeChar(p *printer, verb rune, arg any) {
258	switch v := arg.(type) {
259	// rune is int32. Exclude overflowing numeric types and dups (byte, int32):
260	case rune:
261		p.buf.writeString(string(v))
262	case int:
263		p.buf.writeRune(rune(v))
264	case int8:
265		p.buf.writeRune(rune(v))
266	case int16:
267		p.buf.writeRune(rune(v))
268	case uint:
269		p.buf.writeRune(rune(v))
270	case uint8:
271		p.buf.writeRune(rune(v))
272	case uint16:
273		p.buf.writeRune(rune(v))
274	default:
275		p.buf.writeString(fallback(verb, v))
276	}
277}
278
279// writeInt handles %d formatting
280func writeInt(p *printer, verb rune, arg any) {
281	switch v := arg.(type) {
282	case int:
283		p.buf.writeString(strconv.Itoa(v))
284	case int8:
285		p.buf.writeString(strconv.Itoa(int(v)))
286	case int16:
287		p.buf.writeString(strconv.Itoa(int(v)))
288	case int32:
289		p.buf.writeString(strconv.Itoa(int(v)))
290	case int64:
291		p.buf.writeString(strconv.Itoa(int(v)))
292	case uint:
293		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
294	case uint8:
295		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
296	case uint16:
297		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
298	case uint32:
299		p.buf.writeString(strconv.FormatUint(uint64(v), 10))
300	case uint64:
301		p.buf.writeString(strconv.FormatUint(v, 10))
302	default:
303		p.buf.writeString(fallback(verb, v))
304	}
305}
306
307// writeFloat handles floating-point formatting verbs
308func writeFloat(p *printer, verb rune, arg any) {
309	switch v := arg.(type) {
310	case float64:
311		switch verb {
312		case 'e':
313			p.buf.writeString(strconv.FormatFloat(v, 'e', -1, 64))
314		case 'E':
315			p.buf.writeString(strconv.FormatFloat(v, 'E', -1, 64))
316		case 'f', 'F':
317			p.buf.writeString(strconv.FormatFloat(v, 'f', 6, 64))
318		case 'g':
319			p.buf.writeString(strconv.FormatFloat(v, 'g', -1, 64))
320		case 'G':
321			p.buf.writeString(strconv.FormatFloat(v, 'G', -1, 64))
322		}
323	default:
324		p.buf.writeString(fallback(verb, v))
325	}
326}
327
328// writeBool handles %t formatting
329func writeBool(p *printer, verb rune, arg any) {
330	switch v := arg.(type) {
331	case bool:
332		if v {
333			p.buf.writeString("true")
334		} else {
335			p.buf.writeString("false")
336		}
337	default:
338		p.buf.writeString(fallback(verb, v))
339	}
340}
341
342// writeHex handles %x formatting
343func writeHex(p *printer, verb rune, arg any) {
344	switch v := arg.(type) {
345	case uint8:
346		p.buf.writeString(strconv.FormatUint(uint64(v), 16))
347	default:
348		p.buf.writeString("(unhandled)")
349	}
350}
351
352// writeQuotedString handles %q formatting
353func writeQuotedString(p *printer, verb rune, arg any) {
354	switch v := arg.(type) {
355	case string:
356		p.buf.writeString(strconv.Quote(v))
357	default:
358		p.buf.writeString("(unhandled)")
359	}
360}
361
362// writeType handles %T formatting
363func writeType(p *printer, arg any) {
364	switch arg.(type) {
365	case bool:
366		p.buf.writeString("bool")
367	case int:
368		p.buf.writeString("int")
369	case int8:
370		p.buf.writeString("int8")
371	case int16:
372		p.buf.writeString("int16")
373	case int32:
374		p.buf.writeString("int32")
375	case int64:
376		p.buf.writeString("int64")
377	case uint:
378		p.buf.writeString("uint")
379	case uint8:
380		p.buf.writeString("uint8")
381	case uint16:
382		p.buf.writeString("uint16")
383	case uint32:
384		p.buf.writeString("uint32")
385	case uint64:
386		p.buf.writeString("uint64")
387	case string:
388		p.buf.writeString("string")
389	case []byte:
390		p.buf.writeString("[]byte")
391	case []rune:
392		p.buf.writeString("[]rune")
393	default:
394		p.buf.writeString("unknown")
395	}
396}
397
398// Fprintf formats according to a format specifier and writes to w.
399// Returns the number of bytes written and any write error encountered.
400func Fprintf(w io.Writer, format string, a ...any) (n int, err error) {
401	p := newPrinter()
402	p.doPrintf(format, a)
403	return w.Write(p.buf)
404}
405
406// Printf formats according to a format specifier and writes to standard output.
407// Returns the number of bytes written and any write error encountered.
408//
409// XXX: Replace with os.Stdout handling when available.
410func Printf(format string, a ...any) (n int, err error) {
411	var out strings.Builder
412	n, err = Fprintf(&out, format, a...)
413	print(out.String())
414	return n, err
415}
416
417// Appendf formats according to a format specifier, appends the result to the byte
418// slice, and returns the updated slice.
419func Appendf(b []byte, format string, a ...any) []byte {
420	p := newPrinter()
421	p.doPrintf(format, a)
422	return append(b, p.buf...)
423}
424
425// Fprint formats using default formats and writes to w.
426// Spaces are added between arguments.
427// Returns the number of bytes written and any write error encountered.
428func Fprint(w io.Writer, a ...any) (n int, err error) {
429	p := newPrinter()
430	p.doPrint(a)
431	return w.Write(p.buf)
432}
433
434// Print formats using default formats and writes to standard output.
435// Spaces are added between arguments.
436// Returns the number of bytes written and any write error encountered.
437//
438// XXX: Replace with os.Stdout handling when available.
439func Print(a ...any) (n int, err error) {
440	var out strings.Builder
441	n, err = Fprint(&out, a...)
442	print(out.String())
443	return n, err
444}
445
446// Append formats using default formats, appends to b, and returns the updated slice.
447// Spaces are added between arguments.
448func Append(b []byte, a ...any) []byte {
449	p := newPrinter()
450	p.doPrint(a)
451	return append(b, p.buf...)
452}
453
454// Fprintln formats using default formats and writes to w with newline.
455// Returns the number of bytes written and any write error encountered.
456func Fprintln(w io.Writer, a ...any) (n int, err error) {
457	p := newPrinter()
458	p.doPrintln(a)
459	return w.Write(p.buf)
460}
461
462// Println formats using default formats and writes to standard output with newline.
463// Returns the number of bytes written and any write error encountered.
464//
465// XXX: Replace with os.Stdout handling when available.
466func Println(a ...any) (n int, err error) {
467	var out strings.Builder
468	n, err = Fprintln(&out, a...)
469	print(out.String())
470	return n, err
471}
472
473// Sprintln formats using default formats and returns the string with newline.
474// Spaces are always added between arguments.
475func Sprintln(a ...any) string {
476	p := newPrinter()
477	p.doPrintln(a)
478	return string(p.buf)
479}
480
481// Appendln formats using default formats, appends to b, and returns the updated slice.
482// Appends a newline after the last argument.
483func Appendln(b []byte, a ...any) []byte {
484	p := newPrinter()
485	p.doPrintln(a)
486	return append(b, p.buf...)
487}
488
489// This function is used to mimic Go's fmt.Sprintf
490// specific behaviour of showing verb/type mismatches,
491// where for example:
492//
493//	fmt.Sprintf("%d", "foo") gives "%!d(string=foo)"
494//
495// Here:
496//
497//	fallback("s", 8) -> "%!s(int=8)"
498//	fallback("d", nil) -> "%!d(<nil>)", and so on.f
499func fallback(verb rune, arg any) string {
500	var s string
501	switch v := arg.(type) {
502	case string:
503		s = "string=" + v
504	case (interface{ String() string }):
505		s = "string=" + v.String()
506	case error:
507		// note: also "string=" in Go fmt
508		s = "string=" + v.Error()
509	case float64:
510		s = "float64=" + Sprintf("%f", v)
511	case int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64:
512		// note: rune, byte would be dups, being aliases
513		if typename, e := typeToString(v); e == nil {
514			s = typename + "=" + Sprintf("%d", v)
515		} else {
516			panic("ufmt: unexpected type error")
517		}
518	case bool:
519		s = "bool=" + strconv.FormatBool(v)
520	case nil:
521		s = "<nil>"
522	default:
523		s = "(unhandled)"
524	}
525	return "%!" + string(verb) + "(" + s + ")"
526}
527
528// typeToString returns the name of basic Go types as string.
529func typeToString(v any) (string, error) {
530	switch v.(type) {
531	case string:
532		return "string", nil
533	case int:
534		return "int", nil
535	case int8:
536		return "int8", nil
537	case int16:
538		return "int16", nil
539	case int32:
540		return "int32", nil
541	case int64:
542		return "int64", nil
543	case uint:
544		return "uint", nil
545	case uint8:
546		return "uint8", nil
547	case uint16:
548		return "uint16", nil
549	case uint32:
550		return "uint32", nil
551	case uint64:
552		return "uint64", nil
553	case float32:
554		return "float32", nil
555	case float64:
556		return "float64", nil
557	case bool:
558		return "bool", nil
559	default:
560		return "", errors.New("unsupported type")
561	}
562}
563
564// errMsg implements the error interface for formatted error strings.
565type errMsg struct {
566	msg string
567}
568
569// Error returns the formatted error message.
570func (e *errMsg) Error() string {
571	return e.msg
572}
573
574// Errorf formats according to a format specifier and returns an error value.
575// Supports the same verbs as Sprintf. See Sprintf documentation for details.
576func Errorf(format string, args ...any) error {
577	return &errMsg{Sprintf(format, args...)}
578}