eggy

README

eggy 🥚

Exempli Gratia Go Yielder

A lightweight Go framework for creating interactive example runners for your packages. Eggy makes it easy to showcase how your code works through selectable, executable examples.

What is Eggy?

Eggy is designed to help package authors create interactive demos and examples for their libraries. Instead of writing separate example files or expecting users to read through documentation, eggy provides an interactive menu-driven interface where users can select and run examples on the fly.

Installation

go get github.com/engmtcdrm/go-eggy

Quick Start

package main

import (
    "fmt"

    "github.com/engmtcdrm/go-eggy"
)

func main() {
    examples := []eggy.Example{
        {Name: "Hello World Example", Fn: helloWorldExample},
        {Name: "Hi Mom Example", Fn: hiMomExample},
    }

    eggy.NewExamplePrompt(examples).
        Title("My Package Examples").
        Show()
}

func helloWorldExample() {
    fmt.Println("Hello World!")
}

func hiMomExample() {
    fmt.Println("Hi Mom!")
}

Features

Basic Example Prompt

Create a simple example selector:

examples := []eggy.Example{
    {Name: "Example One", Fn: exampleOne},
    {Name: "Example Two", Fn: exampleTwo},
}

eggy.NewExamplePrompt(examples).Show()

Adding a Title

Display a title above the example menu:

eggy.NewExamplePrompt(examples).
    Title("My Awesome Examples").
    Show()

Repeat Mode

Allow users to run multiple examples in sequence without restarting:

eggy.NewExamplePrompt(examples).
    Repeat(true).
    Show()

When Repeat(true) is set, after running an example, the user will be prompted to run another example until they choose to exit.

Nested Examples

You can create nested example menus for organizing complex demonstrations:

var topLevelExamples = []eggy.Example{
    {Name: "Basic Examples", Fn: showBasicExamples},
    {Name: "Advanced Examples", Fn: showAdvancedExamples},
}

var basicExamples = []eggy.Example{
    {Name: "Hello World", Fn: helloWorld},
    {Name: "Simple Math", Fn: simpleMath},
}

func showBasicExamples() {
    eggy.NewExamplePrompt(basicExamples).
        Repeat(true).
        Show()
}

API Reference

Types

Example

Represents a single example with a name and function to execute.

type Example struct {
    Name string // Display name in the selection menu
    Fn   func() // Function to execute when selected
}

ExamplePrompt

Manages a collection of examples and handles user interaction.

Functions

NewExamplePrompt(examples []Example) *ExamplePrompt

Creates a new ExamplePrompt with the provided examples.

(*ExamplePrompt) Title(title string) *ExamplePrompt

Sets a title to display above the example menu. Returns the ExamplePrompt for method chaining.

(*ExamplePrompt) Repeat(repeat bool) *ExamplePrompt

Sets whether to prompt the user to run additional examples after each execution. Returns the ExamplePrompt for method chaining.

(*ExamplePrompt) Show()

Displays the example prompt and handles user interaction.

Customization

Eggy provides default styling functions that you can override:

// Style the selected answer
eggy.DefaultAnswerFunc = func(answer string) string {
    return myCustomStyle(answer)
}

// Style the cursor
eggy.DefaultCursorFunc = func(cursor string) string {
    return myCustomStyle(cursor)
}

// Style the selected option
eggy.DefaultSelectFunc = func(s string) string {
    return myCustomStyle(s)
}

// Style icons
eggy.DefaultIconFunc = func(icon string) string {
    return myCustomStyle(icon)
}

Example Project Structure

For a complete working example of eggy in action, see the example directory. This is a great way to see how eggy works and get ideas for how to structure your own example runners.

example/
├── main.go              # Entry point
├── examples/
│   └── all_examples.go  # Example definitions
└── go.mod

To run the examples:

cd example
go run .

License

See LICENSE for details.

Documentation

Index

• Variables
• type Example
• type ExamplePrompt
  • func NewExamplePrompt(examples []Example) *ExamplePrompt
  • func (ep *ExamplePrompt) Repeat(repeat bool) *ExamplePrompt
  • func (ep *ExamplePrompt) Show()
  • func (ep *ExamplePrompt) Title(title string) *ExamplePrompt

Variables

var DefaultAnswerFunc = func(answer string) string {
	return pp.Yellow(answer)
}

DefaultAnswerFunc styles the answer text in yellow.

var DefaultCursorFunc = func(cursor string) string {
	return pp.Yellow(cursor)
}

DefaultCursorFunc styles the cursor text in yellow.

var DefaultIconFunc = func(icon string) string {
	return pp.Cyan(icon)
}

DefaultIconFunc styles the icon text in cyan.

var DefaultSelectFunc = func(s string) string {
	return pp.Green(s)
}

DefaultSelectFunc styles the selected option text in green.

Types

type Example

type Example struct {
	Name string // Name of the example to be displayed in the selection prompt.
	Fn   func() // Function to execute when the example is selected.
}

Example represents a single example with a name and an associated function to execute.

type ExamplePrompt

type ExamplePrompt struct {
	// contains filtered or unexported fields
}

ExamplePrompt manages a collection of examples and handles user interaction.

func NewExamplePrompt

func NewExamplePrompt(examples []Example) *ExamplePrompt

NewExamplePrompt creates a new ExamplePrompt with the provided examples.

func (*ExamplePrompt) Repeat

func (ep *ExamplePrompt) Repeat(repeat bool) *ExamplePrompt

Repeat sets whether to repeat the prompt after an example is executed.

func (*ExamplePrompt) Show

func (ep *ExamplePrompt) Show()

Show displays the example prompt and handles user interaction.

func (*ExamplePrompt) Title

func (ep *ExamplePrompt) Title(title string) *ExamplePrompt

Title sets the title of the example prompt.