[darcs-devel] darcs patch: add "hidden" printer, for printing things to screen bu...

Eric Y. Kow eric.kow at gmail.com
Sun Nov 4 18:59:28 UTC 2007

On Tue, Oct 30, 2007 at 13:57:35 -0700, David Roundy wrote:
> This printer isn't yet used at all, but we might want to add it to
> the unstable repository, if the code looks reasonable to you.  A
> better name would be helpful, though.

Ok, this is going in.  How about 'debugP' or 'terminalP' for a name?

> Tue Oct 30 13:54:48 PDT 2007  David Roundy <droundy at darcs.net>
>   * add "hidden" printer, for printing things to screen but not file.
>   This is a poor name, but it's the counterpart of the invisible printer,
>   which prints to files, but not to the screen.  I wanted this for adding
>   colorful annotations to conflicted patches (to help while debugging).
>   But it may turn out to be more generally useful.

For the interested, below is an explanation the (Colour)Printers code in
general.  It took me a while to understand how it all fit together, so I
hope you'll forgive the lengthy explanation.

There are three basic layers to the Printers code.

The innermost layer is a set of "physical printers".  These have names
that end in 'Printer', e.g., simplePrinter, invisiblePrinter and
colorPrinter.  In short, simplePrinter prints things, invisiblePrinter
does not, and colorPrinter prints things in colour (if possible).  To be
more precise, printers do not actually print anything.  Rather, they
/transform/ text so that when the transformed text is printed out, you
will get a specific effect.  To get an idea, simplePrinter does not make
any transformations, invisiblePrinter ignores the text and returns the
empty string, colorPrinter wraps the text in escape codes.

The middle layer provides a set of "logical printers".  Logical printers
have names that end in 'P', for example, colorP, invisibleP and defP (I
think this would be clearer as defaultP).  These names do not guarantee
how the logical printers will behave, but they make some hints about how
the logical printer is intended to be used.  As you may guess from the
names, a logical printer is nothing more than a pointer to a physical

The outermost layer consists of functions for building up Documents,
mappings from logical printers to physical printers, and rendering

   Documents are built up with functions like (e.g., text,
invisibleText, greenText) and combinators (e.g. $$ and <>).
These functions essentially send text through a logical printer,
getting some transformed text, and concatenates this transformed
text.  In other words, you can think of these document-building
functions as a user-interface to the logical printers.  Whereas
'invisibleText' sends text through the invisibleP printer, 'text'
function sends it through defP printer, and so on.

   This is where the printer mappings (:: Printers) come in.
There are two printer mappings in use, simplePrinters and
fancyPrinters.  Printer mappings is how we can obtain different
behaviours for printing to screen vs. printing to a file.  If
you want to printer to screen, you use the fancy mappings; if you
want to print to a file, you're much better off with the
simple mappings.  This is where the distinction between the
printers invisibleP, hiddenP and defaultP come from:

  |            | fancy mapping (screen) | simple mapping   |
  | defaultP   | simplePrinter          | simplePrinter    |
  | invisibleP | invisiblePrinter       | simplePrinter    |
  | hiddenP    | colorPrinter green     | invisiblePrinter |

In other words, invisible printer has the behaviour of printing only to
files, and not to the screen because under the fancy mapping, it points
to invisiblePrinter.  Likewise, hiddenP has the opposite behaviour,
because it points to invisiblePrinter under the simple mapping.

   The final detail in the outermost layer is the rendering functions,
namely, hPutDoc, hPutDocWith (etc), renderString and renderStringWith.
These take a built up Document and pass them through a printer mapping.
hPutDoc is just a wrapper around hPutDocWith (passing in
simplePrinters).  If you want the fancy mapping, you should invoke
something like (hPutDocWith fancyPrinters) instead.

Eric Kow                     http://www.loria.fr/~kow
PGP Key ID: 08AC04F9         Merci de corriger mon français.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 186 bytes
Desc: not available
Url : http://lists.osuosl.org/pipermail/darcs-devel/attachments/20071104/370227f2/attachment.pgp 

More information about the darcs-devel mailing list