integration/luprex/cpp/core/pprint.hpp

//////////////////////////////////////////////////////////////////////////////////
//
// print, pprint, and tostring
//
// This module implements the heart of the lua 'print', lua 'pprint', and lua
// 'tostring' functions. Note that we have to override the lua builtins 'print'
// and 'tostring' for two reasons:
//
//   * We need to suppress the printing of table addresses, for determinism.
//   * We need to channel the output to a PrintBuffer in the world model.
//
// Note that the actual lua 'print' and 'pprint' routines aren't defined in this
// module, they're in the World module, because they send their output into the
// PrintBuffer of the world model.  But all the tricky code to implement 'print'
// and 'pprint' are in this module.
//
//////////////////////////////////////////////////////////////////////////////////

#ifndef PPRINT_HPP
#define PPRINT_HPP

#include "luastack.hpp"
#include <ostream>

struct PrettyPrintOptions {
    bool indent;
    int level;
    bool expand;
    PrettyPrintOptions() : indent(true), level(0), expand(true) {}
    PrettyPrintOptions(bool indent, bool expand) : indent(indent), level(0), expand(expand) {}
    void parse(LuaKeywordParser &kp);
};

// Atomic print to a stream.
//
// This prints an atomic value to a stream.  If you give it a table,
// it just prints "<table>".  This routine is the heart of the lua
// primitives 'print' and 'tostring'.
//
void atomic_print(LuaCoreStack &LS, LuaSlot val, bool quote, std::ostream *os);

// Pretty print to a stream.
//
void pprint(LuaCoreStack &LS, LuaSlot val, const PrettyPrintOptions &opts, std::ostream *os);

// Format a string using printf-style format specifiers, consuming
// arguments from a LuaExtraArgs.  Returns an empty string on success,
// or an error message on failure.
//
// Numeric types (argument must be a number).  All of the following
// use the same formatting parameters as 'printf'.
//   
//   %d, %i   — signed decimal integer
//   %o       — unsigned octal
//   %u       — unsigned decimal
//   %x, %X   — unsigned hexadecimal (lower/upper)
//   %e, %E   — scientific notation (lower/upper)
//   %f       — decimal floating point
//   %g, %G   — shortest of %e/%f (lower/upper)
//   %c       — character (integer converted to character)
//
// Non-numeric types:
//   %s       — prints any lua value using atomic_print (unquoted)
//   %q       — prints any lua value using atomic_print (quoted)
//
// Pretty-printing:
//
//   %p       - pretty print
//   %lp      - pretty print, but all on one line
//   %P       - pretty print, force table expansion
//   %lP      - pretty print, force table expansion, all on one line
//    
// Special:
//   %%       — literal percent sign (consumes no argument)
//
eng::string format(LuaCoreStack &LS, std::string_view fmt, LuaExtraArgs args, std::ostream *os);

#endif // PPRINT_HPP