From 2bb9d5c3f85e3b602d062d9d4f78af19fe3b9b1b Mon Sep 17 00:00:00 2001 From: dsiders Date: Fri, 12 Apr 2024 00:05:51 +0100 Subject: [PATCH] Docs: LazUtils/laztty. Adds laztty.xml documentation file for changes in be06ee3c. --- docs/xml/lazutils/laztty.xml | 294 +++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 docs/xml/lazutils/laztty.xml diff --git a/docs/xml/lazutils/laztty.xml b/docs/xml/lazutils/laztty.xml new file mode 100644 index 0000000000..0d78f60739 --- /dev/null +++ b/docs/xml/lazutils/laztty.xml @@ -0,0 +1,294 @@ + + + + + + + +Contains platform-specific code for checking TTY output. + + +

+laztty.pas is copied from Free Pascal Compiler source files +comptty.pas and comphook.pas. Copyright (c) 2020 by +the Free Pascal development team. +

+

+This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. +

+

+This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. +

+

+You should have received a copy of the GNU General Public License along with +this program; if not, write to the Free Software Foundation, Inc., 675 Mass +Ave, Cambridge, MA 02139, USA. +

+ + + + +Indicates whether the specified Text file type supports colorization on a given +platform. + + +

+The return value is platform-dependent, and returns True if the platform +supports ANSI escape sequences in TTY output. +

+
+
Linux and Darwin (macOS)
+
+Returns True when termio indicates the file type is a TTY device. +
+
Windows
+
+Returns True when ENABLE_VIRTUAL_TERMINAL_PROCESSING can be enabled for +the Text file type. Please note that this facility is available for Windows +version 10 or higher. Previous versions cannot handle ANSI escape sequences. +
+
OS/2
+
+Returns True if DosQueryHType indicates the file type is a hardware +device and not a pipe. +
+
Go32V32 and Watcom
+
+Returns True is ANSI.SYS is available for the platform and bit 7 is set +for the Text file type. +
+
+

+The default return value is False. +

+ + + + + +Returns True if colorization is supported for the platform. + + + + +Text file type examined in the routine. + + + + + +Constant which allows compile-time removal of the coloring functionality on +unsupported platforms. + + +

+Colorization is supported for: +

+
    +
  • Linux
    • +
  • Windows (version 10+)
    • +
  • Darwin (macOS)
    • +
  • OS/2
    • +
  • Go32V2
    • +
  • WATCOM
    • +
+ + + + + + + + +Represents the colors allowed for colorized text output on a TTY device. + + +

+TOutputColor is the type passed as an argument to the +WriteColoredOutput routine. Values in the enumeration are also used +in the implementation of the Colorize routine. +

+ + + + + + + +Represents the color Black. + + +Represents the color Red. + + +Represents the color Green. + + +Represents the color Orange. + + +Represents the color Blue. + + +Represents the color Magenta. + + +Represents the color Cyan. + + +Represents the color Light Gray. + + + + +Writes text using the specified color to a Text file type when enabled. + + +

+WriteColoredOutput colorizes the value in s when +TTYCheckSupported indicates that the action is supported for the platform and +t is a TTY device. If both conditions are not met, the text in +s is not colorized and is written as-is to the Text file type. +

+

+WriteColoredOutput surrounds a write operation to t with ANSI escape +codes needed to set the text color and reset the text when done. The text color +in color uses the Bold attribute when the color is set. Both the +color and the style are removed using another ANSI escape code when the write +is completed. +

+

+See TOutputColor for the color values supported +in the routine. +

+

+Use Colorize to examine and colorize compiler- or +build-related keywords found in a string value. +

+ + + + + + + + + + +Text file type where the string value is written. + + + + +Foreground color for the specified text. + + + + +Text colorized (optional) and written in the routine. + + + + + +Gets a string with colorized compiler and build keywords. + + +

+Colorize is an AnsiString function used to examine and to +colorize any keywords found in s. +

+

+Colorize recognizes and applies colors for the following compiler- and +build-related keywords: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordColor
'Note:'oc_orange
'Hint:'oc_lightgray
'Warning:'oc_magenta
'Error:'oc_red
'(lazbuild)'oc_lightgray
'(lazarus)'oc_cyan
gtk2oc_green
+

+The keyword is surrounded by ANSI escape codes to set and reset both the color +and style for the keyword. Any text in s which is not a keyword is returned in +its unmodified form. +

+

+Use WriteColoredOutput to colorize the contents of a string and write the value +to a Text file type. +

+

+Colorize is used in the implementation of the + +WriteLnToFile method in TLazLoggerFileHandle. +

+ + + + +TLazLoggerFileHandle.WriteLnToFile + + + + +String with the value after keywords have been colorized. + + + + +String with keywords colorized in the routine. + + + + + + +