markout

package module
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2022 License: MIT Imports: 10 Imported by: 0

README

go-markout

GoDoc

go-markout is a GO library of structured document writers

Features:

  • writing to HTML, Markdown, and Plain text targets
  • structuring documents with sections, lists, and tables
  • decorating inline content with styles and links
  • enjoying the same API regardless of the output format
  • marshaling custom types with in-line styling
  • writing content simultaneously to multiple targets

Warning: unstable API, WIP

Documentation

Automatically generated documentation for the package can be viewed online here: http://pkg.go.dev/github.com/adnsv/go-markout

Documentation

Index

Examples

Constants

View Source 
const (
	SingleQuotedStyle = Style(iota) // a fragment surrounded by single quotation marks
	DoubleQuotedStyle               // a fragment surrounded by double quotation marks
	EmphasizedStyle                 // emphasized fragment, typically rendered in italic type
	StrongStyle                     // strong fragment, typically rendered in bold type
)

Accepted Style values:

View Source 
const (
	ASCIIQuotes         = `'|'|"|"`
	TypographicalQuotes = `‘|’|“|”`
)

Quotation marks

Variables

This section is empty.

Functions

func DoubleQuoted added in v0.2.0 

func DoubleQuoted(a any) style_wrapper

DoubleQuoted creates a wrapper for double quoted inline spans.

func Emphasized added in v0.2.0 

func Emphasized(a any) style_wrapper

DoubleQuoted creates a wrapper for emphasized (italic) inline spans. 

func Link(caption any, url string) link_wrapper

Link creates a wrapper for a named links.

func SingleQuoted added in v0.2.0 

func SingleQuoted(a any) style_wrapper

SingleQuoted creates a wrapper for single quoted inline spans.

func Strong added in v0.2.0 

func Strong(a any) style_wrapper

DoubleQuoted creates a wrapper for strong-formatted (bold) inline spans.

func URL added in v0.3.4 

func URL(url string) link_wrapper

URL creates a wrapper for an unnamed link.

Example 
url_filter := func(url string) []byte {
	return []byte(filepath.Base(url))
}

w := NewTXT(os.Stdout, TXTOptions{URLFilter: url_filter})
w.Paraf("Link: %s", Link("test", "../../path.txt"))
w.Paraf("URL: %s", URL("../../path.txt"))
w.Close()

Output:

Link: [test](path.txt)

URL: path.txt

Types

type Callback added in v0.3.2 

type Callback = func(Printer)

Callback is a funcional inline content builder that can be used for complex inline formatting.

type HTMLOptions 

type HTMLOptions struct {
	PutBOM         bool
	QuotationMarks string
	Title          string
	Style          string
	ListTitleClass string
	URLFilter      url_filter
}

type InlineMarshaler 

type InlineMarshaler interface {
	MarshalMarkoutInline(Printer) error
}

InlineMarshaler is the interface implemented by types that support marshal custom marshaling into markout targets (as inline fragments).

type ListWriter added in v0.3.0 

type ListWriter interface {
	// ListTitle writes paragraph block that acts as a title preceeding a list.
	ListTitle(a any)
	ListTitlef(format string, args ...any)

	// BeginOList and BeginUList begins a list block (ordered or unourdered). If
	// writer is already in list mode, this begins a child list. Each BeginList
	// must be matched with EndList.
	BeginOList()
	BeginUList()
	EndList()

	// ListItem writes an item into the list block. Must be called within the
	// BeginList()/EndList() fragment.
	ListItem(a any)

	// ListItemf is a version of ListItem() with built-in formatting.
	ListItemf(format string, args ...any)

	// Callback-based list writing methods that automatically wrap items
	// BeginList/EndList blocks.
	OList(func(ListWriter))
	UList(func(ListWriter))
}

ListWriter is an interface for writing items and child lists into list blocks.

type MDOptions 

type MDOptions struct {
	PutBOM         bool
	QuotationMarks string // pipe-separated single and double quotes (defaults to '|'|"|")
	URLFilter      url_filter
}

type MultiWriter added in v0.3.0 

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

MultiWriter implements a writer that funnels its output to other writers.

func NewMultiWriter added in v0.3.0 

