Re: [epsilon-devel] jitter and libtextstyle

[Jose E. Marchesi]

Hi Luca!
    
    On 2019-10-14 at 16:26 +0200, Jose E. Marchesi wrote:
    
    > I recently "libtextstylized" poke, and to complete the process I would
    > need a few changes in the Jitter API.
    
    Very interesting.
    
    I have not looked at libtextstyle beyond what Bruno showed us.  It is
    way too late for me to do it now, unfortunately.  I have class at 8.
    But I will check it soon.
    
    In the mean time, please tell me if I am misunderstanding anything.
    
    > First, PREFIX_print_program currently is invoked like:
    >
    >     pvm_print_program (stdout, prog);
    >
    > Where the first argument is a FILE*.
    
    I am seizing the occasion of the upcoming routine API change to change
    this a little.  In particular I want to make the APIs for printing a
    routine and for disassembling it as similar as possible.  Neither will
    become substantially more complex.
    
    > In order to be able to apply style in the printed disassembly
                                                        ^^^^^^^^^^^
    
    I am assuming you mean printing a VM routine.

Yep.
    
    > , I would
    > need PREFIX_print_program to get a hook instead, that will do the
    > printing of the entities.
    
    This is fine, but I would like to make the dependency on libtextstyle
    optional.  The hook-enabled printer will be a new function, but
    something very close to the current API will remain available as
    well.

Works for me.
    
    In fact I believe that libtextstyle will be even more useful for the
    actual (hardware-instruction) disassembly where a lot of information is
    condensed in a small, cluttered space.  In the case of actual
    disassembly I suppose that the hook could be completely hidden from the
    user, as long as the format customization does not rely on the C
    API.

    I would be quite happy to replace scripts/highlight-disassembly.in ,
    which has always been meant as a kludge, with something clean and
    directly usable from C.

As I mentioned in the other email, in my opinion the styling of the
hardware-instruction disassembly is something that is up to Jitter.  It
is the styling of the routines that concerns us.
    
    > The hook should also be made aware of the kind of entity it is
    > printing, like instruction mnemonic, or argument type.
    
    Sure, this is easy.  The entities are fixed, and few in number.

Ok, thanks.
    
    Right now Jitter's routine printing performs a trivial kind of
    pretty-printing, using the least possible amount of horizontal space for
    mnemonics while having the first instruction arguments all aligned on
    the same column.
    
    I hope this will not interfere with the library.  If it did in some
    troublesome way, I could avoid aligning in the hook-enabled printout.
    That would be of course a worst-case scenario.

Hmm, I think your pretty-printing should still work.  Just pass the
horizontal space (blanks) to the hook using a suitable entity
identification.
    
    > Also, the instruction pretty printers currently are implemented as hooks
                ^^^^^^^^^^^
    
    I am assuming you mean literal.
    
Yep.

    > that also get a FILE *.  Example:
    > [...]
    > But then I'm afraid of Jitter relying on the order imposed by the FILE
    > stream, or caching it in some other way.
    
    Jitter currently prints routines in two passes:
    
    1) The first pass scans every used VM instruction in order to find the
       longest mnemonic which is actually used as explained above, without
       printing anything;
    
    2) the second pass does the actual output, writing everything to the
       FILE * stream, in order.  No bizarre caching, no ungetc.
    
    I would keep this same idea for the hook version -- possibly replacing
    the FILE * argument with something different, as explained below.  Of
    course I would re-implement the traditional-style printer as a call to
    the hook version, using trivial hooks.  As long as I am not
    misunderstanding how libtextstyle works, this should again be easy.

That should work yes :)
    
    > I am already ignoring the OUT argument in some places, like in:
    >
    >     void
    >     pvm_literal_printer (FILE *out, jitter_uint val)
    >     {
    >       /* XXX what about out.  */
    >       pvm_print_val ((pvm_val) val, 10, 0);
    >     }
    
    I do not understand this.  Where is pvm_print_val printing to?  Always
    to the standard output?  I can replace the FILE * object with an
    abstract "hook callee argument", in the style of pthread_create 's last
    argument.  This would play the role of the FILE * object, and hopefully
    interact naturally with libtextstyle.

pvm_print_val uses pk_term_* services, which in turn use a global
libtextstyle ostream.

Having a void* client data passed to the hooks would be ideal, for when
globals are not an option, yes.
    
    > I can always flush the libtextstyle output stream in each pretty
    > printer, and simply ignore the OUT, but that seems a bit fragile to
    > me...  what are your thoughts about an API that would allow
    > client-provided printers?  That would be perfect for me, and for other
    > users of libtextstyle as well! :)
    
    I have no objections.
    
    This is not directly related to libtextstyle, but the issue will come up
    if you want to print structured literal objects in a sophisticated way.
    
    The problem I anticipate is related to printing objects (in your case VM
    instruction literals as Poke objects) spanning multiple lines.  If we
    want to support that, then Jitter needs to call the data printer (or the
    hook?  Are they different things?) by providing information about the
    initial column index.
    
    For example (here I am making up VM instructions and Poke data
    notation):
    
    $L1:
         push-literal       [struct my-file-field
                              foo = 3:  #2B;
                              bar = 79: #1B]
         frobnicate-and-pop
         branch             $L1
    
    If you want to decorate every syntactic element within the struct in a
    sophisticated way and use multiple lines for a single struct, then your
    printer hooks need to know how much to indent following each '\n', in
    addition to your own indentation showing the data nesting level.  I can
    arrange for that.
    
    Are you planning to do this?

No, not really.  Assuming a line per instruction is perfectly ok for us.
At least for the time being? :)

Thanks!