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| }