Add support for moving the cursor

src/Spectre.Console/AnsiConsole.cs

@@ -27,6 +27,11 @@ namespace Spectre.Console
         /// </summary>
         public static IAnsiConsole Console => _recorder ?? _console.Value;
 
+        /// <summary>
+        /// Gets the <see cref="IAnsiConsoleCursor"/>.
+        /// </summary>
+        public static IAnsiConsoleCursor Cursor => _recorder?.Cursor ?? _console.Value.Cursor;
+
         /// <summary>
         /// Gets the console's capabilities.
         /// </summary>
@@ -56,7 +61,7 @@ namespace Spectre.Console
         /// <returns>An <see cref="IAnsiConsole"/> instance.</returns>
         public static IAnsiConsole Create(AnsiConsoleSettings settings)
         {
-            return AnsiConsoleBuilder.Build(settings);
+            return BackendBuilder.Build(settings);
         }
     }
 }

src/Spectre.Console/CursorDirection.cs

@@ -0,0 +1,28 @@
+namespace Spectre.Console
+{
+    /// <summary>
+    /// Represents cursor direction.
+    /// </summary>
+    public enum CursorDirection
+    {
+        /// <summary>
+        /// Up
+        /// </summary>
+        Up,
+
+        /// <summary>
+        /// Down
+        /// </summary>
+        Down,
+
+        /// <summary>
+        /// Left
+        /// </summary>
+        Left,
+
+        /// <summary>
+        /// Right
+        /// </summary>
+        Right,
+    }
+}

src/Spectre.Console/Extensions/CursorExtensions.cs

@@ -0,0 +1,152 @@
+namespace Spectre.Console
+{
+    /// <summary>
+    /// Contains extension methods for <see cref="IAnsiConsoleCursor"/>.
+    /// </summary>
+    public static class CursorExtensions
+    {
+        /// <summary>
+        /// Shows the cursor.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        public static void Show(this IAnsiConsoleCursor cursor)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Show(true);
+        }
+
+        /// <summary>
+        /// Hides the cursor.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        public static void Hide(this IAnsiConsoleCursor cursor)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Show(false);
+        }
+
+        /// <summary>
+        /// Moves the cursor up.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        public static void MoveUp(this IAnsiConsoleCursor cursor)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Up, 1);
+        }
+
+        /// <summary>
+        /// Moves the cursor up.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        /// <param name="steps">The number of steps to move the cursor.</param>
+        public static void MoveUp(this IAnsiConsoleCursor cursor, int steps)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Up, steps);
+        }
+
+        /// <summary>
+        /// Moves the cursor down.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        public static void MoveDown(this IAnsiConsoleCursor cursor)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Down, 1);
+        }
+
+        /// <summary>
+        /// Moves the cursor down.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        /// <param name="steps">The number of steps to move the cursor.</param>
+        public static void MoveDown(this IAnsiConsoleCursor cursor, int steps)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Down, steps);
+        }
+
+        /// <summary>
+        /// Moves the cursor to the left.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        public static void MoveLeft(this IAnsiConsoleCursor cursor)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Left, 1);
+        }
+
+        /// <summary>
+        /// Moves the cursor to the left.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        /// <param name="steps">The number of steps to move the cursor.</param>
+        public static void MoveLeft(this IAnsiConsoleCursor cursor, int steps)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Left, steps);
+        }
+
+        /// <summary>
+        /// Moves the cursor to the right.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        public static void MoveRight(this IAnsiConsoleCursor cursor)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Right, 1);
+        }
+
+        /// <summary>
+        /// Moves the cursor to the right.
+        /// </summary>
+        /// <param name="cursor">The cursor.</param>
+        /// <param name="steps">The number of steps to move the cursor.</param>
+        public static void MoveRight(this IAnsiConsoleCursor cursor, int steps)
+        {
+            if (cursor is null)
+            {
+                throw new System.ArgumentNullException(nameof(cursor));
+            }
+
+            cursor.Move(CursorDirection.Right, steps);
+        }
+    }
+}

src/Spectre.Console/Extensions/ExceptionExtensions.cs

@@ -1,4 +1,5 @@
 using System;
+using Spectre.Console.Internal;
 using Spectre.Console.Rendering;
 
 namespace Spectre.Console

src/Spectre.Console/IAnsiConsole.cs

@@ -18,6 +18,11 @@ namespace Spectre.Console
         /// </summary>
         Encoding Encoding { get; }
 
