Add io_ansi:escape/2 with chardata and no format

Author: josevalim

lib/stdlib/src/io_ansi.erl

@@ -86,7 +86,7 @@ that should handle it. `io_ansi:fwrite/4` works across nodes and will use the
 
 -export([tput/1, tput/2, tigetnum/1, tigetflag/1, tinfo/0]).
 -export([format/1, format/2, format/3, fwrite/1, fwrite/2, fwrite/3, fwrite/4,
-         enabled/0, enabled/1, scan/1]).
+         enabled/0, enabled/1, scan/1, escape/1, escape/2]).
 
 -export([black/0, blue/0, cyan/0, green/0, magenta/0, red/0, white/0, yellow/0,
          color/1, color/3, default_color/0]).
@@ -2243,67 +2243,51 @@ lookup_vts(Data) ->
         KeyValueRest
     end.
 
--doc #{ equiv => format(Format, []) }.
--spec format(format()) -> unicode:unicode_binary().
-format(Format) ->
-    format(Format, []).
-
--doc #{ equiv => format(Format, Data, []) }.
--spec format(format(), Data :: [term()]) -> unicode:unicode_binary().
-format(Format, Data) ->
-    format(Format, Data, []).
+-doc #{ equiv => escape(Data, []) }.
+-spec escape([vts() | unicode:chardata()]) -> unicode:chardata().
+escape(Data) ->
+    escape(Data, []).
 
 -doc """
-Returns a character list that represents `Data` formatted in accordance with
-`Format`.
+Escapes terminal sequences in `Data`.
 
-This function works just as `io_lib:bformat/2`, except that it also allows
-atoms and tuples represeting virtual terminal sequences as part of the
-`Format` string.
+`Data` may contain either virtual terminal sequences, which are escaped,
+or `unicode:chardata()`, which are left as is.
 
-Calling `format/3` will always emit a `reset/0` VTS at the end of the returned
-string. To not emit this, set the `reset` option to `false`.
-
-To force enabling or disabling of emitting VTSs set the `enabled` option to
-`true` or `false`. By default the emitting of VTSs is enabled if `enabled/0` returns `true`
-and disabled otherwise.
-
-To disable emitting of color VTSs but still emit other VTSs, set the `color` option to `false`.
-The default color option is `true` unless the `NO_COLOR` environment variable is set to a non-empty value,
-in which case the default is `false`.
+It accepts the same options as `format/3`.
 
 Example:
 
 ```erlang
-1> io_ansi:format([blue, underline, "Hello world"]).
-~"\e[34m\e[4mHello world\e(B\e[m"
-2> io_ansi:format([blue, underline, "Hello ~p"],[world]).
-~"\e[34m\e[4mHello world\e(B\e[m"
-3> io_ansi:format([blue, underline, "Hello ~p"],[world],[{reset,false}]).
-~"\e[34m\e[4mHello world"
-4> io_ansi:format([blue, underline, "Hello ~p"],[world],[{enabled,false}]).
-~"Hello world"
-5> io_ansi:format([blue, underline, "Hello ~p"],[world],[{color,false}]).
-~"\e[4mHello world\e(B\e[m"
-6> io_ansi:format([invalid_code, "Hello world"]).
+1> io_ansi:escape([blue, underline, "Hello world"]).
+[~"\e[34m",~"\e[4m","Hello world",~"\e(B\e[m"]
+2> io_ansi:escape([blue, underline, ~"Hello world"],[{reset,false}]).
+[~"\e[34m",~"\e[4m",~"Hello world"]
+3> io_ansi:escape([blue, underline, ~"Hello world"],[{enabled,false}]).
+[~"Hello world"]
+4> io_ansi:escape([blue, underline, "Hello ", $\n, ~"world"],[{color,false}]).
+[~"\e[4m","Hello ", $\n, ~"world",~"\e(B\e[m"]
+5> io_ansi:escape([invalid_code, "Hello world"]).
 ** exception error: {invalid_code,invalid_code}
-     in function  io_ansi:format_internal/3
+     in function  io_ansi:escape_internal/5
 ```
-
-For a detailed description of the available formatting options, see `io:fwrite/3`.
 """.
--spec format(format(), Data :: [term()], options()) -> unicode:unicode_binary().
-format(Format, Data, Options) ->
-    format_internal(Format, Data, Options).
+-spec escape([vts() | unicode:chardata()], options()) -> unicode:chardata().
+escape(Data, Options) ->
+    escape_internal(Data, [], Options, false, fun
+      (Fmt, []) when is_list(Fmt); is_binary(Fmt); is_integer(Fmt) ->
+        {Fmt, []};
+
+      (_, _) ->
+        erlang:error(badarg, [Data, Options])
+    end).
 
-format_internal(Format, Data, Options) ->
+escape_internal(Format, InitAcc, Options, FormatOnly, Callback) ->
     UseAnsi = case proplists:get_value(enabled, Options) of
                     undefined -> enabled();
                     Enabled -> Enabled
               end,
-    %% Only to be used by fwrite
-    FormatOnly = proplists:get_value(format_only, Options, false),
-    AppendReset = [reset || proplists:get_value(reset, Options, true)],
+    AppendReset = proplists:get_value(reset, Options, true),
     NoColor = os:getenv("NO_COLOR"),
     DefaultColor = NoColor =:= false orelse NoColor =:= "",
     Color = proplists:get_value(color, Options, DefaultColor),
