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
- Variables
- func Debug(producer DevcardProducer)
- func WithHighlighting(lang string) monospaceCellOption
- type AnnotatedImage
- type AnnotatedValue
- type AnnotatedValueCell
- type Cell
- type CustomCell
- type 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) Mono(vals ...any) *MonospaceCell
- func (d *Devcard) MonoFmt(format string, a ...any) *MonospaceCell
- func (d *Devcard) Replace(oldCell, newCell Cell)
- func (d *Devcard) ReplaceLast(newCell Cell)
- 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 DevcardInfo
- type DevcardProducer
- type ErrorCell
- type HTMLCell
- type ImageCell
- type JumpCell
- type MarkdownCell
- type MonospaceCell
- type SourceCell
- type ValueCell
Constants ¶
const ( MessageTypeCell = "cell" MessageTypeInfo = "info" MessageTypeError = "internal error" )
Message types are used for communication with devcards server via TCP connection.
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 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 ¶
AnnotatedImage as an image with its description.
type AnnotatedValue ¶
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 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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) MarshalJSON ¶
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 ¶
Replace replaces oldCell with newCell.
The new cell is immediately sent to the client.
func (*Devcard) ReplaceLast ¶
ReplaceLast replaces the bottom cell of the devcard with newCell.
The new cell is immediately sent to 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 ¶
UnmarshalJSON unmarshals JSON data into the devcard.
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 ¶
ErrorCell is a cell for error reporting.
type HTMLCell ¶
type HTMLCell struct {
HTML string `json:"html"`
}
HTMLCell is a cell with markdown-formatted text.
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 ¶
NewImageCell creates ImageCell.
func (*ImageCell) Append ¶
Append appends one or more AnnotatedImages to the cell. vals are converted to annotated images by the rules described in Devcard.Image.
type JumpCell ¶
type JumpCell struct {
// Delay in milliseconds.
Delay int
}
JumpCell is a cell to which we scroll when it's rendered.
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) Type ¶
func (c *MarkdownCell) Type() string
Returns "MarkdownCell". Used for marshaling.
type MonospaceCell ¶
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) 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) Type ¶
func (c *SourceCell) Type() string
Returns "SourceCell". Used for marshaling.
Source Files
Directories