Skip to content

Versions.md

Latest commit

 

History

History
executable file
·
308 lines (230 loc) · 25.4 KB

Versions.md

File metadata and controls

executable file
·
308 lines (230 loc) · 25.4 KB

Versions

v6.0.1

Changed

  • Updated the shipped pretty-console-expert skill and its references so the packaged guidance reflects the v6 API surface.
  • Removed the stale packaged v5-api-map.md skill reference and added package cleanup for consumers that already received it.
  • Clarified LiveConsoleRegion lifecycle docs so examples use Dispose() as the normal cleanup path and describe Clear() as the reusable mid-scope hide case.
  • Refreshed README and file-based example guidance to match the current Color/Markup/AnsiToken-first model and the current package version.

v6.0.0

Added

  • Added LiveConsoleRegion for retained live output on a single OutputPipe, enabling Cargo-style durable status lines above a pinned transient region.
  • Added AnsiToken as the guarded ANSI abstraction for interpolated output.
  • Added Color as the preferred interpolation-facing color surface with cached tokens such as Color.Green, Color.DefaultForeground, Color.DefaultBackground, and Color.Default.
  • Added token-based color support across ProgressBar, Spinner, TypeWrite, and LiveConsoleRegion.RenderProgress.
  • Added Windows ANSI capability detection so PrettyConsole can avoid emitting styled ANSI output when the terminal cannot safely render it.
  • ConsoleColor remains supported for compatibility, but Color is now the preferred API for styled output.

Breaking

  • Markup now exposes guarded AnsiTokens instead of raw string escape sequences.
  • AnsiColors.Foreground(ConsoleColor) and AnsiColors.Background(ConsoleColor) now return cached AnsiTokens instead of raw ANSI strings and map to the Color cache.

v5.4.2

  • Improve perf of ReadOnlySpan based overloads of Write and WriteLine.
  • SKILL improvements
    • Highlight some points that correct invalid API assumptions made by agents.
    • Add testing section and teach agents to about ConsoleContext.

v5.4.1

  • This version now ships with a specialized AI agent skill PrettyConsoleExpert that will be copied to consumers on build.
    • This can be opt-out of - instructions are in the main README.md

v5.4.0

  • BREAKING: IndeterminateProgressBar was renamed to Spinner
    • Internal line reset is now triggered at the start of each frame render, this keeps the output after the last render. You can choose whether to override or keep the output by using Console.ClearNextLines or Console.SkipLines.
    • All overloads of RunAsync now have a default value for the CancellationToken.
    • AnimationSequence was renamed to Pattern to fit Spinner.Patterns.
  • Changes in ProgressBar
    • BREAKING: the static WriteProgressBar methods have been renamed to Render.
    • Added overloads that accept a PrettyConsoleInterpolatedStringHandlerFactory like the overloads in Spinner to allow more complex outputs at lower costs.
    • BREAKING: ReadOnlySpan<char> parameters of header, now use string instead due to language limitation that caused incorrect escape analysis with the PrettyConsoleInterpolatedStringHandlerFactory

v5.3.0

  • PrettyConsoleInterpolatedStringHandler:
    • Turned more of the methods to be public to enhance the usability of it in an advance usage (unrolling its creation). To further aid in this.
    • Added AppendInline which can inline the contents of an another PrettyConsoleInterpolatedStringHandler to the source instance and enable nested use cases.
    • Added another constructor that accepts just OutputPipe and an optional IFormatProvider.
    • Is now passed by ref to accepting methods.
  • Added SkipLines which can be used to move the cursor n amount of lines forward. This can be used to keep the output of overwritten lines, like progress bars, spinners, OverWrite and so on and forth.
  • Confirm(trueValues, ref handler, bool emptyIsTrue = true) parameters were reordered, emptyIsTrue is now the last parameter.
  • IndeterminateProgressBar overloads with the Func now use PrettyConsoleInterpolatedStringHandlerFactory instead, and usage is now (builder, out handler) => handler = builder.Build(OutputPipe.Error, $"..."). This was required to reduce compiler created struct copies and increase safety.
    • Building custom handlers is now done with PrettyConsoleInterpolatedStringHandlerBuilder which contains a thread-safe singleton; PrettyConsoleInterpolatedStringHandler.Build was removed in favor of using the builder.
  • AnsiColors which provides static utilities to convert ConsoleColor to ANSI sequences is now public (was previously internal)

