devcard

package module
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 21, 2024 License: MIT Imports: 16 Imported by: 1

README

Devcards

Devcards provides interactive visual environment for Go, in a way that's similar to REPL and computational notebooks such as Jupyter.

How it works

A devcard is a playground for visualizations and quick experiments. You write its code with our own editor in you own codebase, and the devcards web app turns it into a web page that's shown in your browser. The app watches your project's source files and re-renders the page on each save.

See this short video for a quick demonstration.

Getting started

Perhaps the easiest place to start is to the devcard examples repo.

If you went through the examples already (or have no patience for toy code) follow the following instructions.

Install the devcards web app:

go install github.com/igorhub/devcard/cmd/devcards@latest

Add devcard dependency to your Go modules (I recommend making a separate branch for it):

go get github.com/igorhub/devcard

Start devcards from your project's directory (alternatively, add your project to the config file):

cd /path/to/your/project
devcards

Write your first devcard:

package yourpackage

import "github.com/igorhub/devcard"

func DevcardFoobar(dc *devcard.Devcard) {
    dc.SetTitle("Untitled")

    dc.Md("This is a new devcard...")
}

Documentation

For introduction into devcards, see devcard examples pages.

For API reference, see https://godocs.io/github.com/igorhub/devcard.

Troubleshooting

Devcards is a young project. I've done reasonable job ironing out the bugs, but I expect some to still lurk beneath the surface. In most cases simply refreshing the page will fix everything. Still, please let me know about the errors you encounter. This will make the project better. I appreciate your help.

Acknowledgements

  • Devcards owes its name and primary idea to Bruce Hauman's devcards, although it's more bare-bones and limited in scope.

  • Devcards' builtin CSS style is based upon the excellent new.css.

  • Ace of Spades icon is designed by DesignContest / CC BY.

Documentation

Overview

Package devcard describes the Devcard and its primary building block, Cell.

For proper introduction, see README.

Index

Constants

View Source 
const (
	MessageTypeCell  = "cell"
	MessageTypeInfo  = "info"
	MessageTypeError = "internal error"
)

Message types are used for communication with devcards server via TCP connection.

Variables

View Source 
var DefaultJumpDelay = 50

Default JumpCell delay, in milliseconds.

Functions

func Debug 

func Debug(producer DevcardProducer)

Debug facilitates debugging. To debug a devcard, either put a call to Debug in the main(), or wrap it in a test function, and then use "Debug Test" feature of your IDE.

Example: 

func TestDevcardFoobar(t *testing.T) {
	devcard.Debug(DevcardFoobar)
}

func Interrupt added in v0.11.0 

func Interrupt()

func WithHighlighting 

func WithHighlighting(lang string) monospaceCellOption

WithHighlighting is an option for Devcard.Mono. It enables syntax highlighting for the code in a MonospaceCell.

Types

type AnnotatedImage 

type AnnotatedImage struct {
	Annotation string `json:"comment"`
	Path       string `json:"value"`
}

AnnotatedImage as an image with its description.

type AnnotatedValue 

type AnnotatedValue struct {
	Annotation string `json:"annotation"`
	Value      string `json:"value"`
}

AnnotatedValueCell contains pretty-printed Go value and its description/annotation.

type AnnotatedValueCell 

type AnnotatedValueCell struct {
	AnnotatedValues []AnnotatedValue `json:"marked_values"`
}

AnnotatedValueCell is a cell with pretty-printed Go values that have comments attached to them.

func NewAnnotatedValueCell 

func NewAnnotatedValueCell(annotationsAndVals ...any) *AnnotatedValueCell

NewAnnotatedValueCell creates AnnotatedValueCell.

func (*AnnotatedValueCell) Append 

func (c *AnnotatedValueCell) Append(annotationsAndVals ...any)

Append appends one or more AnnotatedValues to the cell. annotationsAndVals are converted to annotated values by the rules described in Devcard.Ann.

func (*AnnotatedValueCell) Erase 

func (c *AnnotatedValueCell) Erase()

Erase clears the content of the cell.

func (*AnnotatedValueCell) Type 

func (c *AnnotatedValueCell) Type() string

Returns "AnnotatedValueCell". Used for marshaling.

type Cell 

type Cell interface {
	Type() string
	Append(...any)
	Erase()
}

Cell is a basic building block of a devcard.

func UnmarshalCell 

