attr Interface

attr(3f) - [M_attr] substitute escape sequences for HTML-like syntax
           in strings
(LICENSE:MIT)

  function attr(string,reset) result (expanded)

    ! scalar
    character(len=*),intent(in)  :: string
    logical,intent(in),optional  :: reset
    character(len=:),allocatable :: expanded
    ! or array
    character(len=*),intent(in)  :: string(:)
    logical,intent(in),optional  :: reset
    character(len=:),allocatable :: expanded(:)
    integer,intent(in),optional  :: chars

Use HTML-like syntax to add attributes to terminal output such as
color on devices that recognize ANSI escape sequences.

string        input string  of form

                "<attribute_name>string</attribute_name> ...".

               where the current attributes are color names,
               bold, italic, underline, ...

reset          By default, a sequence to clear all text attributes
               is sent at the end of each returned line if an escape
               character appears in the output string. This can be
               turned off by setting RESET to .false. .

               Note if turning off the reset attributes may be
               continued across lines, but if each line is not
               self-contained attributes may not display properly
               when filtered with commands such as grep(1).

chars          For arrays, a reset will be placed after the Nth
               displayable column count in order to make it easier
               to generate consistent right borders for non-default
               background colors for a text block.

primary default keywords

  colors:
    r,         red,       R,  RED
    g,         green,     G,  GREEN
    b,         blue,      B,  BLUE
    m,         magenta,   M,  MAGENTA
    c,         cyan,      C,  CYAN
    y,         yellow,    Y,  YELLOW
    e,         ebony,     E,  EBONY
    w,         white,     W,  WHITE

  attributes:
    it,        italic
    bo,        bold
    un,        underline

  basic control characters:
   nul
   bel  (0x07, ^G) beeps;
   bs   (0x08, ^H) backspaces one column (but not past the beginning of
                   the line);
   ht   (0x09, ^I) goes to the next tab stop or to the end of the line if
                   there is no earlier tab stop;
   lf   (0x0A, ^J),
   vt   (0x0B, ^K)
   ff   (0x0C, ^L) all give a linefeed, and if LF/NL (new-line mode) is
                   set also a carriage return
   cr   (0x0D, ^M) gives a carriage return;
   so   (0x0E, ^N) activates the G1 character set;
   si   (0x0F, ^O) activates the G0 character set;
   can  (0x18, ^X) and SUB (0x1A, ^Z) interrupt escape sequences;
   sub
   esc  (0x1B, ^[) starts an escape sequence;
   del  (0x7F) is ignored;

  other:
    clear
    default
    reset
    gt
    lt
    save,DECSC     Save  current state (cursor coordinates, attributes,
                   character sets pointed at by G0, G1).
    restore,DECRC  Restore state most recently saved by ESC 7.
    CSI            "Control Sequence Introducer"(0x9B) is equivalent to
                   "ESC [".

  dual-value (one for color, one for mono):

    write(*,*)attr('<ERROR>an error message')
    write(*,*)attr('<WARNING>a warning message')
    write(*,*)attr('<INFO>an informational message')

By default, if the color mnemonics (ie. the keywords) are uppercase
they change the background color. If lowercase, the foreground color.
When preceded by a "/" character the attribute is returned to the
default.

The "default" keyword is typically used explicitly when reset=.false,
and sets all text attributes to their initial defaults.

o colors are not nestable, keywords are case-sensitive,
o not all terminals obey the sequences. On Windows, it is best if
  you use Windows 10+ and/or the Linux mode; although it has worked
  with all CygWin and MinGW and Putty windows and mintty.
o you should use "<gt>" and "<lt>" instead of ">" and "<" in a string
  processed by attr(3f) instead of in any plain text output so that
  the raw mode will create correct input for the attr(3f) function
  if read back in.

Sample program

 program demo_attr
 use M_attr, only : attr, attr_mode, attr_update
    call printstuff('defaults')

    call attr_mode(manner='plain')
    call printstuff('plain:')

    call printstuff('raw')

    call attr_mode(manner='color')
    call printstuff('')

    write(*,'(a)') attr('TEST ADDING A CUSTOM SEQUENCE:')
    call attr_update('blink',char(27)//'[5m')
    call attr_update('/blink',char(27)//'[25m')
    write(*,'(a)') attr('<blink>Items for Friday</blink>')

 contains
 subroutine printstuff(label)
 character(len=*),intent(in)  :: label
 character(len=:),allocatable :: array(:)
   call attr_mode(manner=label)

   array=[character(len=60) ::    &
    'TEST MANNER='//label,                      &
    '<r>RED</r>,<g>GREEN</g>,<b>BLUE</b>',      &
    '<c>CYAN</c>,<m>MAGENTA</g>,<y>YELLOW</y>', &
    '<w>WHITE</w> and <e>EBONY</e>']
   write(*,'(a)') attr(array)

   write(*,'(a)') attr('Adding <bo>bold</bo>')
   write(*,'(a)') attr('<bo><r>RED</r>,<g>GREEN</g>,<b>BLUE</b></bo>')
   write(*,'(a)') attr('<bo><c>CYAN</c>,<m>MAGENTA</g>,<y>YELLOW</y></bo>')
   write(*,'(a)') attr('<bo><w>WHITE</w> and <e>EBONY</e></bo>')

   write(*,'(a)') attr('Adding <ul>underline</ul>')
   write(*,'(a)') attr(&
    &'<bo><ul><r>RED</r>,<g>GREEN</g>,<b>BLUE</b></ul></bo>')
   write(*,'(a)') attr(&
    &'<bo><ul><c>CYAN</c>,<m>MAGENTA</g>,<y>YELLOW</y></ul></bo>')
   write(*,'(a)') attr('<bo><ul><w>WHITE</w> and <e>EBONY</e></ul></bo>')

   write(*,'(a)') attr('Adding <ul>italic</ul>')
   write(*,'(a)') attr(&
    &'<bo><ul><it><r>RED</r>,<g>GREEN</g>,<b>BLUE</b></it></ul></bo>')
   write(*,'(a)') attr(&
    &'<bo><ul><it><c>CYAN</c>,<m>MAGENTA</g>,<y>YELLOW</it></y></ul></bo>')
   write(*,'(a)') attr('<bo><ul><it><w>WHITE</w> and <e>EBONY</e></ul></bo>')

   write(*,'(a)') attr('Adding <in>inverse</in>')
   write(*,'(a)') attr('<in><bo><ul><it><r>RED</r>,<g>GREEN</g>,&
    &<b>BLUE</b></it></ul></bo></in>')
   write(*,'(a)') attr('<in><bo><ul><it><c>CYAN</c>,<m>MAGENTA</g>,&
    &<y>YELLOW</it></y></ul></bo></in>')
   write(*,'(a)') attr(&
    &'<in><bo><ul><it><w>WHITE</w> and <e>EBONY</e></ul></bo></in>')
 end subroutine printstuff
 end program demo_attr

John S. Urban, 2021

MIT

attr_mode(3f), attr_update(3f)