src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/eval/builtin_fn_styled.d.elv (about)

     1  # Constructs a styled segment, a building block for styled texts.
     2  #
     3  # - If `$object` is a string, constructs a styled segment with `$object` as the
     4  #   content, and the properties specified by the options.
     5  #
     6  # - If `$object` is a styled segment, constructs a styled segment that is a
     7  #   copy of `$object`, with the properties specified by the options overridden.
     8  #
     9  # The properties of styled segments can be inspected by indexing into it. Valid
    10  # keys are the same as the options to `styled-segment`, plus `text` for the
    11  # string content:
    12  #
    13  # ```elvish-transcript
    14  # ~> var s = (styled-segment abc &bold)
    15  # ~> put $s[text]
    16  # ▶ abc
    17  # ~> put $s[fg-color]
    18  # ▶ default
    19  # ~> put $s[bold]
    20  # ▶ $true
    21  # ```
    22  #
    23  # Prefer the high-level [`styled`]() command to build and transform styled
    24  # texts. Styled segments are a low-level construct, and you only have to deal
    25  # with it when building custom style transformers.
    26  #
    27  # In the following example, a custom transformer sets the `inverse` property
    28  # for every bold segment:
    29  #
    30  # ```elvish
    31  # styled foo(styled bar bold) {|x| styled-segment $x &inverse=$x[bold] }
    32  # # transforms "foo" + bold "bar" into "foo" + bold and inverse "bar"
    33  # ```
    34  fn styled-segment {|object &fg-color=default &bg-color=default &bold=$false &dim=$false &italic=$false &underlined=$false &blink=$false &inverse=$false| }
    35  
    36  # Constructs a **styled text** by applying the supplied transformers to the
    37  # supplied `$object`, which may be a string, a [styled
    38  # segment](#styled-segment), or an existing styled text.
    39  #
    40  # Each `$style-transformer` can be one of the following:
    41  #
    42  # - A boolean attribute name:
    43  #
    44  #   - One of `bold`, `dim`, `italic`, `underlined`, `blink` and `inverse` for
    45  #     setting the corresponding attribute.
    46  #
    47  #   - An attribute name prefixed by `no-` for unsetting the attribute.
    48  #
    49  #   - An attribute name prefixed by `toggle-` for toggling the attribute
    50  #     between set and unset.
    51  #
    52  # - A color name for setting the text color, which may be one of the
    53  #   following:
    54  #
    55  #   - One of the 8 basic ANSI colors: `black`, `red`, `green`, `yellow`,
    56  #     `blue`, `magenta`, `cyan` and `white`.
    57  #
    58  #   - The bright variant of the 8 basic ANSI colors, with a `bright-` prefix.
    59  #
    60  #   - Any color from the xterm 256-color palette, as `colorX` (such as
    61  #     `color12`).
    62  #
    63  #   - A 24-bit RGB color written as `#RRGGBB` (such as `'#778899'`).
    64  #
    65  #     **Note**: You need to quote such values, since an unquoted `#` introduces
    66  #     a comment (e.g. use `'bg-#778899'` instead of `bg-#778899`).
    67  #
    68  # - A color name prefixed by `fg-` to set the foreground color. This has
    69  #   the same effect as specifying the color name without the `fg-` prefix.
    70  #
    71  # - A color name prefixed by `bg-` to set the background color.
    72  #
    73  # - A function that receives a styled segment as the only argument and outputs
    74  #   a single styled segment, which will be applied to all the segments.
    75  #
    76  # When a styled text is converted to a string the corresponding
    77  # [ANSI SGR code](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_.28Select_Graphic_Rendition.29_parameters)
    78  # is built to render the style.
    79  #
    80  # If the [`NO_COLOR`](https://no-color.org) environment variable is set and
    81  # non-empty when Elvish starts, color output is suppressed. Modifications to
    82  # `NO_COLOR` within Elvish (including from `rc.elv`) do not affect the current
    83  # process, but will affect child Elvish processes.
    84  #
    85  # Examples:
    86  #
    87  # ```elvish
    88  # echo (styled foo red bold) # prints red bold "foo"
    89  # echo (styled (styled foo red bold) green) # prints green bold "foo"
    90  # ```
    91  #
    92  # A styled text can contain multiple [segments](#styled-segment) with different
    93  # styles. Such styled texts can be constructed by concatenating multiple styled
    94  # texts with the [compounding](language.html#compounding) syntax. Strings and
    95  # styled segments are automatically "promoted" to styled texts when
    96  # concatenating. Examples:
    97  #
    98  # ```elvish
    99  # echo foo(styled bar red) # prints "foo" + red "bar"
   100  # echo (styled foo bold)(styled bar red) # prints bold "foo" + red "bar"
   101  # ```
   102  #
   103  # The individual segments in a styled text can be extracted by indexing:
   104  #
   105  # ```elvish
   106  # var s = (styled abc red)(styled def green)
   107  # put $s[0] $s[1]
   108  # ```
   109  #
   110  # When printed to the terminal, a styled text is not affected by any existing
   111  # SGR styles in effect, and it will always reset the SGR style afterwards. For
   112  # example:
   113  #
   114  # ```elvish
   115  # print "\e[1m"
   116  # echo (styled foo red)
   117  # echo bar
   118  # # "foo" will be printed as red, but not bold
   119  # # "bar" will be printed without any style
   120  # ```
   121  #
   122  # See also [`render-styledown`]().
   123  fn styled {|object @style-transformer| }
   124  
   125  #doc:added-in 0.21
   126  # Renders "styledown" markup into a styled text. For the styledown markup
   127  # format, see <https://pkg.go.dev/src.elv.sh@master/pkg/ui/styledown>.
   128  #
   129  # Examples:
   130  #
   131  # ```elvish-transcript
   132  # ~> render-styledown '
   133  #    foo bar
   134  #    *** ###
   135  #    '[1..]
   136  # ▶ [^styled (styled-segment foo &bold) ' ' (styled-segment bar &inverse) "\n"]
   137  # ```
   138  #
   139  # To see the rendered text in the terminal, pass it to [`print`](), like
   140  # `render-styledown ... | print (one)`.
   141  #
   142  # See also [`styled`]().
   143  fn render-styledown {|s| }