Module Ocolor_format

Format-friendly functions

Overview

These are functions made to be used easily with Format functions. They use semantic tags to apply and remove a style. Moreover, they are made to be compositional: when using a new style (typically, in a %a context) that override a current style, the previous style is recovered when closing the new one.

For instance, in printf "a@{<red>b@{<blue>c@}d@}e", the 'a' will be printed with the default color (usually white), the 'b' will be in red, the 'c' in blue (since "blue" overrides "red"), the 'd' in red (since "blue" is closed, but nut "red" yet), and 'e' in the default color again.

When using styles that could exists together (for instance, a foreground color, a background color and a bold font), each is handled separatly. For instance, in printf "a@{<red>b@{<bold>c@}d@}e", 'a' and 'e' will be printed with default style, 'b' and 'd' will be only red, but 'c' will be bold and red.

Allowed tags are:

• standard 4-bits colors: black, red, green, blue, yellow, magenta, cyan, white and the same colors prefixed with hi_ for high intensity versions
• rgb colors in the format rgb(ddd,ddd,ddd) where ddd are numbers between 0 and 255 (included) or rgb(0xhh,0xhh,0xhh) where hh are numbers between 0 and ff (included). 0x are mandatory, to disambiguate 10 and 0x10 for instance. There must be no spaces.
• 6*6*6 color, in the format c6(d,d,d) where d are numbers between 0 and 5 (included). There must be no spaces. These colors are interpreted as 8-bits colors.
• 24-step grayscale in the format gs(dd) wheredd is a number between 0 and 23 (included). There must be no spaces. These colors are interpreted as 8-bits colors.
• a X11 color name (just as in X11/rgb.txt). In this case, it may constain spaces (for instance Dark Magenta)
• a X11 color name prefixed by x11_. Useful to disambiguate with standard colors. For instance green is a standard 4-bits color, but x11_green is the x11 color.
• a color prefixed by bg_ to apply this color on the background. For instance bg_green, bg_hi_green, bg_x11_green, bg_gs(12), bg_rgb(1,2,3).
• font(i) with i between 1 and 9 included. Rarely supported
• ul, under, underlined: underlined
• uul, dul, uunder, dunderlined, doubleunderlined: doubly underlined. Rarely supported. Sometimes interpreted as "bold off". Use at your own risks.
• b, bold: bold
• faint
• blink
• conceal
• frak, fraktur: rarely supported
• reverse: reverse video, exchange foreground and background colors
• crossed
• framed: rarely supported
• it, italic
• encircled: rarely supported
• ol, over, overlined

There must be no extra spaces, and everything is case sensitive.

One can as well make a tag by separating two tags by a ";" (without spaces). All styles will be applied and removed at once. For instance Ocolor_format.printf "@{<red;bold>foo@}" is the same as Ocolor_format.printf "@{<red>@{<bold>foo@}@}".

Of course, tags can be opened and closed using Format.pp_open_tag and Format.pp_close_tag. We can rewrite the previous example as Ocolor_format.printf "%afoo%a" Format.pp_open_tag "red;bold" Format.pp_close_tag (). This seems less smart, but this is useful to make styles parametrizable.

However, strictly speaking, applying several styles at once is implementation defined. But most reasonnable combinations will work anyway.

To make it work, the formatter should have semantic tags enabled and correctly set, this is the job of make_formatter and prettify_formatter. There are also pretty standard formatters (std_formatter and err_formatter) and their printers (printf and eprintf) and formatter-less functions (kasprintf and asprintf) that rely on a local pretty formatter (to a buffer) to generate strings.

Prettifying a formatter with prettify_formatter is simply calling make_formatter and ignoring the result. The custom formatter is only needed to do introspection on the current style, this is not the most current usage. Prettifying a formatter enables tag marking (using Format.pp_set_mark_tags) and set (overwrite) mark_open_tag and mark_close_tag. It does not change anything about tag printing.

If one use functions like pp_bool, pp_option, pp_list etc. with a non prettified formatter, the text will be printed with tags, but they won't be interpreted. Thus, with a standard formatter (in which tag marking is disabled by default), it will print raw text. If the formatter allow tag marking, mark_open_tag and mark_close_tag will be used. Thus, it depends on these functions.

To disable pretty printing on a Format.formatter, one can simply disable tag marking with Format.pp_set_mark_tags fmt false. It can be useful to make colors conditional.

Please note that only ANSI escape code are issued. It should suit most modern terminals. However they should not be interpreted on Windows before Windows 10 1511 (November update).

Examples

  let () = Ocolor_format.printf "a@{<red>b@}c"
  (* "abc" is printed on the standard output
     "a" and "c" without styles and "b" in red.
  *)

  let pp_pair (fmt: Format.formatter) ((a, b): int * int) : unit =
    Format.fprintf fmt "(@{<bold>%d@}, @{<ul>%d@})" a b

  let pp_pair_pair (fmt: Format.formatter) ((a, b): (int * int) * (int * int)) : unit =
    Format.fprintf fmt "(@{<red>%a@}, @{<blue>%a@})" pp_pair a pp_pair b

  let () = Format.fprintf Ocolor_format.raw_std_formatter "%a" pp_pair_pair ((1, 2), (3, 4))
  (* "((1, 2), (3, 4))" is printed on the standard output.
     "(1, 2)" is red, "(3, 4)" is blue.
     "1" and "3" are bold and "2" and "4" are underlined.

     Equivalent to
  *)

  let pp_pair (fmt: Format.formatter) ((a, b): int * int) : unit =
    Format.fprintf fmt "(%a%d%a, %a%d%a)"
      Format.pp_open_tag "bold"
      a
      Format.pp_close_tag ()
      Format.pp_open_tag "ul"
      b
      Format.pp_close_tag ()

  let pp_pair_pair (fmt: Format.formatter) ((a, b): (int * int) * (int * int)) : unit =
    Format.fprintf fmt "(%a%a%a, %a%a%a)"
      Format.pp_open_tag "red"
      pp_pair a
      Format.pp_close_tag ()
      Format.pp_open_tag "blue"
      pp_pair b
      Format.pp_close_tag ()

  let () = Format.fprintf Ocolor_format.raw_std_formatter "%a" pp_pair_pair ((1, 2), (3, 4))

  let () = Ocolor_format.printf "%a"
      (Ocolor_format.pp_list
         (fun fmt n ->
            Format.pp_open_tag fmt "red";
            Format.pp_print_int fmt n;
            Format.pp_close_tag fmt ()
         )
      )
      [1;2;3]
  (* Prints "[1; 2; 3]" each number in red, semicolons and brackets are fainted. *)

  (* Same as *)
  let () = Ocolor_format.printf "%a"
      (Ocolor_format.pp_list_generic
         ~elem_style:[Ocolor_types.(Fg (C4 red))]
         Format.pp_print_int
      )
      [1;2;3]

Custom formatters

Format-like functions

Introspection

Pretty printers

Pretty printers for common types

Generic functions

Default pretty printers