func NewMultiWriter(targets ...Writer) *MultiWriter

NewMultiWriter constructs a MultiWriter that writes into targets.

Example 
buf := bytes.Buffer{}
html_w := NewHTML(&buf, HTMLOptions{})
cout_w := NewTXT(os.Stdout, TXTOptions{})
null_w := NewNULL()

multi_w := NewMultiWriter(cout_w, html_w, null_w)

w := Writer(multi_w)
w.ListTitle("List:")
w.UList(func(li ListWriter) {
	li.ListItem("item 1")
	li.ListItem("item 2")
})
w.Table([]any{"h1", "h2"}, func(row TableRowWriter) {
	row("c1", "c2")
	row("c3", "cell4")
})

cout_w.Close()
html_w.Close()

fmt.Printf("************\n")
os.Stdout.Write(buf.Bytes())

Output:

List:
* item 1
* item 2

h1 h2
-- -----
c1 c2
c3 cell4

************
<html>
<body>
<p>List:</p>
<ul>
  <li>item 1</li>
  <li>item 2</li>
</ul>

<table>
<thead><tr><th>h1</th><th>h2</th></tr></thead>
<tbody>
<tr><td>c1</td><td>c2</td></tr>
<tr><td>c3</td><td>cell4</td></tr>
</tbody>
</table>

</body>
</html>

func (*MultiWriter) BeginOList added in v0.3.1 

func (w *MultiWriter) BeginOList()

func (*MultiWriter) BeginSection added in v0.3.0 

func (w *MultiWriter) BeginSection(a any)

func (*MultiWriter) BeginSectionf added in v0.3.0 

func (w *MultiWriter) BeginSectionf(format string, args ...any)

func (*MultiWriter) BeginTable added in v0.3.0 

func (w *MultiWriter) BeginTable(first_column any, other_columns ...any)

func (*MultiWriter) BeginUList added in v0.3.1 

func (w *MultiWriter) BeginUList()

func (*MultiWriter) Close added in v0.3.0 

func (w *MultiWriter) Close()

func (*MultiWriter) CloseEx added in v0.5.2 

func (w *MultiWriter) CloseEx(ps func(ParagraphWriter))

func (*MultiWriter) DisableOutput added in v0.3.3 

func (w *MultiWriter) DisableOutput()

func (*MultiWriter) EnableOutput added in v0.3.3 

func (w *MultiWriter) EnableOutput()

func (*MultiWriter) EndList added in v0.3.0 

func (w *MultiWriter) EndList()

func (*MultiWriter) EndSection added in v0.3.0 

func (w *MultiWriter) EndSection()

func (*MultiWriter) EndTable added in v0.3.0 

func (w *MultiWriter) EndTable()

func (*MultiWriter) ListItem added in v0.3.0 

func (w *MultiWriter) ListItem(a any)

func (*MultiWriter) ListItemf added in v0.3.0 

func (w *MultiWriter) ListItemf(format string, args ...any)

func (*MultiWriter) ListTitle added in v0.3.0 

func (w *MultiWriter) ListTitle(a any)

func (*MultiWriter) ListTitlef added in v0.3.0 

func (w *MultiWriter) ListTitlef(format string, args ...any)

func (*MultiWriter) OList added in v0.3.1 

func (w *MultiWriter) OList(items func(ListWriter))

func (*MultiWriter) Para added in v0.3.0 

func (w *MultiWriter) Para(a any)

func (*MultiWriter) Paraf added in v0.3.0 

func (w *MultiWriter) Paraf(format string, args ...any)

func (*MultiWriter) Section added in v0.3.0 

func (w *MultiWriter) Section(a any)

func (*MultiWriter) Sectionf added in v0.3.0 

func (w *MultiWriter) Sectionf(format string, args ...any)

func (*MultiWriter) Table added in v0.3.0 

func (w *MultiWriter) Table(columns []any, rows func(cb TableRowWriter))

func (*MultiWriter) TableRow added in v0.3.0 

func (w *MultiWriter) TableRow(first_cell any, other_cells ...any)

func (*MultiWriter) UList added in v0.3.1 

func (w *MultiWriter) UList(items func(ListWriter))