v5.2.0

  • PrettyConsoleInterpolatedStringHandler was re-written to buffers interpolated content before emitting it (instead of streaming), along with other optimizations.
  • Added a WhiteSpace struct to declare padding regions; the handler recognizes it as a special argument and writes that many spaces directly into the buffer.
  • IndeterminateProgressBar gains overloads that take a Func<PrettyConsoleInterpolatedStringHandler>, letting each frame build status text with captured locals. Use PrettyConsoleInterpolatedStringHandler.Build to bind the handler to the correct OutputPipe inside the factory.

v5.1.0

  • Console.WriteInterpolated and Console.WriteLineInterpolated now return a int that contains the number of characters written using the handler. This could be used to help calculate paddings or other things when creating structured output.
    • It will ignore escape sequences that were added using the handler like ConsoleColor, Color, Markup, or any guarded AnsiToken, but if you hardcode your own they might be taken into account. As such, if you do this, I recommend first checking the length without using those helpers, then using this result for the calculation.
  • PrettyConsoleExtensions that contains the Out, Error, In, etc... was renamed to ConsoleContext.
  • The standard Out, Error, In streams now have a public setter, so end users could mock them in their own tests.
  • Console.WriteWhiteSpaces(length, OutputPipe) was added to reduce the complexity of using the TextWriter extension.

v5.0.0 - .NET 10+

This version contains a lot of breaking changes, but they were necessary to trim legacy and sub-optimal things from the library to ensure it remains the best performing library for stylized console outputs.

Removed

  • ColoredOutput is completely gone, all APIs that used it - are gone as well.
  • Color struct is gone too, extension members allowed me to rework it's uses to the built-in System.ConsoleColor.

