Help us shape the future of Go! Take the 2026 Go Developer Survey

document

package
v0.1.6 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package document owns file families and their viewing behavior.

Index

Constants

View Source 
const (
	// SniffLength is the prefix inspected for binary content.
	SniffLength = 8000
	// PreviewLimit is the largest file size that is previewed, formatted, or
	// highlighted. Larger files show escaped plain source.
	PreviewLimit = 4 << 20
	// SearchLimit is the largest file size included in content search.
	SearchLimit = 8 << 20
	// DisplayLimit is the largest text file read for display. Larger non-image
	// files show a "Too large to display" note.
	DisplayLimit = 32 << 20
)
View Source 
const (
	PreviewMarkdown = "markdown"
	PreviewImage    = "image"
)

Preview kinds rendered by the UI. Image previews use the file's raw bytes.

Variables

View Source 
var ErrNotFormattable = errors.New("file type is not formattable")

ErrNotFormattable is returned when formatting a family without a Formatter.

Functions

func DisplayReadLimit added in v0.1.6 

func DisplayReadLimit(fileType Type) int64

DisplayReadLimit is the largest file of a type read for display, or -1 for none: image previews use raw bytes, so they display at any size.

func IsBinary added in v0.1.6 

func IsBinary(content []byte) bool

IsBinary reports whether content has a NUL byte within its first SniffLength bytes.

Types

type Availability added in v0.1.6 

type Availability struct {
	// TooLarge files are not read; only a note is shown.
	TooLarge          bool
	PreviewDisabled   bool
	HighlightDisabled bool
	SearchExcluded    bool
}

Availability is what the size and binary limits leave of a file's views.

func Available added in v0.1.6 

func Available(fileType Type, size int64, binary bool) Availability

Available applies the size and binary limits to a file of fileType. Image previews need no server work, so they stay enabled at any size; large SVG source is still shown, unhighlighted.

type CodeHandler 

type CodeHandler struct {
	Definition Type
}

CodeHandler is reusable for explicitly registered source languages and image families: source and no HTML preview.

func (CodeHandler) Preview 

func (h CodeHandler) Preview([]byte, Context) (string, error)

func (CodeHandler) Type 

func (h CodeHandler) Type() Type

type Context 

type Context struct {
	Path     string
	Project  string
	Supports func(string) bool
}

Context supplies navigation policy without giving handlers filesystem access. Project scopes rewritten links to the current project; Supports reports whether a link target names an in-scope file.

type Family added in v0.1.6 

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

Family is a registered handler with registry-derived capabilities.

func (Family) Format added in v0.1.6 

func (f Family) Format(source []byte) ([]byte, error)

Format formats a copy of source and returns the formatted text.

func (Family) Preview added in v0.1.6 

func (f Family) Preview(source []byte, context Context) (string, error)

func (Family) Type added in v0.1.6 

func (f Family) Type() Type

Type returns the family metadata, including derived capabilities.

type FormattedCodeHandler added in v0.1.6 

type FormattedCodeHandler struct {
	CodeHandler
	FormatSource func([]byte) ([]byte, error)
}

FormattedCodeHandler adds an on-demand, read-only formatted view to source. FormatSource receives a copy of the file bytes.

func (FormattedCodeHandler) Format added in v0.1.6 

func (h FormattedCodeHandler) Format(source []byte) ([]byte, error)

type Formatter added in v0.1.6 

type Formatter interface {
	Format(source []byte) ([]byte, error)
}

Formatter is an optional Handler capability for a read-only formatted view. Errors leave the source view available.

type Handler 

type Handler interface {
	Type() Type
	Preview(source []byte, context Context) (string, error)
}

Handler owns presentation, never filesystem access. Content search reads original source, so handlers know nothing about it. Preview returns escaped HTML, or an error without making source unavailable. Handlers without an HTML preview return empty HTML.

func NewCSS added in v0.1.6 

func NewCSS() Handler

func NewHTML added in v0.1.6 

func NewHTML() Handler

func NewJSON 

func NewJSON() Handler

func NewJavaScript added in v0.1.6 

func NewJavaScript() Handler

func NewYAML 

func NewYAML() Handler

type Registry 

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

Registry is immutable after construction. It decides how a file is shown, never which files are in scope.

func Builtins 

func Builtins() *Registry

Builtins is the explicit composition point for file families. Registration only decides presentation; files outside these families use the plain-text fallback. Each family's Language names a Highlights language explicitly, or "text" for none; the browser highlights Source and Format (decision 0029).

func NewRegistry 

func NewRegistry(fallback Handler, handlers ...Handler) (*Registry, error)

NewRegistry composes a source-only fallback family for unregistered files with additional handlers.

func (*Registry) Lookup 

func (r *Registry) Lookup(name string) Family

Lookup returns the family for a file: exact base name, then extension, then the fallback. Every file has a family.

func (*Registry) MediaType added in v0.1.6 

func (r *Registry) MediaType(name string) (string, bool)

MediaType returns the media type a file's raw bytes are served as. Only image-preview families have one.

func (*Registry) Types 

func (r *Registry) Types() []Type

Types lists registered families, fallback first.

type Type 

type Type struct {
	ID           string   `json:"id"`
	Label        string   `json:"label"`
	Extensions   []string `json:"extensions"`
	Filenames    []string `json:"filenames"`
	Language     string   `json:"language"`
	PreviewKind  string   `json:"previewKind"`
	PreviewLabel string   `json:"previewLabel"`
	DefaultMode  string   `json:"defaultMode"`
	Formattable  bool     `json:"formattable"`
}

Type describes a file family and the views the UI can offer. Source is always available. An empty PreviewKind means no preview; extensions include their leading dot; filenames are exact base names. Matching is case-insensitive. Formattable is derived by the registry from the Formatter capability; handlers leave it unset. Language-server capabilities are composed by web. Language is a Highlights language ID for browser highlighting ("text" for none).

func (Type) HasTextSource added in v0.1.6 

func (t Type) HasTextSource() bool

HasTextSource reports whether files of this type have a text source view. Raster images (image previews without a language) are binary regardless of their bytes.

Source Files

View all Source files

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.