func UnmarshalCell(cellType string, data []byte) (Cell, error)

UnmarshalCell unmarshalls JSON data into a Cell instance.

type CustomCell 

type CustomCell struct{}

CustomCell provides a base for user-defined cells.

It implements Cell interface by providing Type, Append, and Erase methods that don't do anything.

func (*CustomCell) Append 

func (c *CustomCell) Append(vals ...any)

Append panics by default. Custom Append might be implemented by user.

func (*CustomCell) Erase 

func (c *CustomCell) Erase()

Erase panics by default. Custom Erase might be implemented by user.

func (*CustomCell) Type 

func (c *CustomCell) Type() string

Returns "CustomCell". Not used anywhere; implemented to satisfy Cell interface.

type Devcard 

type Devcard struct {
	Title   string `json:"title"`
	TempDir string `json:"temp_dir"`
	Cells   []Cell `json:"cells"`
	// contains filtered or unexported fields
}

Devcard struct represents the devcard shown to the user.

It's responsible for maintaining its list of renderable cells and for interaction with the server.

It's safe for concurrent use.

func Current 

func Current() *Devcard

Current returns a global pointer to the devcard that's currently being produced. It's exposed to allow the user to access the current devcard from any arbitrary place.

func (*Devcard) Ann added in v0.6.0 

func (d *Devcard) Ann(annotationsAndVals ...any) *AnnotatedValueCell

Ann appends an AnnotatedValueCell to the bottom of the devcard. annotationsAndVals are split into pairs: the first value of each pair becomes an annotation, the second value becomes a pretty-printed value.

Example: 

c.Ann("Loaded config:", cfg, "Default config:", defaultConfig())

The appended AnnotatedValueCell is immediately sent to the client.

func (*Devcard) Append 

func (d *Devcard) Append(vals ...any)

Append appends values to the bottom cell of the devcard. The exact behavior is dictated by the concrete type of the bottom cell.

The bottom cell is immediately sent to the client.

func (*Devcard) Custom 

func (d *Devcard) Custom(cell customCell)

Custom appends a custom cell to the bottom of the devcard.

The appended HTMLCell is immediately sent to the client.

func (*Devcard) Erase 

func (d *Devcard) Erase(cell Cell)

Erase clears the content of the cell.

The cell is not removed from the devcard, and can be reused later on.

The resulting blank cell is immediately sent to the client.

func (*Devcard) EraseLast 

func (d *Devcard) EraseLast()

EraseLast clears the content of the bottom cell of the devcard.

The cell is not removed from the devcard, and can be reused later on.

The blank bottom cell is immediately sent to the client.

func (*Devcard) Error 

func (d *Devcard) Error(vals ...any) *ErrorCell

Error appends an ErrorCell to the bottom of the devcard.

The first of vals becomes the cell's title; the rest are converted into strings, concatenated, and become the cell's body.

The appended ErrorCell is immediately sent to the client.

func (*Devcard) Html 

func (d *Devcard) Html(vals ...any) *HTMLCell

Html appends an HTMLCell to the bottom of the devcard. vals are converted into strings and concatenated.

The appended HTMLCell is immediately sent to the client.

func (*Devcard) Image 

func (d *Devcard) Image(annotationsAndImages ...any) *ImageCell

Image appends an ImageCell to the bottom of the devcard. annotationsAndVals are split into pairs: the first value of each pair becomes an annotation, the second value becomes an image.

An image can be either an absolute path to the image file, or an instance of image.Image.

When called with a single argument, the argument is treated as image, not annotation. For example: 

c.Image("/home/ivk/Pictures/wallhaven-n6mrgl.jpg")

// With annotation
c.Image("Two cats sitting on a tree", "/home/ivk/Pictures/wallhaven-n6mrgl.jpg")

The appended ImageCell is immediately sent to the client.

func (*Devcard) Jump 

func (d *Devcard) Jump() *JumpCell

Not documented. Subject to change.

func (*Devcard) MarshalJSON 

func (d *Devcard) MarshalJSON() ([]byte, error)

MarshalJSON marshals the devcard into JSON data.

func (*Devcard) Md 

func (d *Devcard) Md(vals ...any) *MarkdownCell

Md appends a MarkdownCell to the bottom of the devcard. vals are converted into strings and concatenated.

The appended MarkdownCell is immediately sent to the client.