type ParagraphWriter added in v0.5.2 

type ParagraphWriter = interface {
	// Para writes paragraph block.
	Para(a any)
	Paraf(format string, args ...any)
}

ParagraphWriter interface supports writing plain paragraphs.

type Printer added in v0.1.0 

type Printer interface {
	// Low-level string content
	WriteString(string)
	WriteRawBytes([]byte)

	// Code spans
	CodeString(string)
	CodeRawBytes([]byte)

	// Inline links
	BeginLink(url string)
	EndLink()

	// Quoted spans
	BeginStyled(Style)
	EndStyled()

	// High-level api
	Print(any)
	Printf(format string, args ...any)
	SimpleLink(a any, url string)
	Styled(Style, any)
}

Printer is an interface used in callbacks and custom marshalers for writing inline content.

type RawContent added in v0.5.1 

type RawContent []byte

RawContent is the the sequence of bytes that is written out to a target 'as-is'. No additional scrambling or escaping is performed.

type SectionWriter added in v0.5.2 

type SectionWriter = interface {
	// BeginSection writes the section heading block and increments section level
	// counter. Each BeginSection() call must be followed by matching EndSection()
	BeginSection(a any)
	BeginSectionf(format string, args ...any)

	// EndSection decrements section level counter.
	EndSection()

	// Section writes section heading without incrementing section level counter.
	Section(a any)
	Sectionf(format string, args ...any)
}

SectionWriter is an interface that supports structured sectioning of a document.

type Style added in v0.2.0 

type Style int

Style provides decorations for spans in inline output. Styles can be nested.

type TXTOptions 

type TXTOptions struct {
	PutBOM             bool
	QuotationMarks     string // pipe-separated single and double quotes (defaults to '|'|"|")
	ListItemPrefix     string // content inserted before each list item (defaults to `* `)
	UnderlinedSections bool
	NumberedSections   bool
	URLFilter          url_filter
}

type TableRowWriter added in v0.5.2 

type TableRowWriter = func(first_cell any, other_cells ...any)

TableRowWriter is a callback for writing table rows.

type TableWriter added in v0.3.0 

type TableWriter = interface {
	// BeginTable starts table mode.
	//   - only TableRow() calls are supported while in tablt mode.
	//   - use EndTable() to exit from the table mode.
	BeginTable(first_column any, other_columns ...any)
	TableRow(first_cell any, other_cells ...any)
	EndTable()

	// Callback-based table writing method that begins a new table, writes rows
	// into it with callback, then calls EndTable.
	Table(columns []any, rows func(callback TableRowWriter))
}

TableWriter interface supports writing of tabular data.

type UnsupportedTypeError 

type UnsupportedTypeError struct {
	Type reflect.Type
}

UnsupportedTypeError is returned when Marshal encounters a type that cannot be converted into markout.

func (*UnsupportedTypeError) Error 

func (e *UnsupportedTypeError) Error() string

type Writer 

type Writer interface {
	SectionWriter
	ParagraphWriter
	ListWriter
	TableWriter

	Close()
	CloseEx(ps func(ParagraphWriter))

	DisableOutput()
	EnableOutput()
}

Writer is a high level interface for writing markout documents in all supported formats.

func NewHTML 

func NewHTML(out io.Writer, opts HTMLOptions) Writer

NewHtml creates a new markout writer targeting html output.

Example 
buf := bytes.Buffer{}
w := NewHTML(&buf, HTMLOptions{PutBOM: false})
w.Para("Para")
w.BeginUList()
w.ListItem("list item")
w.ListItem(3.14)
w.ListItem(true)
w.ListItem(42)
w.ListItem("subitems:")
w.BeginOList()
w.ListItem("subitem1")
w.ListItem(Emphasized("subitem2"))
w.ListItem(SingleQuoted("subitem3"))
w.ListItem(Emphasized(SingleQuoted("subitem4")))
w.EndList()
w.ListItem("last")
w.EndList()
w.BeginTable("thead", "thead")
w.TableRow("tcell", "tcell")
w.EndTable()
w.BeginSection("Section")
w.BeginSection("SubSection")
w.Section("SubSubSection")
w.EndSection()
w.EndSection()
w.Close()
out := buf.String()
fmt.Println(out)

