From c15b06424482d28f95866cd94ffbac0b54be8db4 Mon Sep 17 00:00:00 2001 From: Robin Wieschendorf Date: Fri, 17 Nov 2023 00:46:42 +0100 Subject: [PATCH] docs: improve docblocks for TextRenderer --- src/Classes/Cli/TextRenderer.php | 147 ++++++++++++++++++++++++++----- 1 file changed, 126 insertions(+), 21 deletions(-) diff --git a/src/Classes/Cli/TextRenderer.php b/src/Classes/Cli/TextRenderer.php index 885683d0..abdff76f 100644 --- a/src/Classes/Cli/TextRenderer.php +++ b/src/Classes/Cli/TextRenderer.php @@ -13,27 +13,72 @@ namespace RobinTheHood\ModifiedModuleLoaderClient\Cli; +/** + * Class TextRenderer + * + * A utility class for rendering text with various formatting options. + * + * @package RobinTheHood\ModifiedModuleLoaderClient\Cli + */ class TextRenderer { + /** + * ANSI color code for red. + */ public const COLOR_RED = 31; + + /** + * ANSI color code for green. + */ public const COLOR_GREEN = 32; + + /** + * ANSI color code for yellow. + */ public const COLOR_YELLOW = 33; + /** + * Generate a module link with a given archive name and title. + * + * @param string $archiveName The name of the module archive. + * @param string $title The title of the module link. + * @return string The generated module link. + */ public static function moduleLink(string $archiveName, string $titel): string { return self::link('https://module-loader.de/modules/' . $archiveName, $titel); } + /** + * Generate a link with a given URL and title. + * + * @param string $url The URL for the link. + * @param string $title The title of the link. + * @return string The generated link. + */ public static function link(string $url, string $titel): string { return "\e]8;;$url\e\\$titel\e]8;;\e\\"; } + /** + * Apply color to a given text using ANSI color codes. + * + * @param string $text The text to be colored. + * @param int $color The ANSI color code. + * @return string The colored text. + */ public static function color(string $text, int $color): string { return "\e[" . $color . "m" . $text . "\e[0m"; } + /** + * Remove ANSI escape sequences related to colors from a given text. + * + * @param string $text The text with escape sequences. + * @return string The text with escape sequences removed. + */ public static function stripEscapeSequencesColor(string $text): string { // Muster für Escape-Sequenzen finden und ersetzen @@ -46,6 +91,12 @@ public static function stripEscapeSequencesColor(string $text): string return $filteredString; } + /** + * Remove ANSI escape sequences related to links from a given text. + * + * @param string $text The text with escape sequences. + * @return string The text with escape sequences removed. + */ public static function stripEscapeSequenceLink(string $text): string { // Muster für Escape-Sequenzen finden und ersetzen @@ -58,6 +109,12 @@ public static function stripEscapeSequenceLink(string $text): string return $filteredString; } + /** + * Remove both color and link-related ANSI escape sequences from a given text. + * + * @param string $text The text with escape sequences. + * @return string The text with escape sequences removed. + */ public static function stripEscapeSequences(string $text): string { $strippedText = $text; @@ -66,6 +123,12 @@ public static function stripEscapeSequences(string $text): string return $strippedText; } + /** + * Get the length of the text without ANSI escape sequences. + * + * @param string $text The text with or without escape sequences. + * @return int The length of the text without escape sequences. + */ public static function getTextLength(string $text): int { $strippedText = self::stripEscapeSequences($text); @@ -73,6 +136,13 @@ public static function getTextLength(string $text): int return $textLength; } + /** + * Right pad a text with spaces to meet the specified total length. + * + * @param string $text The text to be padded. + * @param int $totalLength The desired total length. + * @return string The padded text. + */ public static function rightPad(string $text, int $totalLength): string { $paddingLength = self::getPadLength($text, $totalLength); @@ -80,6 +150,13 @@ public static function rightPad(string $text, int $totalLength): string return $text . $padding; } + /** + * Left pad a text with spaces to meet the specified total length. + * + * @param string $text The text to be padded. + * @param int $totalLength The desired total length. + * @return string The padded text. + */ public static function leftPad(string $text, int $totalLength): string { $paddingLength = self::getPadLength($text, $totalLength); @@ -87,6 +164,13 @@ public static function leftPad(string $text, int $totalLength): string return $padding . $text; } + /** + * Get the padding length required to meet the specified total length. + * + * @param string $text The text to be padded. + * @param int $totalLength The desired total length. + * @return int The calculated padding length. + */ private static function getPadLength(string $text, int $totalLength): int { $textLength = self::getTextLength($text); @@ -99,6 +183,12 @@ private static function getPadLength(string $text, int $totalLength): int return $paddingLength; } + /** + * Get the maximum length among an array of strings. + * + * @param string[] $items An array of strings. + * @return int The maximum length among the strings. + */ public static function getMaxLength(array $items): int { $maxLength = 0; @@ -112,11 +202,12 @@ public static function getMaxLength(array $items): int } /** - * @deprecated 1.21.0 Use a `HelpRenderer` instead. + * Render a heading for help information (deprecated). * - * @param string $heading + * @deprecated 1.21.0 Use a `HelpRenderer` instead. * - * @return string + * @param string $heading The heading text. + * @return string The rendered heading. */ public static function renderHelpHeading(string $heading): string { @@ -124,13 +215,14 @@ public static function renderHelpHeading(string $heading): string } /** - * @deprecated 1.21.0 Use a `HelpRenderer` instead. + * Render a command for help information (deprecated). * - * @param string $name - * @param string $description - * @param int $pad + * @deprecated 1.21.0 Use a `HelpRenderer` instead. * - * @return string + * @param string $name The command name. + * @param string $description The command description. + * @param int $pad The padding length. + * @return string The rendered command. */ public static function renderHelpCommand(string $name, string $description, int $pad = 20): string { @@ -139,13 +231,14 @@ public static function renderHelpCommand(string $name, string $description, int } /** - * @deprecated 1.21.0 Use a `HelpRenderer` instead. + * Render an argument for help information (deprecated). * - * @param string $name - * @param string $description - * @param int $pad + * @deprecated 1.21.0 Use a `HelpRenderer` instead. * - * @return string + * @param string $name The argument name. + * @param string $description The argument description. + * @param int $pad The padding length. + * @return string The rendered argument. */ public static function renderHelpArgument(string $name, string $description, int $pad = 20): string { @@ -154,17 +247,22 @@ public static function renderHelpArgument(string $name, string $description, int } /** - * @deprecated 1.21.0 Use a `HelpRenderer` instead. + * Render an option for help information (deprecated). * - * @param string $shortName - * @param string $longName - * @param string $description - * @param int $pad + * @deprecated 1.21.0 Use a `HelpRenderer` instead. * - * @return string + * @param string $shortName The short option name. + * @param string $longName The long option name. + * @param string $description The option description. + * @param int $pad The padding length. + * @return string The rendered option. */ - public static function renderHelpOption(string $shortName, string $longName, string $description, int $pad = 20): string - { + public static function renderHelpOption( + string $shortName, + string $longName, + string $description, + int $pad = 20 + ): string { $name = ''; if ($shortName && $longName) { @@ -179,6 +277,13 @@ public static function renderHelpOption(string $shortName, string $longName, str return " " . self::color($name, self::COLOR_GREEN) . " $description\n"; } + /** + * Render a table with the given content and settings. + * + * @param array $content The content of the table. + * @param array $settings The settings for each column (left or right alignment). + * @return string The rendered table. + */ public static function renderTable(array $content, array $settings): string { $columns = [];