EluciusFTW.SpectreCoff 0.49.4

SpectreCoff

Spectre Console for F# - A thin, opinionated wrapper around Spectre.Console featuring Dumpify.

Available at Nuget: EluciusFTW.SpectreCoff.

Table of Contents

• Goals and Philosophy
• SpectreCoff Package
  • Output Payloads
  • Markup
  • Convenience Styles
  • Versioning
• SpectreCoff Cli
  • Run Examples
  • Discover Themes
• Related Work
• License
• Feedback and Contributing

Goals and Philosophy

Before we get into the details, we'd like to outline our goals and our guiding principles for designing the SpectreCoff api surface.

1. Make Spectre.Console available for console applications in F# in an idiomatic way.

   We expose separate functionality in different modules, as functions, with typed arguments instead of generics resp. object-typing. Since many of Spectre's functions can handle multiple different kinds of content that often means wrapping your content in discriminated union type. We believe that the expression of intent as well as the resulting robustness and clarity far outweigh the 'overhead' of wrapping.

2. Provide a simple and consistent api surface.

   In SpectreCoff, we follow the structure Spectre.Console provides very closely.

   • Features of Spectre are translated into modules of the same name.
   • Whenever possible, each module exposes a function producing 'the module thing' that is of same name as the module. This will be in form of an OutputPayload.
   • The special module Output (which also defines the type OutputPayload), provides the function toConsole with which everything can be printed.

   In the example of the figlet widget of Spectre, which translates into the figlet module, it looks like this:

   "Hello World"    // figlet content
   |> figlet        // main function of the module producing the figlet as an OutputPayload 
   |> toConsole     // toConsole function of the figlet module
   

   Of course, for more complex objects, there will be more parameters needed. To achieve this simplicity, the main function uses some defaults (in this example the alignment of the figlet). These defaults can be overwritten 'globally' (as they are just static variables in the module), or passed to other functions taking in more arguments, e.g.,

   "Hello again"
   |> alignedFiglet Left 
   |> toConsole
   
   // if all your figlets should be left-aligned, you can also set that as the default and use the main figlet function
   defaultAlignment <- Left
   

3. Add a bit of sprinke on top.

   Spectre is great in providing ways to customize output. We wanted to add a bit on top to make it easier to utilize custom styles consistently throughout applications. Among other things, we decided to include three different semantic levels of output, namely: calm, pumped and edgy, which we also call convenience styles. These are supported throughout the modules, and each style can be customized individually.

4. Bake the cake and eat it, too.

   We want to feel the joy, and pain, of using our api in the fullest. That's why we have included a cli project in this repository, where we expose the full documentation as well as provide examples for each functionality, using the api itself.

   dotnet run figlet doc            // prints the documentation of the figlet module
   dotnet run figlet example        // shows examples of the module in action
   

5. Bonus: Do the same for Dumpify

   Along the way we also added a separate module wrapping the functionality of Dumpify following the same principles. While the main focus remains with Spectre.Console (hence the name of the package), we do think Dumpify's capabilities are useful and related (it uses Spectre.Console internally, after all) enough to just slap it on top of our package.

SpectreCoff Package

SpectreCoff is organized in modules which mirror the features of Spectre.Console. It also contains an additional module exposing the capabilities of Dumpify. The source code for the nuget package can be found in the subfolder /src/spectrecoff/.

Modules

For a list of all modules available, see here. But before checking them out, we advise to read the remainder of this section.

Output Payloads

An important abstraction in SpectreCoff is the OutputPayload type, which is a discriminated union type of all the things that can be sent to the console. As a consequence, any act of producing output in SpectreCoff looks like this:

payload |> toConsole

All modules have functions (often of the same name as the module) to create the respective OutputPayload, like in the example from the introduction above:

"Hello World"    // figlet content
|> figlet        // the function of same name as the module, which creates the OutputPayload 
|> toConsole     // this sends the payload to the console

This function uses some reasonable defaults for layout and styling. These are stored in mutable variables in the module and can be globally adjusted by changing their values. For one-time changes, most modules have another create function - prefixed with custom - which takes in more parameters adjusting the options, layout and styling of the output.

Some of the more complex Spectre.Console objects are inherently mutable, e.g., a table, where rows might be added or removed after creation. In those cases, the main function returns the Spectre.Console type instead, and provides a toOutputPayload function which can be used to map them to a payload just before sending them to the console:

// This creates a Spectre.Console Table
let exampleTable = table columns rows

// This maps and prints the initial table
exampleTable
|> toOutputPayload
|> toConsole

// This adds another row to the table
addRowToTable exampleTable row

// This prints the table again, including the new row
exampleTable
|> toOutputPayload
|> toConsole

Payloads can easily be composed using the Many payload and then printed all at once. Here is a more comprehensive example (without going into details what each payload means at this point):

Many [
    MarkupC (Color.Green, "Hello friends,")           // Use any available color
    BlankLine    
    Pumped "Welcome to my party tomorrow night!"      // Use the Pumped convenience style
    BL                                                // short for BlankLine
    C "Please bring ... "                             // short for Calm
    BI [                                              // short for BulletItems
        C "some snacks,"        
        P "some games,"                               // short for Pumped
        E "and some creepy stories!"                  // short for Edgy
    ]
    C "See you "; P "later ... "; NL                  // Mixing list separators to indicate the line is also possible
    Emoji "alien_monster"
] |> toConsole

You can find a complete list of all payload types here.

Markup

Spectre.Console provides many possibilities to mark up text, which technically are not grouped into features resp. modules. All of these are also encoded in cases of the OutputPayload type, with lot's of helper functions. See here for all details on formatting and styling text output.

Convenience Styles

Additionally, this package introduces three named convenience styles, with which we can easily provide a consistent and semantically meaningful styling across the modules: Calm, Pumped and Edgy.

// Says hello world, emphatically
Pumped "Hello world" |> toConsole

The convenience styles can globally be altered by mutating the corresponding variables, e.g.,

pumpedLook <- { Color = Color.Yellow; Decorations = [ Decoration.Italic ] }

In fact, the package also provides several themes out of the box, which can be selected using the selectTheme function and provide a theme from the SpectreCoffThemes discriminated union type:

// A composite payload of all convenience styles
let sample = 
    Many [                          
        Calm "The calm fox"
        Pumped "jumps pumped"
        Edgy "over the edgy fence"
    ]
// sets the theme and prints the sample
let printExampleUsing theme = 
    selectTheme theme               
    sample |> toConsole

printExampleUsing Volcano
printExampleUsing NeonLights

You can also build your own custom theme and use it with the applyTheme function.

Encoding issues

Note: Several features of Spectre.Console depend on UTF8 Encoding. If you experience unexpected output when handling UTF8 characters check the Spectre.Console best practices.

Versioning

We are using NerdBank.GitVersioning and follow the version scheme: <major>.<minor>.<git-depth> for out releases.

Since this package is a wrapper around Spectre.Console, we will synchronize our major and minor versions with the ones of the Spectre dependency we are wrapping.

<b>Note</b>: In particular, the third number in the version does not have the same meaning as the patches in SemVer. Increments in that number may contain breaking changes, in contrast to patch versions in SemVer.

SpectreCoff Cli

This repository also contains a CLI in the folder in /src/spectrecoff-cli/, with examples of each module, as well as some utilities.

Run Examples

You can see each module in action by using the cli included in this repository in /src/spectrecoff-cli/. Simply run

dotnet run <module-name> example

in the cli subfolder and substitute the module name by and spectrecoff module you can find in the module list. The source files of these commands are also good sources for more examples on how to use the module.

Discover Themes

As mentioned above, SpectreCoff has some built in themes that can be used. The CLI supports discovery of the themes:

dotnet run theme list                              // lists all available themes
dotnet run theme example --theme <themeName>       // shows a sample of the convenience styles of that theme

Related Work

In SpectreCoff we take the approach of providing types and functions wrapping the Spectre.Console api. If you prefer dsls via computation expressions, check out this awesome project (hey, even if you don't, check it out anyway!):

• fs-spectre - 👻💻 Spectre.Console with F# style.

Also, if you want to create a cli using Spectre.Console.Cli (recently the cli part was extracted into a separate package), you can use my starter template:

• fsharp-spectre-console-template - A minimal starter template for using Spectre.Console.Cli in fsharp

License

Copyright © Guy Buss, Daniel Muckelbauer

SpectreCoff is provided as-is under the MIT license. See the LICENSE.md file included in the repository.

Feedback and Contributing

All feedback welcome! All contributions are welcome!