+        /// <summary>
+        /// Gets the console cursor.
+        /// </summary>
+        IAnsiConsoleCursor Cursor { get; }
+
         /// <summary>
         /// Gets the buffer width of the console.
         /// </summary>
@@ -28,6 +33,12 @@ namespace Spectre.Console
         /// </summary>
         int Height { get; }
 
+        /// <summary>
+        /// Clears the console.
+        /// </summary>
+        /// <param name="home">If the cursor should be moved to the home position.</param>
+        void Clear(bool home);
+
         /// <summary>
         /// Writes a string followed by a line terminator to the console.
         /// </summary>

src/Spectre.Console/IAnsiConsoleCursor.cs

@@ -0,0 +1,28 @@
+namespace Spectre.Console
+{
+    /// <summary>
+    /// Represents the console's cursor.
+    /// </summary>
+    public interface IAnsiConsoleCursor
+    {
+        /// <summary>
+        /// Shows or hides the cursor.
+        /// </summary>
+        /// <param name="show"><c>true</c> to show the cursor, <c>false</c> to hide it.</param>
+        void Show(bool show);
+
+        /// <summary>
+        /// Sets the cursor position.
+        /// </summary>
+        /// <param name="column">The column to move the cursor to.</param>
+        /// <param name="line">The line to move the cursor to.</param>
+        void SetPosition(int column, int line);
+
+        /// <summary>
+        /// Moves the cursor relative to the current position.
+        /// </summary>
+        /// <param name="direction">The direction to move the cursor.</param>
+        /// <param name="steps">The number of steps to move the cursor.</param>
+        void Move(CursorDirection direction, int steps);
+    }
+}

src/Spectre.Console/Internal/Backends/Ansi/AnsiBackend.cs