func (*Devcard) MdFmt 

func (d *Devcard) MdFmt(format string, a ...any) *MarkdownCell

MdFmt is a convenience wrapper for Devcard.Md.

It's implemented as `return d.Md(fmt.Sprintf(format, a...))`.

func (*Devcard) Mono 

func (d *Devcard) Mono(vals ...any) *MonospaceCell

Mono appends a MonospaceCell to the bottom of the devcard. vals are converted into strings and concatenated.

WithHighlighting option can be used at any position to enable syntax highlighting. For example: 

c.Mono(devcard.WithHighlighting("clojure"), "(def ^:private *registry (atom {}))")

The appended MonospaceCell is immediately sent to the client.

func (*Devcard) MonoFmt 

func (d *Devcard) MonoFmt(format string, a ...any) *MonospaceCell

MonoFmt is a convenience wrapper for Mono.

It's implemented as `return d.Mono(fmt.Sprintf(format, a...))`.

func (*Devcard) Replace 

func (d *Devcard) Replace(oldCell, newCell Cell)

Replace replaces oldCell with newCell.

The new cell is immediately sent to the client.

func (*Devcard) ReplaceLast 

func (d *Devcard) ReplaceLast(newCell Cell)

ReplaceLast replaces the bottom cell of the devcard with newCell.

The new cell is immediately sent to the client.

func (*Devcard) SetTitle 

func (d *Devcard) SetTitle(title string)

SetTitle sets the devcard's title and updates it on the client.

func (*Devcard) Source 

func (d *Devcard) Source(decls ...string) *SourceCell

Source appends a SourceCell to the bottom of the devcard.

The cell contains the source of the declarations decls. As of now, only function declarations are supported. Declarations must be prefixed with the name of their package. For example: 

c.Source("examples.DevcardTextCells")

The appended SourceCell is immediately sent to the client.

func (*Devcard) UnmarshalJSON 

func (d *Devcard) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals JSON data into the devcard.

func (*Devcard) Update 

func (d *Devcard) Update(cell Cell)

Update sends the cell to the client.

The cell must be contained by the devcard.

func (*Devcard) Val 

func (d *Devcard) Val(vals ...any) *ValueCell

Val appends a ValueCell to the bottom of the devcard. vals are pretty-printed and joined together.

The appended ValueCell is immediately sent to the client.

type DevcardInfo 

type DevcardInfo struct {
	// ImportPath is the import path of the devcard's package.
	ImportPath string

	// Package is the name of the package that the devcard belongs to.
	Package string

	// Path is the relative path (from the project dir) to the source file where
	// the devcard is located.
	Path string

	// Line is a line number in the source file where the devcard is located.
	Line int

	// Name is the name of the devcard-producing function.
	Name string

	// Title is the title of the devcard.
	Title string
}

DevcardInfo describes devcard's metadata.

func (DevcardInfo) Caption 

func (di DevcardInfo) Caption() string

Caption returns the devcard's title, or, in case it's empty, the name of devcard-producing function.

type DevcardProducer 

type DevcardProducer func(*Devcard)

DevcardProducer is a function that fills an empty devcard with content.

type ErrorCell 

type ErrorCell struct {
	Title string
	Body  string
}

ErrorCell is a cell for error reporting.

func NewErrorCell 

func NewErrorCell(vals ...any) *ErrorCell

NewErrorCell creates ErrorCell.

func (*ErrorCell) Append 

func (c *ErrorCell) Append(vals ...any)

Append appends vals to the ErrorCell.

When the cell is blank, the first of vals becomes the cell's title and the rest become its body. If the cell is not blank, all vals become the cell's body.

func (*ErrorCell) Erase 

func (c *ErrorCell) Erase()

Erase clears the content of the cell.

func (*ErrorCell) Type 

func (c *ErrorCell) Type() string

Returns "ErrorCell". Used for marshaling.

type HTMLCell 

type HTMLCell struct {
	HTML string `json:"html"`
}

HTMLCell is a cell with markdown-formatted text.

func NewHTMLCell 

func NewHTMLCell(vals ...any) *HTMLCell

NewHTMLCell creates HTMLCell.

func (*HTMLCell) Append 

func (c *HTMLCell) Append(vals ...any)

Append converts vals to strings and appends them to the cell.

func (*HTMLCell) Erase 

func (c *HTMLCell) Erase()

Erase clears the content of the cell.