@@ -2323,20 +2307,19 @@ format_internal(Format, Data, Options) ->
                      not RenderAnsi ->
                     {Acc, Args}
                 end;
-             (Ansi, {Acc, Args}) when is_atom(Ansi); is_tuple(Ansi) ->
-                  {Acc, Args};
              (Fmt, {Acc, Args}) ->
-                  {Scanned, Rest} = io_lib_format:scan(Fmt, Args),
-                  {[io_lib_format:build_bin(Scanned) | Acc], Rest}
-          end, {[], Data}, group([Format,AppendReset])) of
+                  {Entry, Rest} = Callback(Fmt, Args),
+                  {[Entry | Acc], Rest}
+          end, {[], InitAcc}, Format) of
         {Scanned, []} ->
-            if FormatOnly ->
-                    lists:flatten(lists:reverse(Scanned));
-               not FormatOnly ->
-                    unicode:characters_to_binary(lists:reverse(Scanned))
-            end;
+            Result = if
+              UseAnsi andalso AppendReset -> [reset() | Scanned];
+              true -> Scanned
+            end,
+
+            lists:reverse(Result);
         _ ->
-            erlang:error(badarg, [Format, Data, Options])
+            erlang:error(badarg, [Format, InitAcc, Options])
     catch throw:{invalid_code, Code, []} ->
             erlang:error({invalid_code, Code});
         throw:{invalid_code, Code, Args} ->
@@ -2355,6 +2338,67 @@ is_color(AnsiKey) ->
     lists:member(AnsiKey, ColorAtoms ++ [color, background_color, underline_color,
                                          default_color, default_background, default_underline_color]).
 
+-doc #{ equiv => format(Format, []) }.
+-spec format(format()) -> unicode:unicode_binary().
+format(Format) ->
+    format(Format, []).
+
+-doc #{ equiv => format(Format, Data, []) }.
+-spec format(format(), Data :: [term()]) -> unicode:unicode_binary().
+format(Format, Data) ->
+    format(Format, Data, []).
+
+-doc """
+Returns a character list that represents `Data` formatted in accordance with
+`Format`.
+
+This function works just as `io_lib:bformat/2`, where `Data` is a list of strings
+as well as atoms and tuples representing virtual terminal sequences as part of the
+`Format` string.
+
+Calling `format/3` will always emit a `reset/0` VTS at the end of the returned
+string. To not emit this, set the `reset` option to `false`.
+
+To force enabling or disabling of emitting VTSs set the `enabled` option to
+`true` or `false`. By default the emitting of VTSs is enabled if `enabled/0` returns `true`
+and disabled otherwise.
+
+To disable emitting of color VTSs but still emit other VTSs, set the `color` option to `false`.
+The default color option is `true` unless the `NO_COLOR` environment variable is set to a non-empty value,
+in which case the default is `false`.
+
+Example:
+
+```erlang
+1> io_ansi:format([blue, underline, "Hello world"]).
+~"\e[34m\e[4mHello world\e(B\e[m"
+2> io_ansi:format([blue, underline, "Hello ~p"],[world]).
+~"\e[34m\e[4mHello world\e(B\e[m"
+3> io_ansi:format([blue, underline, "Hello ~p"],[world],[{reset,false}]).
+~"\e[34m\e[4mHello world"
+4> io_ansi:format([blue, underline, "Hello ~p"],[world],[{enabled,false}]).
+~"Hello world"
+5> io_ansi:format([blue, underline, "Hello ~p"],[world],[{color,false}]).
+~"\e[4mHello world\e(B\e[m"
+```
+
+For a detailed description of the available formatting options, see `io:fwrite/3`.
+""".
+-spec format(format(), Data :: [term()], options()) -> unicode:unicode_binary().
+format(Format, Data, Options) ->
+    Formatted = format_internal(group(Format), Data, Options, false),
+    unicode:characters_to_binary(Formatted).
+
+format_internal(Format, Data, Options, FormatOnly) ->
+    escape_internal(group(Format), Data, Options, FormatOnly, fun
+      (Fmt, Args) when is_list(Fmt) ->
+        {Scanned, Rest} = io_lib_format:scan(Fmt, Args),
+        {io_lib_format:build_bin(Scanned), Rest};
+
+      (_, _) ->
+        erlang:error(badarg, [Format, Data, Options])
+    end).
+
 -doc #{ equiv => fwrite(standard_io, Format, [], []) }.
 -spec fwrite(Format :: format()) -> ok.
 fwrite(Format) ->
@@ -2389,8 +2433,6 @@ ok
 ok
 3> io_ansi:fwrite([invalid_code, "%% Hello ~p\n"], [world]).
 ** exception error: {error,{put_ansi,unicode,invalid_code}}
-     in function  io_ansi:fwrite/4
-        called as io_ansi:fwrite(standard_io,[invalid_code,"%% Hello ~p\n"],[world],[])
 ```
 
 The decision what each VTS should be converted to is done by the destination I/O
@@ -2428,7 +2470,7 @@ fwrite(Device, Format, Data, Options) ->
                   end;
               F(_Data, Error) ->
                   throw({Ref, Error})
-          end, ok, format_internal(Format, Data, [{format_only, true} | Options]))
+          end, ok, lists:flatten(format_internal(Format, Data, Options, true)))
     catch {Ref, Error} ->
             erlang:error(Error, [Device, Format, Data, Options])
     end.