About

RapidConsole is a tiny reference assembly with big functionality. The library provides a complete console application framework which includes layered windows and command-line processing.

Windows

consoleapp.jpg
A Window is defined by a rectangular area within the console window and provides functionality such as:
  • Displaying a frame (or border) made of ASCII bar characters (single or double bar)
  • Specifying the background, foreground and frame color
  • Drawing text content in lines fit to the window's client bounds (inside the frame bounds)
  • Scrolling text content vertically, with a visible scroll bar, using arrow or page up/down keys
  • Toggle open windows with the Tab key or close windows with Escape

Derived windows include:
  • A ListWindow which treats the window text as an array of lines (split at the new-line character)
    • Displays a scrollable list of items, split from lines of the window text
    • Tracks and highlights the selected item in the list
  • A single-line, scrollable MenuWindow with item selection
    • Items are split from the words in the window text, using the pipe character as a word seperator
  • A CommandLineWindow which serves as a single-line, scrollable input box with a command prompt
    • Tracks and displays user keyboard input when in focus
    • Provides notification when a command line string is entered
  • An OutputWindow which is configured to disallow focus and to display its text inverted (that is, from bottom to top instead of top to bottom).
    • Use as the parent window for a CommandLineWindow instance to receive automatic output from the command line.
  • A HelpWindow containing a list of command methods and their associated help text.

Also provides the ability to draw directly to the screen buffer, overwriting any open windows with custom content.

Processing

The RapidConsole framework provides a CommandProcessor object which is capable of parsing command line text input and executing associated code methods. Any method which takes a single parameter of type CommandLine and returns Void (is a Sub not a Function) can be designated as a command-method by applying the <CommandMethod> attribute. The attribute also allows defining alternate names for the command as well as optional help content.

Any object derived from CommandProcessor will automatically load any command methods defined within itself at the time of construction. Instances of CommandProcessor can also load command methods on demand from a specified object instance.

Commands

Command keywords are recognized with partial text. If the characters entered for the command match the beginning of exactly one known command keyword then that command is executed. If the characters entered match the beginning of more than one known command keyword then the command returns an AMBIGUOUS result status code.

Command lines consist of the command keyword followed by a delimited list of parameter values. The first word of the line is interpreted as the command keyword and all other words are parsed into a dictionary of parameter names and values.

Parameters are delimited by spaces, and a parameter value can be quoted to contain a space. If the parameter value contains an equals character (=) then the parameter will be parsed as a key-value pair. Otherwise the parameter will be parsed as a value with a key assigned as "%n" where "n" is the value's index in the parameter list.

Rapid CLI

The framework also includes a CommandPromptProgram class which can serve as the base class for any console application. This class includes the command line and output windows as well as a command processor. Simply inherit from this class and implement your command methods. Your actual console program is then simply:

Imports RapidConsole

Module Module1
    Private program As New Program

    Sub Main()
        program.Start()
    End Sub
End Module

Example Program

Public Class Program
    Inherits CommandPromptProgram

    Private WithEvents infoWindow As Window 'use a window as a message box
    Private WithEvents menuWindow As MenuWindow  'a single-line, scrollable list of menu items
    Private WithEvents listWindow As ListWindow  'a scrollable list of items
    Private dotX, dotY As Integer 'position of a user-drawn "dot" character on the screen

    Public Overrides Sub Start()
        UseF1Help = True
        infoWindow = New Window(Console.WindowWidth / 2 - 13, Console.WindowHeight / 2 - 4, 26, 8)
        infoWindow.BackColor = ConsoleColor.Red
        infoWindow.ForeColor = ConsoleColor.White
        infoWindow.FrameColor = ConsoleColor.Yellow

        Dim panel As New Window(4, 2, 30, 14) 'use a window as a panel
        panel.BackColor = ConsoleColor.DarkBlue
        panel.MergeFrameWithParent = False
        panel.CanFocus = False
        Output.Children.Add(panel)
        panel.Show()

        listWindow = New ListWindow(1, 1, 8, 8)
        panel.Children.Add(listWindow)
        listWindow.MergeFrameWithParent = False
        listWindow.BackColor = ConsoleColor.DarkGreen
        listWindow.FrameColor = ConsoleColor.Green
        listWindow.ForeColor = ConsoleColor.Yellow

        menuWindow = New MenuWindow(1, 1, 78)
        menuWindow.MergeFrameWithParent = False
        menuWindow.BackColor = ConsoleColor.DarkRed
        menuWindow.FrameColor = ConsoleColor.Red
        menuWindow.ForeColor = ConsoleColor.Yellow

        For i As Integer = 1 To 20 'add items to the list windows
            menuWindow.Add($" Item {i} ")
            listWindow.Add($"Menu Item {i}")
        Next

        MyBase.Start() 'start the program execution; this is a blocking method so call it last
    End Sub

    'implement the commands recognized by your program

    <CommandMethod()>
    Public Sub Test(line As CommandLine)
        Output.AppendText(line.GetParameterString, True)
    End Sub

    <CommandMethod()>
    Public Sub Testing(line As CommandLine)
        Output.AppendText(line.GetParameterString, True)
        line.CustomStatus = "OK - LONG FORM"
    End Sub

    <CommandMethod("", "Show {what} (args)", "Show dot (x y)\nShow info (infoText)")>
    Public Sub Show(line As CommandLine)
        If line.ParameterCount > 0 Then
            Select Case line.ParameterValue(0)
                Case "dot"
                    Dim x As Integer = 0
                    If line.ParameterCount > 1 Then
                        x = CInt(line.ParameterValue(1))
                    End If
                    Dim y As Integer = 0
                    If line.ParameterCount > 2 Then
                        y = CInt(line.ParameterValue(2))
                    End If
                    Window.UserBuffer.Clear(dotX, dotY)
                    Window.UserBuffer.Item(x, y) = "∙"c
                    Window.UserBuffer.ForegroundColor(x, y) = ConsoleColor.Red
                    dotX = x
                    dotY = y
                Case "info"
                    If line.ParameterCount > 1 Then
                        infoWindow.Content.Text = line.ParameterValue(1)
                        infoWindow.Show()
                    End If
                Case "menu"
                    menuWindow.Show()
                Case "list"
                    listWindow.Show()
                Case Else
                    line.CustomStatus = "UNKNOWN ARGUMENT"
            End Select

        Else
            line.CustomStatus = "INSUFFICIENT NUMBER OF ARGUMENTS"
        End If
    End Sub

    'handle the events on your program's windows required to implement your program's functionality

    Private Sub infoWindow_KeyProcessing(sender As Object, e As Window.KeyProcessingEventArgs) Handles infoWindow.KeyProcessing
        If e.Key.Key = ConsoleKey.Enter Then
            CType(sender, Window).Hide()
        End If
    End Sub

    Private Sub menuWindow_ItemSelected(sender As Object, e As EventArgs) Handles menuWindow.ItemSelected
        Output.AppendText($"Selected: {menuWindow.Item(menuWindow.SelectedIndex)}", True)
    End Sub
End Class

Last edited Oct 1, 2015 at 8:15 PM by ReedKimble, version 3