prettyparlib

Documentation

Overview

prettyparlib is a library that format text strings and paragraphs.

There are couple of utilities available: namely, fold and par. fold (https://linux.die.net/man/1/fold) wraps a text string by a given length. Unfortunately, it knows nothing, that paragraphs may have an additional context structure.

par is more powerful that prettypar (https://bitbucket.org/amc-nicemice/par/src/master/) but way more complex at the same time. It knows about comments and text decorations but works poorly with lists. Also, its knowledge of text decorations drives me nuts. I haven't seen these ASCII-style text boxes for ages. But par tends to consider dots (.) as an element of that box and align based on that.

So, par is very opionated. It knows how to format this guy

# Hello, this is an example
# paragraph full of
# some random thoughts.
#
# Another paragraph.
#
#     1. lala
#     2. blabla
#
#   * long-long list of something

into this

# Hello, this is an example paragraph full of some random thoughts.
#
# Another paragraph.
#
#     1. lala
#     2. blabla
#
#   * long-long list of something

Index

• func Format(text string, options FormatOptions) string
• type FormatOptions
  • func (f FormatOptions) MarshalJSON() ([]byte, error)
  • func (f *FormatOptions) UnmarshalJSON(data []byte) error

Functions

func Format

func Format(text string, options FormatOptions) string

Format formats a given text based on provided options.

Text is considered as a text block by lines. Lines are split by a '\n' (I do not have any intention to support '\r\n' and friends).

Here is an anatomy of the text from Format's point of view:

   # Some prefix
   # lalala
   #
   #  1. blablabla
   #     and continue
   #  2. tututu

\--------------------/ <- paragraph
      \--------------/ <- list block
         \-----------/ <- text block

Text may have many paragraphs. Each paragraph is delimited by 1+ empty lines. A paragraph may have some common prefix, like comment etc.

Comments are so common that this function manages them recursively.

Each paragraph may be a list. List are made of this form:

1. N.
2. a.
3. -
4. *

Nested lists are fine but they have to be a paragraph itself. Each list may have a multiple lines. Each line has to be adjusted to a first one. Like this:

1. Hahaha Hahaha
2. lslsls

Incorrect list is treated as a text block. Each item is treated as a text block and adjusted relative to its bullet.

Text block is wrapped by a line length.

Types

type FormatOptions

type FormatOptions struct {
	// LineLength defines a count of utf-8 runes in a line. Negative
	// value effectively means 0.
	LineLength int

	// A regular expression that detects a paragraph prefix.
	ParagraphPrefixes *regexp.Regexp
}

FormatOptions contains options for Format function.

func (FormatOptions) MarshalJSON

func (f FormatOptions) MarshalJSON() ([]byte, error)

func (*FormatOptions) UnmarshalJSON

func (f *FormatOptions) UnmarshalJSON(data []byte) error