/ 
Devel-ebug-0.67
⭐ Starred 3 / Devel::ebug::Wire

NAME

Devel::ebug::Wire - Serialization for the Devel::ebug wire protocol

VERSION

version 0.67

SYNOPSIS

use Devel::ebug::Wire;

my $line = Devel::ebug::Wire::encode('json', { command => 'step' });
my $req  = Devel::ebug::Wire::decode(Devel::ebug::Wire::detect($line), $line);

DESCRIPTION

The frontend and the backend exchange Perl data structures as single newline terminated lines over a socket. This module is the one place that knows how those lines are written and read.

Two formats are understood:

yaml

The original format: YAML Dump output, hex packed so that it occupies a single line. This is the default, and what every existing client speaks.

json

Plain JSON, one object per line. Chosen with the serializer attribute of Devel::ebug, or by setting DEVEL_EBUG_SERIALIZER in the environment.

JSON is the format to pick when the other end of the socket is not Perl. Hex packed YAML asks a client to implement YAML, object deserialization and a hex decoder before it can say hello; a JSON line can be read by anything.

The JSON encoder is only loaded when JSON is actually used, so it is not needed to run the debugger, and neither is YAML when JSON is in use. Cpanel::JSON::XS is used if it is installed, otherwise JSON::PP.

Blessed references

YAML carries blessed references itself, and the protocol relies on it: stack_trace returns Devel::StackTrace::Frame objects that the frontend calls methods on. JSON has no equivalent, so a blessed reference is written as

{ "__bless__": "Some::Class", "__value__": { ... } }

and blessed back into its class on the way out. Scalar references get the same treatment through __scalarref__.

References JSON cannot represent at all - code, globs, regular expressions, filehandles - are replaced by their stringified form. These only ever turn up in values sampled from the program being debugged, such as the arguments in a stack frame, where a readable placeholder is the best that can be done and is what the reader wanted anyway.

FUNCTIONS

detect

my $format = Devel::ebug::Wire::detect($line);

Works out which format a line arrived in.

encode

my $line = Devel::ebug::Wire::encode($format, $data);

Serializes a data structure to a single line, without the terminating newline.

decode

my $data = Devel::ebug::Wire::decode($format, $line);

The inverse of encode.

SEE ALSO

Devel::ebug

AUTHOR

Original author: Leon Brocard <acme@astray.com>

Current maintainer: Graham Ollis <plicease@cpan.org>

Contributors:

Brock Wilcox <awwaiid@thelackthereof.org>

Taisuke Yamada

COPYRIGHT AND LICENSE

This software is copyright (c) 2005-2026 by Leon Brocard.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.