C Library Functions - attr (3)

NAME

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

Synopsis
Description
Options
Keywords
Limitations
Example
Author
License
See Also

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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.

KEYWORDS

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.

LIMITATIONS

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.

EXAMPLE

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

AUTHOR

John S. Urban, 2021