Output:

<html>
<body>
<p>Para</p>

<ul>
  <li>list item</li>
  <li>3.14</li>
  <li>true</li>
  <li>42</li>
  <li>subitems:</li>
  <ol>
    <li>subitem1</li>
    <li><em>subitem2</em></li>
    <li>'subitem3'</li>
    <li><em>'subitem4'</em></li>
  </ol>
  <li>last</li>
</ul>

<table>
<thead><tr><th>thead</th><th>thead</th></tr></thead>
<tbody>
<tr><td>tcell</td><td>tcell</td></tr>
</tbody>
</table>

<h1>Section</h1>

<h2>SubSection</h2>

<h3>SubSubSection</h3>

</body>
</html>

func NewMD 

func NewMD(out io.Writer, opts MDOptions) Writer

NewMD creates a new markout writer targeting markdown output.

Example 
buf := bytes.Buffer{}
w := NewMD(&buf, MDOptions{PutBOM: false})
w.Section("Section")
w.Para("Para")
w.BeginUList()
w.ListItem("list item")
w.ListItem(3.14)
w.ListItem(true)
w.ListItem(42)
w.ListItem("subitems:")
w.BeginOList()
w.ListItem("subitem1")
w.ListItem(Emphasized("subitem2"))
w.EndList()
w.ListItem("last")
w.EndList()

w.Para(func(p Printer) {
	p.Print("Inline formatting: ")
	p.BeginStyled(DoubleQuotedStyle)
	p.Styled(EmphasizedStyle, "Hello")
	p.Print(", ")
	p.Styled(StrongStyle, "World!")
	p.EndStyled()
})

w.BeginTable("th", "thead")
w.TableRow("tcell", "tcell")
w.EndTable()
w.Close()
out := buf.String()
fmt.Println(out)

Output:

# Section

Para

- list item
- 3.14
- true
- 42
- subitems:
  1. subitem1
  2. <em>subitem2</em>
- last

Inline formatting: "<em>Hello</em>, <strong>World\!</strong>"

th | thead
---|------
tcell | tcell

func NewNULL added in v0.3.0 

func NewNULL() Writer

func NewTXT 

func NewTXT(out io.Writer, opts TXTOptions) Writer

NewTxt creates a new markout writer targeting plain text output.

Example 
buf := bytes.Buffer{}
w := NewTXT(&buf, TXTOptions{
	PutBOM:             false,
	NumberedSections:   true,
	UnderlinedSections: true})
w.Para("Para")
w.ListTitle("list:")
w.BeginUList()
w.ListItem("list item")
w.ListItem(3.14)
w.ListItem(true)
w.ListItem(42)
w.ListItem("subitems:")
w.BeginOList()
w.ListItem("subitem1")
w.ListItem(Emphasized("subitem2"))
w.ListItem(SingleQuoted("subitem3"))
w.ListItem(Emphasized(SingleQuoted("subitem4")))
w.ListItem(URL("subitem5"))
w.ListItem(Link("a", "b"))
w.EndList()
w.ListItem("last")
w.EndList()
w.BeginTable("th1", "th2")
w.TableRow("tcell", "another cell")
w.EndTable()
w.BeginSection("SECTION")
w.BeginSection("SUBSECTION")
w.Section("First SubSubSection")
w.Section("Second SubSubSection")
w.Section("Third SubSubSection")
w.EndSection()
w.Section("ANOTHER SUBSECTION")
w.EndSection()
w.Close()
out := buf.String()
fmt.Println(out)

Output:

Para

list:
* list item
* 3.14
* true
* 42
* subitems:
  1. subitem1
  2. *subitem2*
  3. 'subitem3'
  4. *'subitem4'*
  5. subitem5
  6. [a](b)
* last

th1   th2
----- ------------
tcell another cell

1. SECTION
==========

1.1. SUBSECTION
---------------

1.1.1. First SubSubSection

1.1.2. Second SubSubSection

1.1.3. Third SubSubSection

1.2. ANOTHER SUBSECTION
-----------------------

Source Files

View all Source files

Directories

Path Synopsis

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.