readtxt

Documentation

Overview

Package readtxt parses and formats read.txt formatted files.

Read.txt file format

Example:

-- not cataloged
the wizard of earthsea, ursula k. le guin / 1968

-- 2022
wolf hall, hilary mantel / 2009 *
lapvona, ottessa moshfegh / 2022
god bless you, mr. rosewater, kurt vonnegut / r *
my year of rest and relaxation, ottessa moshfegh

-- to read
donna tartt
the end of nightwork / 2023

Description:

A read.txt file lists books read. The file consists of sections. A section is separated from a previous section by one or more empty lines. Most sections represent a calendar year and the books read for that year.

Each section starts with a section heading. The syntax for a section heading line is:

-- [section name]

Section names can be any arbitrary string. However, if the section name looks like a year (more specifically, is exactly 4 digits long), then the section name is considered a calendar year, and the books listed under the section are the books read for that year. The special section name "not cataloged" can be used to list books for which the calendar year the books were read is not available.

Books are listed one per line under a section. Books read earlier are listed before books read later. The syntax for a book line is:

[title], [author] / [published year] [r] [*]

The author field must not contain commas. The published year field, if present, is used as provided without validation. A "r" explicitly marks the book as a reread. A "*" marks the book as a loved book. For books listed in a calendar year section or the not-cataloged section, both the title and author fields are required. For books in other sections, either the title or the author---or both---may be present.

Index

• Constants
• Variables
• func Format(w io.Writer, r *Reads) error
• type Book
• type Reads
  • func Parse(r io.Reader) (*Reads, error)
• type Section
• type SyntaxError
  • func (e SyntaxError) Error() string
  • func (e SyntaxError) Unwrap() error

Constants

const (
	SectionNotCataloged = "not cataloged" // name of the special "not cataloged" section
)

Variables

var (
	ErrOrphanBook      = errors.New("book not associated with any section")
	ErrMissingAuthor   = errors.New("missing comma for required author")
	ErrTooManyOptional = errors.New("too many optional fields")
)

Functions

func Format

func Format(w io.Writer, r *Reads) error

Format writes the read.txt formatted representation of the Reads to the supplied writer.

Types

type Book

type Book struct {
	Title     string
	Author    string
	Loved     bool
	Published string
	Reread    bool // valid for calendar year sections and the SectionNotCataloged section
}

Book specifies the details for a book in a read.txt file.

If the Author field is empty, then the Title field may represent the book title, the book author, or both, and it should generally be treated as an opaque value.

type Reads

type Reads struct {
	Sections []Section
}

Reads represents the sections and the books in a read.txt file.

func Parse

func Parse(r io.Reader) (*Reads, error)

Parse parses a read.txt input.

type Section

type Section struct {
	// Name is the section name. It is always non-empty. If the section name
	// represents a calendar year, then the Year field is set as described
	// below.
	Name string
	// Year represents the calendar year of the section, if applicable.
	// It is valid only when the value is >= 0.
	Year int
	// Books is the list of books in the section.
	Books []Book
}

Section is a section in a read.txt file.

type SyntaxError

type SyntaxError struct {
	// Line is the line number in the input (starting at 1) at which the
	// error occurred.
	Line int
	// Err is the underlying error (e.g. ErrOrphanBook, ErrMissingAuthor,
	// other generic errors).
	Err error
}

SyntaxError indicates an incorrectly formatted input to Parse.

func (SyntaxError) Error

func (e SyntaxError) Error() string

func (SyntaxError) Unwrap

func (e SyntaxError) Unwrap() error