gmi

Documentation

Overview

Package gmi provides tools for reading Gemini text and converting it to HTML.

Index

• type LineType
  • func (typ LineType) String() string
• type Scanner
  • func NewScanner(r io.Reader) *Scanner
  • func (s *Scanner) Buffer(buf []byte, max int)
  • func (s *Scanner) Err() error
  • func (s *Scanner) Line() int
  • func (s *Scanner) Scan() bool
  • func (s *Scanner) Text() string
  • func (s *Scanner) TextBytes() []byte
  • func (s *Scanner) Type() LineType
  • func (s *Scanner) URL() string
  • func (s *Scanner) URLBytes() []byte

Examples

• Scanner

Types

type LineType

type LineType int

LineType describes the type of line in Gemini formatted text.

const (
	// Head1 is a heading level 1 line.  It is a line that starts with # and is
	// optionally followed by whitespace.
	Head1 LineType = iota + 1
	// Head2 is a heading level 2 line.  It is a line that starts with ## and is
	// optionally followed by whitespace.
	Head2
	// Head3 is a heading level 3 line.  It is a line that starts with ### and
	// is optionally followed by whitspace.
	Head3
	// Text is a normal text line.  This is the default line type.
	Text
	// Link is a line containing a link.  It is a line that starts with => and
	// is followed by a URL and optional text to describe the link, each
	// separated by whitespace.
	Link
	// PreStart is a line that starts preformatted text.  It is a line that
	// starts with “` and may have additional alternative text.
	PreStart
	// PreBody is a line of text that should be rendered as preformatted text.
	// It's a line in-between lines that start with “`.
	PreBody
	// PreEnd is a line that ends preformatted text.  It's a line that starts
	// with “` that comes after a previous line that starts with “`.  Any text
	// after the “` should be ignored.
	PreEnd
	// List is an unordered list line.  It's a line that starts with * .
	List
	// Quote is a line containing a quoted text.  It's a line that starts with
	// >.
	Quote
)

func (LineType) String

func (typ LineType) String() string

String returns the string representation of the line type. For example, for Head3 it will return the string "Head3".

type Scanner

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

Scanner provides an interface for reading Gemini formatted text. Text is assumed to be UTF-8 encoded. This is a line-based scanner where new lines are delimited by either CRLF (\r\n DOS/Windows format) or LF (\n UNIX format).

This uses the bufio.Scanner from Go's standard library to scan input text line by line. Each successive call to the Scan method will step through the lines of the input text. Each line can be identified by it's Gemini type by calling the Type method.

Scanning stops unrecoverably at EOF, the first I/O error, or an input line too large to fit in the buffer.

For reference, the text/gemini format is described here:

https://gemini.circumlunar.space/docs/specification.html

Alternatively:

gemini://gemini.circumlunar.space/docs/specification.gmi

Example

Using Scanner to read Gemini text line by line.

package main

import (
	"fmt"
	"os"
	"strings"

	"git.sr.ht/~kiba/gdn/gmi"
)

const geminiText = `# Example Gemini
This is a line of text.
=> gemini://gemini.circumlunar.space/ Gemini`

// Using Scanner to read Gemini text line by line.
func main() {
	scanner := gmi.NewScanner(strings.NewReader(geminiText))
	for scanner.Scan() {
		if scanner.Type() == gmi.Link {
			fmt.Printf("line %d: %s: url %s: %s\n",
				scanner.Line(), scanner.Type(), scanner.URL(), scanner.Text())
		} else {
			fmt.Printf("line %d: %s: %s\n",
				scanner.Line(), scanner.Type(), scanner.Text())
		}
	}

	if err := scanner.Err(); err != nil {
		fmt.Fprintln(os.Stderr, err)
	}

}

Output:

line 1: Head1: Example Gemini
line 2: Text: This is a line of text.
line 3: Link: url gemini://gemini.circumlunar.space/: Gemini

func NewScanner

func NewScanner(r io.Reader) *Scanner

NewScanner returns a new Scanner to read from r.

func (*Scanner) Buffer

func (s *Scanner) Buffer(buf []byte, max int)

Buffer sets the initial buffer to use when scanning and the maximum size of buffer that may be allocated during scanning. The maximum input line size is the larger of max and cap(buf). If max <= cap(buf), Scan will use this buffer only and do no allocation.

By default, Scan uses an internal buffer and sets the maximum token size to bufio.MaxScanTokenSize (64 kilobytes).

Buffer panics if it is called after scanning has started.

func (*Scanner) Err

func (s *Scanner) Err() error

Err returns the first non-EOF error that was encountered by the Scanner.

func (*Scanner) Line

func (s *Scanner) Line() int

Line is the line number that has just been scanned by the Scan method. Will return 0 if Scan has not been called yet.

func (*Scanner) Scan

func (s *Scanner) Scan() bool

Scan advances the Scanner to the next line of text, which will then be available through the TextBytes or Text methods. The Gemini line type scanned will be available through the Type method. If the line type scanned was a link the URL for the link will be available via the URL and URLBytes methods. It returns false when the scan stops, either by reaching the end of the input or an error. After Scan returns false, the Err method will return any error that occurred during scanning, except that if it was io.EOF, Err will return nil.

Scan panics if the split function returns too many empty lines without advancing the input. This is a common error mode for scanners.

func (*Scanner) Text

func (s *Scanner) Text() string

Text returns the most recent text for the Gemini line generated by a call to Scan as a newly allocated string holding its bytes.

func (*Scanner) TextBytes

func (s *Scanner) TextBytes() []byte

TextBytes returns the most recent text for the Gemini line generated by a call to Scan. The underlying array may point to data that will be overwritten by a subsequent call to Scan. It does no allocation.

func (*Scanner) Type

func (s *Scanner) Type() LineType

Type returns the LineType of the line of Gemini text that was just scanned by the Scan method.

func (*Scanner) URL

func (s *Scanner) URL() string

URL returns the URL if the Gemini line is a link from the most recent call to Scan as a newly allocated string holding its bytes. Is empty if the line scanned was not a link.

func (*Scanner) URLBytes

func (s *Scanner) URLBytes() []byte

URLBytes returns the URL if the Gemini line is a link from the most recent call to Scan. The underlying array may point to data that will be overwritten by a subsequent call to Scan. It does no allocation. Is nil if the line scanned was not a link.