Changed

  • All of the public facing APIs can now be invoked directly from System.Console
    • Write<T> and Write(ReadOnlySpan<char>, OutputPipe) remain by the same names.
    • Write and WriteLine that use PrettyConsoleInterpolatedStringHandler were renamed to WriteInterpolated and WriteLineInterpolated respectively - This is slightly more verbose but required to bypass overload resolution which prefers the build-in Write and WriteLine methods of System.Console.
    • Selection, Menu, Table, ReadLine, TryReadLine were all added to System.Console.
  • ConsoleColor now has static properties to allow the same semantics as Color used to.
    • ConsoleColor.DefaultForeground and ConsoleColor.DefaultBackground bind to the defaults of the shell and can be used to work with the defaults or reset colors.
    • ConsoleColor.Default returns a tuple of (DefaultForeground, DefaultBackground)
    • ConsoleColor / ConsoleColor also returns a tuple where the first the foreground and second a background.
    • ConsoleColor / (ConsoleColor, ConsoleColor) returns a tuple of the foreground, and the background from second tuple.
    • Those can be used with the string handler $"{ConsoleColor.Red}Hello{ConsoleColor.Default}" to write colored zero allocation outputs.
  • ProgressBar and IndeterminateProgressBar are no longer nested classes of Console (since it doesn't exist anymore) - this can affect your using statements.

Added

  • TextWriter which is the object backing Console.Out and Console.Error now has a static extension WriteWhiteSpaces(int), which can be used to write paddings and whatever else without any allocations. It was previously an internal method but I chose to expose it for all of you.
  • Markup static class provides ANSI escape-sequence toggles (underline, bold, italic, strikethrough) that automatically collapse to empty strings when output/error are redirected, so callers can opt into inline decorations without additional checks.
  • PrettyConsoleInterpolatedStringHandler now exposes a duration format for TimeSpan values (formerly hr) that emits Xh Ym Zs and a bytes format for double values that scales through B/KB/MB/... with culture-aware separators.
  • ProgressBar.WriteProgressBar (and the instance helper via ProgressBar.MaxLineWidth) now accept an optional maxLineWidth so the full [=====] 42% line can be constrained for columnar layouts without overflowing the buffer.

v4.1.0

Added

  • ProgressBar now includes a static method WriteProgressBar which renders a static progress bar with the set parameters, it can be used in conjunction with Overwrite to create multi-progress-bars UI.
  • ProgressBar.Update overloads now include an optional parameter sameLine which configures whether to render the progress bar at the same of the status. It is set to true by default to keep current behavior.

Fixed

  • ProgressBar.ForegroundColor docs were fixed (they previously were the same as ProgressColor) which is invalid.
  • ProgressBar in all variations now shows progress as a round number suffixed by %.
  • ProgressBar no longer tracks if the percentage is changed, being that the numbers are round, percentage could progress or status needs to be re-written while it stays the same when rounded.
  • Methods that overwrite lines, now have a note in the remarks to clear the used lines after the last call, to prevent artifacts.

v4.0.0

Added

  • PrettyConsoleInterpolatedStringHandler was added to allow streaming zero allocation formatted and styled outputs to console pipes. With supported overloads for:
    • Write and WriteLine
    • ReadLine and TryReadLine
    • Selection and MultiSelection
    • Overwrite is a wrapper around an action of displaying outputs, with or without closures using TState, it enables you to use a lambda and call the PrettyConsoleInterpolatedStringHandler methods inside, to create zero allocation reactive and refreshable components.
    • To customize colors, use Color as an interpolation parameter at the correct place, and restore the colors with Color.Default. for example: WriteLine($"This is in {Color.Green}green{Color.Default} and this is in {Color.Red}red{Color.Default}.");, all overloads that accept the interpolation reset the color at the end, so you can omit Color.Default if you colored the last section of your string.
    • The same conventions and syntax of setting Foreground / Background colors works here as well.
  • IndeterminateProgressBar will now allow customization of the animated sequence via the property AnimationSequence, and it also includes an inner class Patterns that contains some constant sequences that could be used with it.

Fixed

  • Fixed issue that could sometimes cause writing into buffers beyond their bounds - throwing an exception. Possibly effected:
    • ProgressBar and IndeterminateProgressBar
    • ClearNextLines
  • IndeterminateProgressBar.UpdateRate is 200 ms by default.
  • IndeterminateProgressBar header is now positioned right of the animation. Similar to common CLIs.
  • ProgressBar had numeral optimizations and should perform better in all scenarios.
  • OverrideCurrentLine was renamed to OverwriteCurrentLine to be more semantically correct.

Also

  • Dropped Sharpify as a dependency - PrettyConsole is now self-sufficient.

v3.1.0

  • Updated to support .NET 9.0
  • Updated to use Sharpify 2.5.0
  • ProgressBar was redesigned since it randomly produced artifacts such as printing the header multiple times.
    • Now the buffer area of ProgressBar is only 1 line, the (now "status") is printed on the same line, after the bar
    • Only if the header is empty, the percentage is printed instead.
    • An internal lock is now also used to prevent race conditions.
  • ClearNextLines show now work properly, previously it could actually clear 1 line too many.

Breaking changes

  • OutputPipe enum was added to unify APIs
  • ClearNextLinesError was removed, use ClearNextLines with OutputPipe.Error instead
  • NewLineError was removed, use NewLine with OutputPipe.Error instead
  • WriteError was removed, use Write with OutputPipe.Error instead
  • WriteLineError was removed, use WriteLine with OutputPipe.Error instead
  • OverrideCurrentLine now has an option to choose the output pipe, use OutputPipe.Error by default
  • Write<T> had the same treatment, now it has an option to choose the output pipe, use OutputPipe.Out by default, so the overload of WriteError<T> were removed
  • WriteLine<T> and WriteLine(ReadOnlySpan<char>) were introduced thanks to this change

v3.0.0

  • Removed Write and WriteLine overloads that contains multiple ColoredOutputs, when using the overload with ReadOnlySpan<ColoredOutput> and CollectionExpression, the compiler generates an inline array to hold the elements, this is very efficient, and the reduced complexity allows usage of multiple ColoredOutputs in more places.
  • All overloads of all functions that previously took only one ColoredOutput now take a ReadOnlySpan<ColoredOutput> instead, as noted it will use an inline array, and the internal implementation also has fast paths for size 1.
  • All fast changing outputs (ProgressBar, IndeterminateProgressBar, OverrideCurrentLine) now uses the error output pipe by default, this means that if the consumer will pipe the output to another cli, it won't be filled with garbage and retain only the valuable stuff.
  • Added ReadOnlySpan<ColoredOutput> overloads to WriteError and WriteLineError.
  • Added overloads for all variants of ReadLine and TryReadLine that support T @default that will be returned if parsing fails.
  • Write, WriteLine, WriteError and WriteLineError no longer have params ColoredOutput[] overloads, they instead have a ReadOnlySpan<ColoredOutput> overload. This performs even better as it uses an inline array, and the removal of the restrictions on where params can be used, allowed ReadOnlySpan<ColoredOutput> to replace virtually allow single ColoredOutput methods as well. Allowing greater customization in any function.
  • You can now access the In, Out, and Error streams of System.Console directly from PrettyConsole.Console by using the properties Out, Error, and In. This reduces verbosity since the names of the classes have collisions.
  • Added SetColors to allow setting the colors of the console output.
  • ClearNextLines now also has a ClearNextLinesError brother which does the same for the Error stream.
  • NewLineError was also added for this.
  • To enhance customization in extreme high perf scenarios where you write a ReadOnlySpan<char> directly to the output stream, the Write and WriteError methods now have overloads that take a ReadOnlySpan<char> instead of a ReadOnlySpan<ColoredOutput>, along with foreground and background colors.
  • Added Write and WriteError variants for T : ISpanFormattable as well.
  • ProgressBar should now be even more performant as internal progress tracking allowed cutting the required operations by 20%.
  • Color will now contain static readonly ConsoleColor fields for both Foreground and Background colors, they will be initialized during runtime to support all platforms (fixing the instant crashes on Windows).
    • You can also refer them when you want to use the defaults for any reason.
  • The base methods which are used for outputting ReadOnlySpan<ColoredOutput> have been re-written to reduce assembly instructions, leading to about 15-20% runtime improvements across the board, and reducing by the binary size by a few bytes too lol.
  • Console and Color now have the correct attributes to disallow compilation on unsupported platforms, if anyone tries to use them now (even thought it should've been obvious that they shouldn't be used on unsupported platforms), it should display the right message at build time.
  • Removed all overloads that have options to change the input colors, it invites non-streamlined usage, and just increases the code complexity to maintain. Without them the code is simpler and more performant.
  • A lot of methods that used white-spaces in any shape or form were now optimized using pre-initialized static buffer.
  • IndeterminateProgressBar now has overloads that accept a string header that can be displayed before the progress char. There also was a change involving a secondary addition of catching the CancellationToken, removing up to 5 internal iterations.
  • Added GetCurrentLine and GoToLine methods to allow efficiently using the same space in the console for continuous output, such as progress outputting, and general control flow.

v2.1.1

  • Removed redirection of ReadOnlySpan<char> print overload that degraded performance.
  • Improved internal handling of array and memory pooling.
  • Decreased formatted length limit for ISpanFormattable to 50 characters, as it was too long and frequent calls could cause the os to lag. Also changed to use rented buffer instead of stack allocation.

v2.1.0

  • Fixed default colors, previously colors where defaulted to Color.Gray for foreground and Color.Black for background, however many shells have custom colors that they render by default, which means the default colors seemed to render in a non ordinary fashion. The default colors now are Color.Unknown which will actually use the colors of the shell.
  • ProgressBar now implements IDisposable since the implementation has been optimized, make sure to dispose of it, lest you induce a penalty on other such optimization which are now spread across the library.
  • Introduced an overload to Write that accepts any T : ISpanFormattable. In many cases users might want to print structs or other types that implement this interface such as int, double, DateTime and more... splitting the output into a few lines and using this overload will enable you completely avoid the string allocation for this object, the overload is very optimized, writes it directly to the stack and prints it using a span. However, this limitation means that if the formatted item is longer than 256 characters, an exception will be thrown indicating that you should use a different overload.

v2.0.0

  • All previous variants of output types were removed, now the main output type is ColoredOutput (which includes a string, foreground color and background color). Thanks to implicit and other converters and the added supporting Color class, usage is even simpler, and much more performant.
  • Overloads of many functions were changed, many were deleted.
  • ReadLine<T> and new overloads TryReadLine<T> now support reflection free parsing for any IParsable<T> implementing types (which are most of the base types, and you can create any custom implementations if you choose so).
  • ReadLine now also has an Enum overload that can parse for enums, with configurable case sensitivity.
  • Many functions, especially more advance outputs such as selections, menus and progress bar, had undergone tremendous performance optimizations, and show now perform extremely efficiently.
  • A new table view implementation was added.
  • The progress bar types ProgressBar and IndeterminateProgressBar are now classes, and also have been substantially optimized.

v1.6.1

  • TextRenderingScheme type was added for better handling of outputs consisting of mixed colors
  • TypeWrite now has a TextRenderingScheme overload and the delay in all overloads was increased to 200 (ms) to look more natural
  • Write, WriteLine, ReadLine and OverrideCurrentLine now also have overloads with TextRenderingScheme, and they are the recommended ones for mixed color use, using them instead of the params array overload may allow further optimization during JIT compilation
  • Write and WriteLine now have overloads for ReadOnlySpan<char> for even better performance
  • More try-finally blocks have been implemented to further reduce the possibility of render failure upon exceptions
  • More methods have been re-implemented to call their overloads for better maintainability and consistency
  • More methods were marked as Pure to provide more information to the end users
  • After testing it became rather clear, the best way to avoid glitches in frequently updated outputs inside event handlers, such as ProgressBar, OverrideCurrentLine and the likes is to firstly create an early return based on elapsed time after previous render, secondly, Use the [MethodImpl(MethodImplOptions.Synchronized)] On the event, and if the output is a Task, use .Wait instead of making the event async and awaiting it
  • ProgressBarDisplay was modified to be a record struct instead of ref struct, This is aimed to increase usage flexibility which is limited with ref structs, Also it may increase performance in edge cases due to higher potential for compiler optimization

v1.6.0

  • Re-structured Console as a static partial class into many files to separate the code into categorized section for better maintainability and improved workflow for adding new features
  • Removed synchronized method compiler enforcements that could in some case limit usage flexibility when intentionally using Tasks, if that feature is needed, simply create your own wrapper method with the attribute
  • Update all places where the color of the output is changed to use try-finally block to ensure color reset even if an exception was thrown, which before could cause bugged colors
  • Added more safeguards in key places
  • Improved performance of various methods
  • Merged closely related method implementations to reduce possibility of future errors
  • [POSSIBLE BREAKING CHANGE] ProgressBarDisplay has been restructured to safeguard against improper initialization. Also a ProgressChar property was added to allow further customization of the progress bar look
  • Added TypeWrite and TypeWriteLine methods that provide a simple type-writer effect for text.
  • Fixed issue in RequestAnyInput that could read a pre-existing character from the input stream and accept it, basically skipping the entire request.

v1.5.2

  • FROM THIS VERSION ON, THE PACKAGE WILL BE SIGNED
  • Updated many string interpolation instances to use string.Concat instead to improve performance
  • Modified calculations in progress bars to use functions which are more hardware optimized
  • Modified evaluated strings in progress bars to only be printed when done
  • Added direction to synchronize progress bars to reduce buggy outputs
  • Updated csproj file for better compatibility with the nuget website

This is a quality of life update, in most use cases the performance benefit, whether time wise or memory allocation will be visible and sometimes very significant.

This update doesn't introduce any breaking changes so updating is highly encouraged.

v1.5.1

  • Fixed issues with progress bar where the next override could keep artifacts of previous render.
  • Added OverrideCurrentLine() which allows showing of progress with string only.
  • Added ClearNextLines(num) which allows to remove next num lines, this is useful when something overriding was used, such as progress bar, but after parts of are left because the new output is shorter.

v1.5.0

  • Optimized code across the board for better performance and less memory allocation
  • Improved organization and documentation
  • Added more method overloads
  • Added options to output errors to error pipeline to improve stds down the line
  • Added trimming safe overloads for generic methods
  • Added trim warnings for generic and reflection methods
  • Added optional header to the progress bar

v1.4.0

  • Greatly improved performance by taking generics or strings into output methods instead of objects to avoid boxing.

Upgrade notes

  • Most methods, including Write and WriteLine with single parameter should not require any code modification as they will use generics
  • Outputs methods which use tuples will require modification to enjoy the performance upgrade, with that said, existing code will be break because legacy object implementation was not removed but rather just marked as obsolete for now.

v1.3.0

  • Fixed memory leak in TreeMenu
  • Improved performance and reduced complexity
  • Removed Colors.Primary - it reduced uniformity as default was very close in color. Now default will be used in place of both, if you like primary more, consider overriding the Colors.Default to ConsoleColor.White
  • Added Labels - outputs with configurable background color.

v1.2.0

  • Removed Color enum, use the Colors property instead
  • Added progress bars, both regular and indeterminate
  • Added documentation file so summaries will be visible

v1.1.0

  • Added indeterminate progress-bar
  • Added regular progress-bar
  • Changed parameter-less Write and WriteLine to use color version with default values to trim unnecessary code.

v1.0.2

  • Changed secondary color to be called the default color and also act as such, meaning by default Write and WriteLine will use it
  • Internal outputs such as ReadLine or others will still use primary color

v1.0.1

  • Moved Color enum into Console to reduce using statements
  • Changed accessibility of extensions, they were meant to be used internally