From 641c7a4f643ef0a67df905fecd9e3fbb2cdb157f Mon Sep 17 00:00:00 2001 From: tannevaled Date: Mon, 24 Aug 2026 22:00:47 +0200 Subject: [PATCH] Add String#dump MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit String#dump was undefined (NoMethodError). It now returns the receiver wrapped in double quotes with every non-printable byte, quote, backslash, and interpolation sigil replaced by a backslash escape, so the result is a valid Ruby literal that reproduces the receiver: - named escapes for \a \b \t \n \v \f \r \e, and \" \; - `\#` only when `#` is followed by an interpolation sigil ($, @, {); - printable ASCII kept verbatim; - a single-byte control (0x00-0x1F, 0x7F) escapes as \xHH — unlike #inspect, which uses \uXXXX in a UTF-8 string; - a UTF-8 multibyte character always escapes to \uXXXX (BMP) or \u{XXXX...} (above U+FFFF), never kept verbatim; - a non-ASCII-compatible encoding (UTF-16/UTF-32) additionally carries a .force_encoding("NAME") suffix. The core lives in (*object.String).Dump, alongside Inspect, which it closely mirrors. The result is always a plain, unfrozen String in the receiver's encoding. Verified against ruby 4.0.6. Full package coverage stays at 100.0%. Zero- regression rubyspec sweep; core/string/dump_spec 0 -> 16 (the one remaining error is the .force_encoding example, blocked by rbgo's pre-existing lack of UTF-16 transcoding in String#encode, not by dump). Co-Authored-By: Claude Opus 4.8 --- internal/object/object.go | 68 ++++++++++++++++++++++++ internal/object/string_dump_test.go | 42 +++++++++++++++ internal/vm/builtins.go | 7 +++ internal/vm/string_dump_internal_test.go | 57 ++++++++++++++++++++ 4 files changed, 174 insertions(+) create mode 100644 internal/object/string_dump_test.go create mode 100644 internal/vm/string_dump_internal_test.go diff --git a/internal/object/object.go b/internal/object/object.go index 5d5de97b..986639b6 100644 --- a/internal/object/object.go +++ b/internal/object/object.go @@ -379,6 +379,74 @@ func (s *String) Inspect() string { return b.String() } +// Dump returns the String#dump representation: the receiver wrapped in double +// quotes with every non-printable byte, quote, backslash, and interpolation +// sigil replaced by a backslash escape so the result is a valid Ruby String +// literal that reproduces the receiver. It differs from Inspect in that a UTF-8 +// multibyte character is always escaped (\uXXXX up to U+FFFF, \u{XXXX…} above) +// rather than kept verbatim, and a single-byte control (0x00–0x1F, 0x7F) escapes +// as \xHH rather than \uXXXX. When the encoding is not ASCII-compatible the +// literal is followed by .force_encoding("NAME"), matching MRI. +func (s *String) Dump() string { + var b strings.Builder + b.WriteByte('"') + data := s.Bytes() + utf8enc := s.Enc == "" || s.Enc == "UTF-8" + for i := 0; i < len(data); { + c := data[i] + if esc, ok := inspectNamedEscape[c]; ok { + b.WriteString(esc) + i++ + continue + } + if c == '#' { + if i+1 < len(data) && (data[i+1] == '{' || data[i+1] == '$' || data[i+1] == '@') { + b.WriteString(`\#`) + } else { + b.WriteByte('#') + } + i++ + continue + } + if c >= 0x20 && c < 0x7f { // printable ASCII, kept verbatim + b.WriteByte(c) + i++ + continue + } + // A UTF-8 multibyte character always escapes to \u notation (upper-case + // hex): \uXXXX in the BMP, \u{XXXXXX} above it. + if utf8enc && c >= 0x80 { + if r, size := utf8.DecodeRune(data[i:]); r != utf8.RuneError || size > 1 { + if r > 0xFFFF { + fmt.Fprintf(&b, `\u{%X}`, r) + } else { + fmt.Fprintf(&b, `\u%04X`, r) + } + i += size + continue + } + } + // Every other non-printable byte — a single-byte control in any encoding, + // a high byte of a non-UTF-8 string, or an invalid UTF-8 byte — escapes as + // \xHH with upper-case hex. + fmt.Fprintf(&b, `\x%02X`, c) + i++ + } + b.WriteByte('"') + if !asciiCompatibleEnc(s.EncName()) { + b.WriteString(`.force_encoding("` + s.EncName() + `")`) + } + return b.String() +} + +// asciiCompatibleEnc reports whether an encoding shares the ASCII code points in +// their usual single-byte positions, as MRI's rb_enc_asciicompat does. Only the +// wide fixed-width Unicode encodings (UTF-16/UTF-32 families) are not compatible; +// String#dump appends .force_encoding for those. +func asciiCompatibleEnc(name string) bool { + return !strings.HasPrefix(name, "UTF-16") && !strings.HasPrefix(name, "UTF-32") +} + // inspectNamedEscape maps the control bytes String#inspect renders with a named // backslash escape, in every encoding. var inspectNamedEscape = map[byte]string{ diff --git a/internal/object/string_dump_test.go b/internal/object/string_dump_test.go new file mode 100644 index 00000000..46366034 --- /dev/null +++ b/internal/object/string_dump_test.go @@ -0,0 +1,42 @@ +// Copyright (c) the go-embedded-ruby/ruby authors +// +// SPDX-License-Identifier: BSD-3-Clause + +package object + +import "testing" + +// TestStringDump exercises (*String).Dump at the object layer, covering the +// branches the VM-level String#dump cannot yet reach because rbgo has no way to +// build a non-ASCII-compatible string: such an encoding escapes its high bytes +// as \xHH and appends a .force_encoding("NAME") suffix, while an ASCII-compatible +// encoding does not. The ASCII-compatible cases here match ruby 4.0.6; the +// non-compatible cases assert Dump's own byte-wise contract (rbgo cannot yet +// produce a real UTF-16/UTF-32 string to compare against MRI). +func TestStringDump(t *testing.T) { + cases := []struct { + in *String + want string + }{ + // Default (UTF-8): a multibyte character escapes to \u, no suffix. + {NewString("é"), `"\u00E9"`}, + // ASCII-compatible non-default encoding: no suffix. + {NewStringBytesEnc([]byte("foo"), "ISO-8859-1"), `"foo"`}, + // Non-ASCII-compatible encoding: high bytes escape as \xHH, ASCII bytes + // stay verbatim, and the literal carries a .force_encoding suffix. + {NewStringBytesEnc([]byte{0x80, 'v'}, "UTF-16BE"), `"\x80v".force_encoding("UTF-16BE")`}, + {NewStringBytesEnc([]byte{0xC0, 'A'}, "UTF-32BE"), `"\xC0A".force_encoding("UTF-32BE")`}, + } + for _, c := range cases { + if got := c.in.Dump(); got != c.want { + t.Errorf("Dump(%q enc=%q) = %q, want %q", c.in.Str(), c.in.EncName(), got, c.want) + } + } + + if !asciiCompatibleEnc("UTF-8") || !asciiCompatibleEnc("US-ASCII") { + t.Error("UTF-8/US-ASCII must be ASCII-compatible") + } + if asciiCompatibleEnc("UTF-16LE") || asciiCompatibleEnc("UTF-32LE") { + t.Error("UTF-16/UTF-32 must not be ASCII-compatible") + } +} diff --git a/internal/vm/builtins.go b/internal/vm/builtins.go index fb918aa6..682bd7df 100644 --- a/internal/vm/builtins.go +++ b/internal/vm/builtins.go @@ -1465,6 +1465,13 @@ func (vm *VM) bootstrap() { vm.cString.define("empty?", func(_ *VM, self object.Value, _ []object.Value, _ *Proc) object.Value { return object.Bool(len(strOf(self)) == 0) }) + vm.cString.define("dump", func(_ *VM, self object.Value, _ []object.Value, _ *Proc) object.Value { + // Always a plain (never frozen, never subclass) String in the receiver's + // encoding; a non-ASCII-compatible source additionally carries a + // .force_encoding suffix inside the dumped text (see (*String).Dump). + s := self.(*object.String) + return object.NewStringBytesEnc([]byte(s.Dump()), s.EncName()) + }) vm.cString.define("upcase", func(_ *VM, self object.Value, _ []object.Value, _ *Proc) object.Value { return strEncOf(self, strings.ToUpper(strOf(self))) }) diff --git a/internal/vm/string_dump_internal_test.go b/internal/vm/string_dump_internal_test.go new file mode 100644 index 00000000..a4ed70d6 --- /dev/null +++ b/internal/vm/string_dump_internal_test.go @@ -0,0 +1,57 @@ +// Copyright (c) the go-embedded-ruby/ruby authors +// +// SPDX-License-Identifier: BSD-3-Clause + +package vm + +import "testing" + +// TestStringDump covers String#dump: the receiver wrapped in double quotes with +// non-printable bytes, quotes, backslashes, and interpolation sigils escaped so +// the result is a Ruby literal reproducing the receiver. It exercises the named +// escapes, the \# sigil guard, printable ASCII passthrough, single-byte \xHH +// controls (in both binary and UTF-8 strings), UTF-8 multibyte \uXXXX / \u{…} +// escaping, and the result's encoding. Verified against ruby 4.0.6. +func TestStringDump(t *testing.T) { + cases := []struct{ src, want string }{ + {`p "hello".dump`, `"\"hello\""`}, + {`p "".dump`, `"\"\""`}, + // Named escapes for the control characters that have them. + {`p "\a\b\t\n\v\f\r\e".dump`, `"\"\\a\\b\\t\\n\\v\\f\\r\\e\""`}, + // Quote and backslash double up. + {`p "\"\\".dump`, `"\"\\\"\\\\\""`}, + // `#` is escaped only before an interpolation sigil ($, @, {). Single-quoted + // Ruby literals keep the sigils intact for dump to escape. + {`p '#{a}'.dump`, `"\"\\\#{a}\""`}, + {`p '#$x'.dump`, `"\"\\\#$x\""`}, + {`p '#@y'.dump`, `"\"\\\#@y\""`}, + {`p "#1 # #a".dump`, `"\"#1 # #a\""`}, + // Single-byte controls escape as \xHH (upper-case), in any encoding. + {`p 0.chr.dump`, `"\"\\x00\""`}, + {`p 0x1c.chr.dump`, `"\"\\x1C\""`}, + {`p 0x7f.chr.dump`, `"\"\\x7F\""`}, + // A high byte of a binary string escapes as \xHH. + {`p 0x80.chr.dump`, `"\"\\x80\""`}, + {`p 0xff.chr.dump`, `"\"\\xFF\""`}, + // A UTF-8 single-byte control still uses \xHH (unlike #inspect's \uXXXX). + {`p 0.chr('utf-8').dump`, `"\"\\x00\""`}, + {`p 0x7f.chr('utf-8').dump`, `"\"\\x7F\""`}, + // UTF-8 multibyte: \uXXXX in the BMP, \u{…} above it. + {`p 0x80.chr('utf-8').dump`, `"\"\\u0080\""`}, + {`p 0xFFFF.chr('utf-8').dump`, `"\"\\uFFFF\""`}, + {`p 0x10000.chr('utf-8').dump`, `"\"\\u{10000}\""`}, + {`p 0x10FFFF.chr('utf-8').dump`, `"\"\\u{10FFFF}\""`}, + {`p "é".dump`, `"\"\\u00E9\""`}, + // dump ignores frozen and returns a plain String instance. + {`p "foo".freeze.dump.frozen?`, `false`}, + {`p "foo".dump.instance_of?(String)`, `true`}, + // The result carries the receiver's (ASCII-compatible) encoding. + {`p "foo".encode("ISO-8859-1").dump.encoding.name`, `"ISO-8859-1"`}, + {`p 1.chr.dump.encoding.name`, `"US-ASCII"`}, + } + for _, c := range cases { + if got := eval(t, c.src); got != c.want+"\n" { + t.Errorf("src=%q got=%q want=%q", c.src, got, c.want+"\n") + } + } +}