package devcard

import "github.com/igorhub/devcard"

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

For proper introduction, see README.

Index ¶

• Constants
• Variables
• func Debug(producer DevcardProducer)
• func Interrupt()
• func WithHighlighting(lang string) monospaceCellOption
• func WithStandardCSS() cssOption
• type AnnotatedImage
• type AnnotatedValue
• type AnnotatedValueCell
• func NewAnnotatedValueCell(annotationsAndVals ...any) *AnnotatedValueCell
• func (c *AnnotatedValueCell) Append(annotationsAndVals ...any)
• func (c *AnnotatedValueCell) Erase()
• func (c *AnnotatedValueCell) Type() string
• type Cell
• func UnmarshalCell(cellType string, data []byte) (Cell, error)
• type CustomCell
• func (c *CustomCell) Append(vals ...any)
• func (c *CustomCell) Erase()
• func (c *CustomCell) Type() string
• type Devcard
• func Current() *Devcard
• func (d *Devcard) Ann(annotationsAndVals ...any) *AnnotatedValueCell
• func (d *Devcard) Append(vals ...any)
• func (d *Devcard) Custom(cell customCell)
• func (d *Devcard) Erase(cell Cell)
• func (d *Devcard) EraseLast()
• func (d *Devcard) Error(vals ...any) *ErrorCell
• func (d *Devcard) Html(vals ...any) *HTMLCell
• func (d *Devcard) Image(annotationsAndImages ...any) *ImageCell
• func (d *Devcard) Jump() *JumpCell
• func (d *Devcard) MarshalJSON() ([]byte, error)
• func (d *Devcard) Md(vals ...any) *MarkdownCell
• func (d *Devcard) MdFmt(format string, a ...any) *MarkdownCell
• func (d *Devcard) Mdf(format string, a ...any) *MarkdownCell
• func (d *Devcard) Mono(vals ...any) *MonospaceCell
• func (d *Devcard) MonoFmt(format string, a ...any) *MonospaceCell
• func (d *Devcard) Monof(format string, a ...any) *MonospaceCell
• func (d *Devcard) Replace(oldCell, newCell Cell)
• func (d *Devcard) ReplaceLast(newCell Cell)
• func (d *Devcard) SetCSS(styles ...any)
• func (d *Devcard) SetTitle(title string)
• func (d *Devcard) Source(decls ...string) *SourceCell
• func (d *Devcard) UnmarshalJSON(data []byte) error
• func (d *Devcard) Update(cell Cell)
• func (d *Devcard) Val(vals ...any) *ValueCell
• type DevcardMeta
• func (di DevcardMeta) Caption() string
• type DevcardProducer
• type ErrorCell
• func NewErrorCell(vals ...any) *ErrorCell
• func (c *ErrorCell) Append(vals ...any)
• func (c *ErrorCell) Erase()
• func (c *ErrorCell) Type() string
• type HTMLCell
• func NewHTMLCell(vals ...any) *HTMLCell
• func (c *HTMLCell) Append(vals ...any)
• func (c *HTMLCell) Erase()
• func (c *HTMLCell) Type() string
• type ImageCell
• func NewImageCell(tempDir string, vals ...any) *ImageCell
• func (c *ImageCell) Append(vals ...any)
• func (c *ImageCell) Erase()
• func (c *ImageCell) Type() string
• type JumpCell
• func NewJumpCell() *JumpCell
• func (c *JumpCell) Append(vals ...any)
• func (c *JumpCell) Erase()
• func (c *JumpCell) Type() string
• type MarkdownCell
• func NewMarkdownCell(vals ...any) *MarkdownCell
• func (c *MarkdownCell) Append(vals ...any)
• func (c *MarkdownCell) Erase()
• func (c *MarkdownCell) Type() string
• type MonospaceCell
• func NewMonospaceCell(vals ...any) *MonospaceCell
• func (c *MonospaceCell) Append(vals ...any)
• func (c *MonospaceCell) Erase()
• func (c *MonospaceCell) Type() string
• type SourceCell
• func NewSourceCell(decls ...string) *SourceCell
• func (c *SourceCell) Append(vals ...any)
• func (c *SourceCell) Erase()
• func (c *SourceCell) Type() string
• type ValueCell
• func NewValueCell(vals ...any) *ValueCell
• func (c *ValueCell) Append(vals ...any)
• func (c *ValueCell) Erase()
• func (c *ValueCell) Type() string

Constants ¶

const (
	MessageTypeCell  = "cell"
	MessageTypeTitle = "title"
	MessageTypeCSS   = "css"
	MessageTypeError = "internal error"
)

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

const CSSFromServer = "CSS from devcards-server"

Variables ¶

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 ¶

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.

func WithStandardCSS ¶

func WithStandardCSS() cssOption

WithStandardCSS is an option for devcard.SetCSS.

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"`
	CSS     []string `json:"css,omitempty"`
	// 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 ¶

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.

• For MarkdownCell, same rules as in Devcard.Md apply.
• For ErrorCell, same rules as in Devcard.Error apply.
• For MonospaceCell, same rules as in Devcard.Mono apply.
• For ValueCell, same rules as in Devcard.Val apply.
• Fro AnnotatedValueCell, same rules as in Devcard.Ann apply.
• For ImageCell, same rules as in Devcard.Image apply.
• For other types of cells, Append is a noop.

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

DEPRECATED: Please use Mdf.

func (*Devcard) Mdf ¶

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

Mdf 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

DEPRECATED: Please use Monof.

func (*Devcard) Monof ¶

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

Monof 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) SetCSS ¶

func (d *Devcard) SetCSS(styles ...any)

SetTitle sets the devcard's CSS styles. Styles can be either strings, byte slices (they get converted to strings), or options.

Each string (or byte slice) can be either a path in a filesystem, or a block of CSS code.

Options:

• WithStandardCSS(). With that option, all styles passed to SetCSS get appended to the stylesheet defined in the devcards config. Without that option, the server's stylesheet is ignored.

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 DevcardMeta ¶

type DevcardMeta 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
}

DevcardMeta describes devcard's metadata.

func (DevcardMeta) Caption ¶

func (di DevcardMeta) 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 ¶

cell.go devcard.go producer.go text.go

Directories ¶