@@ -5,13 +5,15 @@ using Spectre.Console.Rendering;
 
 namespace Spectre.Console.Internal
 {
-    internal sealed class AnsiConsoleRenderer : IAnsiConsole
+    internal sealed class AnsiBackend : IAnsiConsole
     {
         private readonly TextWriter _out;
         private readonly AnsiBuilder _ansiBuilder;
+        private readonly AnsiCursor _cursor;
 
         public Capabilities Capabilities { get; }
         public Encoding Encoding { get; }
+        public IAnsiConsoleCursor Cursor => _cursor;
 
         public int Width
         {
@@ -39,7 +41,7 @@ namespace Spectre.Console.Internal
             }
         }
 
-        public AnsiConsoleRenderer(TextWriter @out, Capabilities capabilities, ILinkIdentityGenerator? linkHasher)
+        public AnsiBackend(TextWriter @out, Capabilities capabilities, ILinkIdentityGenerator? linkHasher)
         {
             _out = @out ?? throw new ArgumentNullException(nameof(@out));
 
@@ -47,6 +49,17 @@ namespace Spectre.Console.Internal
             Encoding = _out.IsStandardOut() ? System.Console.OutputEncoding : Encoding.UTF8;
 
             _ansiBuilder = new AnsiBuilder(Capabilities, linkHasher);
+            _cursor = new AnsiCursor(this);
+        }
+
+        public void Clear(bool home)
+        {
+            Write(Segment.Control("\u001b[2J"));
+
+            if (home)
+            {
+                Cursor.SetPosition(0, 0);
+            }
         }
 
         public void Write(Segment segment)

src/Spectre.Console/Internal/Backends/Ansi/AnsiCursor.cs

@@ -0,0 +1,56 @@
+using System;
+using Spectre.Console.Rendering;
+
+namespace Spectre.Console.Internal
+{
+    internal sealed class AnsiCursor : IAnsiConsoleCursor
+    {
+        private readonly AnsiBackend _renderer;
+
+        public AnsiCursor(AnsiBackend renderer)
+        {
+            _renderer = renderer ?? throw new ArgumentNullException(nameof(renderer));
+        }
+
+        public void Show(bool show)
+        {
+            if (show)
+            {
+                _renderer.Write(Segment.Control("\u001b[?25h"));
+            }
+            else
+            {
+                _renderer.Write(Segment.Control("\u001b[?25l"));
+            }
+        }
+
+        public void Move(CursorDirection direction, int steps)
+        {
+            if (steps == 0)
+            {
+                return;
+            }
+
+            switch (direction)
+            {
+                case CursorDirection.Up:
+                    _renderer.Write(Segment.Control($"\u001b[{steps}A"));
+                    break;
+                case CursorDirection.Down:
+                    _renderer.Write(Segment.Control($"\u001b[{steps}B"));
+                    break;
+                case CursorDirection.Right:
+                    _renderer.Write(Segment.Control($"\u001b[{steps}C"));
+                    break;
+                case CursorDirection.Left:
+                    _renderer.Write(Segment.Control($"\u001b[{steps}D"));
+                    break;
+            }
+        }
+
+        public void SetPosition(int column, int line)
+        {
+            _renderer.Write(Segment.Control($"\u001b[{line};{column}H"));
+        }
+    }
+}

src/Spectre.Console/Internal/Backends/BackendBuilder.cs

@@ -3,7 +3,7 @@ using System.Runtime.InteropServices;
 
 namespace Spectre.Console.Internal
 {
-    internal static class AnsiConsoleBuilder
+    internal static class BackendBuilder
     {
         public static IAnsiConsole Build(AnsiConsoleSettings settings)
         {
@@ -60,11 +60,11 @@ namespace Spectre.Console.Internal
             // Create the renderer
             if (supportsAnsi)
             {
-                return new AnsiConsoleRenderer(buffer, capabilities, settings.LinkIdentityGenerator);
+                return new AnsiBackend(buffer, capabilities, settings.LinkIdentityGenerator);
             }
             else
             {
-                return new FallbackConsoleRenderer(buffer, capabilities);
+                return new FallbackBackend(buffer, capabilities);
             }
         }
     }

src/Spectre.Console/Internal/Backends/Fallback/FallbackBackend.cs

@@ -0,0 +1,89 @@
+using System;
+using System.IO;
+using System.Text;
+using Spectre.Console.Rendering;
+
+namespace Spectre.Console.Internal
+{
+    internal sealed class FallbackBackend : IAnsiConsole
+    {
+        private readonly ColorSystem _system;
+        private readonly FallbackCursor _cursor;
+        private Style? _lastStyle;
+
+        public Capabilities Capabilities { get; }
+        public Encoding Encoding { get; }
+        public IAnsiConsoleCursor Cursor => _cursor;
+
+        public int Width
+        {
+            get { return ConsoleHelper.GetSafeBufferWidth(Constants.DefaultBufferWidth); }
+        }
+
+        public int Height
+        {
+            get { return ConsoleHelper.GetSafeBufferHeight(Constants.DefaultBufferHeight); }
+        }
+
+        public FallbackBackend(TextWriter @out, Capabilities capabilities)
+        {
+            if (capabilities == null)
+            {
+                throw new ArgumentNullException(nameof(capabilities));
+            }
+
+            _system = capabilities.ColorSystem;
+            _cursor = new FallbackCursor();
+
+            if (@out != System.Console.Out)
+            {
+                System.Console.SetOut(@out ?? throw new ArgumentNullException(nameof(@out)));
+            }
+
+            Encoding = System.Console.OutputEncoding;
+            Capabilities = capabilities;
+        }
+
+        public void Clear(bool home)
+        {
+            var (x, y) = (System.Console.CursorLeft, System.Console.CursorTop);
+
+            System.Console.Clear();
+
+            if (!home)
+            {
+                // Set the cursor position
+                System.Console.SetCursorPosition(x, y);
+            }
+        }
+
+        public void Write(Segment segment)
+        {
+            if (_lastStyle?.Equals(segment.Style) != true)
+            {
+                SetStyle(segment.Style);
+            }
+
+            System.Console.Write(segment.Text.NormalizeLineEndings(native: true));
+        }
+
+        private void SetStyle(Style style)
+        {
+            _lastStyle = style;
+
+            System.Console.ResetColor();
+
+            var background = Color.ToConsoleColor(style.Background);
+            if (_system != ColorSystem.NoColors && (int)background != -1)
+            {
+                System.Console.BackgroundColor = background;
+            }
+
+            var foreground = Color.ToConsoleColor(style.Foreground);
+            if (_system != ColorSystem.NoColors && (int)foreground != -1)
+            {
+                System.Console.ForegroundColor = foreground;
+            }
+        }
+    }
+}

src/Spectre.Console/Internal/Backends/Fallback/FallbackCursor.cs

@@ -0,0 +1,40 @@
+namespace Spectre.Console.Internal
+{
+    internal sealed class FallbackCursor : IAnsiConsoleCursor
+    {
+        public void Show(bool show)
+        {
+            System.Console.CursorVisible = show;
+        }
+
+        public void Move(CursorDirection direction, int steps)
+        {
+            if (steps == 0)
+            {
+                return;
+            }
+
+            switch (direction)
+            {
+                case CursorDirection.Up:
+                    System.Console.CursorTop -= steps;
+                    break;
+                case CursorDirection.Down:
+                    System.Console.CursorTop += steps;
+                    break;
+                case CursorDirection.Left:
+                    System.Console.CursorLeft -= steps;
+                    break;
+                case CursorDirection.Right:
+                    System.Console.CursorLeft += steps;
+                    break;
+            }
+        }
+
+        public void SetPosition(int x, int y)
+        {
+            System.Console.CursorLeft = x;
+            System.Console.CursorTop = y;
+        }
+    }
+}

src/Spectre.Console/Internal/Collections/ListWithCallback.cs

@@ -2,7 +2,7 @@ using System;
 using System.Collections;
 using System.Collections.Generic;
 
-namespace Spectre.Console.Internal.Collections
+namespace Spectre.Console.Internal
 {
     internal sealed class ListWithCallback<T> : IList<T>, IReadOnlyList<T>
     {

src/Spectre.Console/Internal/ExceptionFormatter.cs

@@ -1,10 +1,9 @@
 using System;
 using System.Linq;
 using System.Text;
-using Spectre.Console.Internal;
 using Spectre.Console.Rendering;
 
-namespace Spectre.Console
+namespace Spectre.Console.Internal
 {
     internal static class ExceptionFormatter
     {

src/Spectre.Console/Internal/FallbackConsoleRenderer.cs

@@ -1,97 +0,0 @@
-using System;
-using System.IO;
-using System.Text;
-using Spectre.Console.Rendering;
-
-namespace Spectre.Console.Internal
-{
-    internal sealed class FallbackConsoleRenderer : IAnsiConsole
-    {
-        private readonly TextWriter _out;
-        private readonly ColorSystem _system;
-        private Style? _lastStyle;
-
-        public Capabilities Capabilities { get; }
-        public Encoding Encoding { get; }
-
-        public int Width
-        {
-            get
-            {
-                if (_out.IsStandardOut())
-                {
-                    return ConsoleHelper.GetSafeBufferWidth(Constants.DefaultBufferWidth);
-                }
-
-                return Constants.DefaultBufferWidth;
-            }
-        }
-
-        public int Height
-        {
-            get
-            {
-                if (_out.IsStandardOut())
-                {
-                    return ConsoleHelper.GetSafeBufferHeight(Constants.DefaultBufferHeight);
-                }
-
-                return Constants.DefaultBufferHeight;
-            }
-        }
-
-        public FallbackConsoleRenderer(TextWriter @out, Capabilities capabilities)
-        {
-            if (capabilities == null)
-            {
-                throw new ArgumentNullException(nameof(capabilities));
-            }
-
-            _out = @out ?? throw new ArgumentNullException(nameof(@out));
-            _system = capabilities.ColorSystem;
-
-            if (_out.IsStandardOut())
-            {
-                Encoding = System.Console.OutputEncoding;
-            }
-            else
-            {
-                Encoding = Encoding.UTF8;
-            }
-
-            Capabilities = capabilities;
-        }
-
-        public void Write(Segment segment)
-        {
-            if (_lastStyle?.Equals(segment.Style) != true)
-            {
-                SetStyle(segment.Style);
-            }
-
-            _out.Write(segment.Text.NormalizeLineEndings(native: true));
-        }
-
-        private void SetStyle(Style style)
-        {
-            _lastStyle = style;
-
-            if (_out.IsStandardOut())
-            {
-                System.Console.ResetColor();
-
-                var background = Color.ToConsoleColor(style.Background);
-                if (_system != ColorSystem.NoColors && _out.IsStandardOut() && (int)background != -1)
-                {
-                    System.Console.BackgroundColor = background;
-                }
-
-                var foreground = Color.ToConsoleColor(style.Foreground);
-                if (_system != ColorSystem.NoColors && _out.IsStandardOut() && (int)foreground != -1)
-                {
-                    System.Console.ForegroundColor = foreground;
-                }
-            }
-        }
-    }
-}

src/Spectre.Console/Recorder.cs

@@ -19,6 +19,9 @@ namespace Spectre.Console
         /// <inheritdoc/>
         public Encoding Encoding => _console.Encoding;
 
+        /// <inheritdoc/>
+        public IAnsiConsoleCursor Cursor => _console.Cursor;
+
         /// <inheritdoc/>
         public int Width => _console.Width;
 
@@ -41,10 +44,26 @@ namespace Spectre.Console
             // Only used for scoping.
         }
 
+        /// <inheritdoc/>
+        public void Clear(bool home)
+        {
+            _console.Clear(home);
+        }
+
         /// <inheritdoc/>
         public void Write(Segment segment)
         {
-            _recorded.Add(segment);
+            if (segment is null)
+            {
+                throw new ArgumentNullException(nameof(segment));
+            }
+
+            // Don't record control codes.
+            if (!segment.IsControlCode)
+            {
+                _recorded.Add(segment);
+            }
+
             _console.Write(segment);
         }
 

src/Spectre.Console/Rendering/Segment.cs

@@ -31,6 +31,12 @@ namespace Spectre.Console.Rendering
         /// </summary>
         public bool IsWhiteSpace { get; }
 
+        /// <summary>
+        /// Gets a value indicating whether or not his is a
+        /// control code such as cursor movement.
+        /// </summary>
+        public bool IsControlCode { get; }
+
         /// <summary>
         /// Gets the segment style.
         /// </summary>
@@ -39,12 +45,12 @@ namespace Spectre.Console.Rendering
         /// <summary>
         /// Gets a segment representing a line break.
         /// </summary>
-        public static Segment LineBreak { get; } = new Segment(Environment.NewLine, Style.Plain, true);
+        public static Segment LineBreak { get; } = new Segment(Environment.NewLine, Style.Plain, true, false);
 
         /// <summary>
         /// Gets an empty segment.
         /// </summary>
-        public static Segment Empty { get; } = new Segment(string.Empty, Style.Plain, false);
+        public static Segment Empty { get; } = new Segment(string.Empty, Style.Plain, false, false);
 
         /// <summary>
         /// Initializes a new instance of the <see cref="Segment"/> class.
@@ -61,16 +67,27 @@ namespace Spectre.Console.Rendering
         /// <param name="text">The segment text.</param>
         /// <param name="style">The segment style.</param>
         public Segment(string text, Style style)
-            : this(text, style, false)
+            : this(text, style, false, false)
         {
         }
 
-        private Segment(string text, Style style, bool lineBreak)
+        private Segment(string text, Style style, bool lineBreak, bool control)
         {
             Text = text?.NormalizeLineEndings() ?? throw new ArgumentNullException(nameof(text));
             Style = style ?? throw new ArgumentNullException(nameof(style));
             IsLineBreak = lineBreak;
             IsWhiteSpace = string.IsNullOrWhiteSpace(text);
+            IsControlCode = control;
+        }
+
+        /// <summary>
+        /// Creates a control segment.
+        /// </summary>
+        /// <param name="control">The control code.</param>
+        /// <returns>A segment representing a control code.</returns>
+        public static Segment Control(string control)
+        {
+            return new Segment(control, Style.Plain, false, true);
         }
 
         /// <summary>

src/Spectre.Console/Widgets/Calendar.cs

@@ -3,7 +3,6 @@ using System.Collections.Generic;
 using System.Globalization;
 using System.Linq;
 using Spectre.Console.Internal;
-using Spectre.Console.Internal.Collections;
 using Spectre.Console.Rendering;
 
 namespace Spectre.Console

src/Spectre.Console/Widgets/Grid.cs

@@ -1,7 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using Spectre.Console.Internal.Collections;
+using Spectre.Console.Internal;
 using Spectre.Console.Rendering;
 
 namespace Spectre.Console

src/Spectre.Console/Widgets/Table.cs

@@ -3,7 +3,6 @@ using System.Collections.Generic;
 using System.Linq;
 using Spectre.Console.Internal;
 using Spectre.Console.Rendering;
-using Spectre.Console.Widgets;
 
 namespace Spectre.Console
 {

src/Spectre.Console/Widgets/TableRow.cs

@@ -3,7 +3,7 @@ using System.Collections;
 using System.Collections.Generic;
 using Spectre.Console.Rendering;
 
-namespace Spectre.Console.Widgets
+namespace Spectre.Console
 {
     /// <summary>
     /// Represents a table row.