Add xop_dump field and integrate into op_dump()

[leonerd]

When working with nontrivially-shaped custom ops, such as ones based on UNOP_AUX with interesting op_aux arrays, it is often useful to be able to peek into the contents of these op structures with op_dump(). Perl's core dumper cannot know the contents of these aux arrays, but by defining a helper function in the module that provides the custom op, help can be achieved.

A helper function, opdump_printf is also provided that acts as a printf()-alike function for outputting lines of content. The various internal arguments to it (level, bar, file) are bundled up into an opaque structure, so as to achieve a modicum of abstraction away from the specific internals on how dump.c happens to work.

[leonerd]

As an example of it in use:

The following function is added to my .xs file:

static void opdump_argelems_named(pTHX_ const OP *o, void *ctx)
{
  UNOP_AUX_item *aux = cUNOP_AUXo->op_aux;

  UV n_params = aux[1].uv;
  opdump_printf(ctx, "ARGIX = %" UVuf "\n", aux[0].uv);
  opdump_printf(ctx, "PARAMS = (%" UVuf ")\n", n_params);
  for(U32 parami = 0; parami < n_params; parami++) {
    UNOP_AUX_item *paramdef = aux + 2 + 4 * parami;

    UV flags = paramdef[NAMEDPARAMaux_FLAGS].uv;
    SV *flagstr = newSVpvn("", 0);
    SAVEFREESV(flagstr);
    if(flags & NAMEDPARAMf_UTF8) sv_catpvf(flagstr, "%sUTF8", SvCUR(flagstr)?", ":"");
    if(flags & NAMEDPARAMf_REQUIRED) sv_catpvf(flagstr, "%sREQUIRED", SvCUR(flagstr)?", ":"");

    opdump_printf(ctx, "  [%d] = {.name=\"%s\", .padix=%u, .flags=(%s)}\n",
        parami,
        paramdef[NAMEDPARAMaux_NAMEPV].pv,
        (unsigned int)paramdef[NAMEDPARAMaux_PADIX].uv,
        SvPV_nolen(flagstr));
  }
}

and added to the XOP structure by:

  XopENTRY_set(&xop_argelems_named, xop_dump, &opdump_argelems_named);

When printed with op_dump(o), it extends the output:

5    +--argelems_named UNOP_AUX(0x55e0f1555af0) ===> [0x0]
         FLAGS = (UNKNOWN,SLABBED)
         ARGIX = 0
         PARAMS = (2)
           [0] = {.name="y", .padix=2, .flags=(REQUIRED)}
           [1] = {.name="x", .padix=1, .flags=(REQUIRED)}

Without this facility, only the top two lines would have been output, resulting in far less useful debug information.

[leonerd]

Several updates made:

• Pass context pointer as opaque structure rather than simply void *
• Automatic linefeed handling in opdump_printf() to avoid caller needing to handle it themselves
• Added documentation of newly-created items

[mauke]

This is a public (API) identifier without a Perl_ prefix. Do we want that?

[leonerd]

We already have hundreds of those - to pick a random example, typedef struct av AV in perl.h. But you're right; no need to make it worse. I'll stick a prefix on it.

[tonycoz]

"decalaration" in the first commit message

[tonycoz]

PerlIO_puts() to avoid the overhead of PerlIO_printf().

[leonerd]

Ahyes; another one I copied from the other code. I'll fix it there too

[tonycoz]

Looks fine otherwise

[leonerd]

"decalaration" in the first commit message

Oops, fixed too.