package html

import "shirakumo.org/markless/html"

Converts Markless components.Component s to HTML via Convert.

This relies on an ad-hoc, minimal HTML DOM implemented in this package as well. Usually you will only care about the string representation of the HTML, which you can obtain via ConvertString or using [Node.AsText]. If you would like to manually manipulate the DOM, see Node and Element.

If you provide custom components.Component types yourself, you will need to implement the Convertable interface as well in order to handle the HTML transformation of your custom type.

Index

Functions

func ConvertString

func ConvertString(in components.Component) string

Convenience function to call Convert and [Node.AsText].

func HtmlEncode

func HtmlEncode(in string) string

Returns a string with &, <, >, and " replaced by HTML entities.

Types

type Convertable

type Convertable interface {
	ToNode() Node
}

Interface used to convert third-party components.Component types.

type ConvertableOption

type ConvertableOption interface {
	ToNodeOption(in *Element) *Element
}

Interface used to convert third-party components.Option types.

type Converter

type Converter func(in components.Component) Node

Callback function to handle conversion of child nodes within Convert and ConvertOption.

type Element

type Element struct {
	Tag        string
	Attributes map[string]string
	Style      map[string]string
	ClassList  []string
	Children   []Node
	Parent     *Element
}

Representation of an HTML Element node. No strict attribute, class, style, or parent/child relation checking is done. This DOM is only meant for minimum-effort HTML construction, not for any serious work outside of the use-case of the Markless conversion. Use NewElement to construct a new instance.

func ConvertOption

func ConvertOption(in components.Option, cur *Element, converter Converter) *Element

Converts the given option. This will typically modify the passed element in some way. However it may also replace the element by returning a different one. If the type is a third-party type, [ConvertableOption.ToNodeOption] is called.

func NewElement

func NewElement(tag string) *Element

Constructs a new Element instance with the given tag.

func (*Element) AddClass

func (e *Element) AddClass(class string) *Element

Adds the given class if it doesn't exist yet and returns the element again.

func (*Element) AppendChild

func (e *Element) AppendChild(child Node) *Element

Appends the given child node and returns the element again.

func (*Element) AsElement

func (e *Element) AsElement() *Element

Returns the element again.

func (*Element) AsText

func (e *Element) AsText() string

Returns the element as HTML source code.

func (*Element) InsertAfter

func (e *Element) InsertAfter(insert Node, sibling Node) *Element

Inserts the given insert node after the given sibling node and returns the element again. If the sibling does not exist as a child, the insert node is added to the back.

func (*Element) InsertBefore

func (e *Element) InsertBefore(insert Node, sibling Node) *Element

Inserts the given insert node before the given sibling node and returns the element again. If the sibling does not exist as a child, the insert node is added to the front.

func (*Element) RemoveChild

func (e *Element) RemoveChild(child Node) *Element

Removes the given node if it exists as a child and returns the element again.

func (*Element) RemoveClass

func (e *Element) RemoveClass(class string) *Element

Removes the given class if it exists and returns the element again.

func (*Element) SetAttribute

func (e *Element) SetAttribute(attr string, val string) *Element

Sets the given attribute and returns the element again.

func (*Element) SetStyle

func (e *Element) SetStyle(attr string, val string) *Element

Sets the given style and returns the element again.

func (*Element) SetTag

func (e *Element) SetTag(tag string) *Element

Changes the tag and returns the element again.

func (*Element) String

func (e *Element) String() string

Returns the element as HTML source code.

func (*Element) Write

func (e *Element) Write(sb io.StringWriter) io.StringWriter

Writes the HTML source code representation of the element to the given writer.

type Node

type Node interface {
	AsElement() *Element
	AsText() string
	Write(sb io.StringWriter) io.StringWriter
}

Interface used to represent an HTML DOM tree node. See Element and Text.

func Convert

func Convert(in components.Component) Node

Convenience function to call DefaultConvert with Convert.

func DefaultConvert

func DefaultConvert(in components.Component, converter Converter) Node

Converts the given components.Component type to an HTML Node. If the type is a third-party type, [Convertable.ToNode] is called.

Typically for a components.Root input, an <article> element is constructed, meaning it will not produce a wholly standalone HTML document. It is up to you to wrap the article element in the necessary HTML to produce a full document. This is done as we cannot know whether the Markless document should be standalone, or part of a larger page.

You can customise how individual nodes are treated by passing a Converter function. This function is called for any child node that is converted, so you can decide whether to handle it, or whether to call DefaultConvert again if you don't care.

type RawHTML

type RawHTML string

Encapsulation of a raw HTML source code string for use in a DOM.

func (RawHTML) AsElement

func (e RawHTML) AsElement() *Element

Returns nil.

func (RawHTML) AsText

func (e RawHTML) AsText() string

Returns the string bare.

func (RawHTML) Write

func (e RawHTML) Write(sb io.StringWriter) io.StringWriter

Writes the [HtmlEncoded] string to the writer.

type Text

type Text string

Encapsulation of a text string for use in a DOM.

func (Text) AsElement

func (e Text) AsElement() *Element

Returns nil.

func (Text) AsText

func (e Text) AsText() string

Returns the string bare.

func (Text) Write

func (e Text) Write(sb io.StringWriter) io.StringWriter

Writes the [HtmlEncoded] string to the writer.