func (*HTMLCell) Type 

func (c *HTMLCell) Type() string

Returns "HTMLCell". Used for marshaling.

type ImageCell 

type ImageCell struct {
	Images []AnnotatedImage `json:"images"`
	Error  *ErrorCell       `json:"error"`
	// contains filtered or unexported fields
}

ImageCell is a cell with annotated images.

func NewImageCell 

func NewImageCell(tempDir string, vals ...any) *ImageCell

NewImageCell creates ImageCell.

func (*ImageCell) Append 

func (c *ImageCell) Append(vals ...any)

Append appends one or more AnnotatedImages to the cell. vals are converted to annotated images by the rules described in Devcard.Image.

func (*ImageCell) Erase 

func (c *ImageCell) Erase()

Erase clears the content of the cell.

func (*ImageCell) Type 

func (c *ImageCell) Type() string

Returns "ImageCell". Used for marshaling.

type JumpCell 

type JumpCell struct {
	// Delay in milliseconds.
	Delay int
}

JumpCell is a cell to which we scroll when it's rendered.

func NewJumpCell 

func NewJumpCell() *JumpCell

NewJumpCell creates JumpCell.

func (*JumpCell) Append 

func (c *JumpCell) Append(vals ...any)

Noop.

func (*JumpCell) Erase 

func (c *JumpCell) Erase()

Noop.

func (*JumpCell) Type 

func (c *JumpCell) Type() string

Returns "JumpCell". Used for marshaling.

type MarkdownCell 

type MarkdownCell struct {
	Text string `json:"text"`
}

MarkdownCell is a cell with markdown-formatted text.

func NewMarkdownCell 

func NewMarkdownCell(vals ...any) *MarkdownCell

NewMarkdownCell creates MarkdownCell.

func (*MarkdownCell) Append 

func (c *MarkdownCell) Append(vals ...any)

Append converts vals to strings and appends them to the cell.

func (*MarkdownCell) Erase 

func (c *MarkdownCell) Erase()

Erase clears the content of the cell.

func (*MarkdownCell) Type 

func (c *MarkdownCell) Type() string

Returns "MarkdownCell". Used for marshaling.

type MonospaceCell 

type MonospaceCell struct {
	Text         string `json:"text"`
	Highlighting string `json:"highlighting"`
}

MonospaceCell is a cell that's supposed to be rendered as monospace, such as block of code.

func NewMonospaceCell 

func NewMonospaceCell(vals ...any) *MonospaceCell

NewMonospaceCell creates MonospaceCell.

func (*MonospaceCell) Append 

func (c *MonospaceCell) Append(vals ...any)

Append converts vals to strings and appends them to the cell. WithHighlighting option can be used at any position to enable syntax highlighting. See Devcard.Mono for example.

func (*MonospaceCell) Erase 

func (c *MonospaceCell) Erase()

Erase clears the content of the cell.

func (*MonospaceCell) Type 

func (c *MonospaceCell) Type() string

Returns "MonospaceCell". Used for marshaling.

type SourceCell 

type SourceCell struct {
	Decls []string `json:"decls"`
}

SourceCell is a cell with source code of a function.

func NewSourceCell 

func NewSourceCell(decls ...string) *SourceCell

NewSourceCell creates SourceCell.

func (*SourceCell) Append 

func (c *SourceCell) Append(vals ...any)

Append converts vals to strings and appends them to the cell.

func (*SourceCell) Erase 

func (c *SourceCell) Erase()

Erase clears the content of the cell.

func (*SourceCell) Type 

func (c *SourceCell) Type() string

Returns "SourceCell". Used for marshaling.

type ValueCell 

type ValueCell struct {
	Values []string `json:"values"`
}

ValueCell is a cell with pretty-printed Go values.

func NewValueCell 

func NewValueCell(vals ...any) *ValueCell

NewValueCell creates ValueCell.

func (*ValueCell) Append 

func (c *ValueCell) Append(vals ...any)

Append appends pretty-printed vals to the cell.

func (*ValueCell) Erase 

func (c *ValueCell) Erase()

Erase clears the content of the cell.

func (*ValueCell) Type 

func (c *ValueCell) Type() string

Returns "ValueCell". Used for marshaling.

Source Files

View all Source files

Directories

Path Synopsis
cmd
devcards
pkg
internal/file
internal/project
runtime
server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.