gtree

package module
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2024 License: Unlicense Imports: 10 Imported by: 2

README

gtree

gtree is a Go package designed to generate family tree diagrams.

Test Status Go Report Card go.dev reference

Purpose

The gtree package is designed to help you generate genealogical diagrams in the form of family trees. It supports both ancestor and descendant chart layouts, making it easy to visualize family connections across generations. The package is ideal for developers looking to integrate family tree generation into their Go applications or for anyone interested in generating genealogical diagrams programmatically.

Capabilities

  • Generate Ancestor Charts: Visualize an individual's ancestors, with the root person on the left and each successive generation aligned vertically to the right.
  • Generate Descendant Charts: Illustrate an individual's descendants, with the root person at the top and each successive generation arranged in horizontal rows below.
  • SVG Output: Export charts as SVG (Scalable Vector Graphics) for easy integration into web pages or further editing in vector graphic editors.
  • Text-Based Parser: Easily parse textual representations of descendant lists into gtree structures, allowing you to quickly generate charts from text-based genealogical data.

Usage

Getting Started

Run the following in the directory containing your project's go.mod file:

go get github.com/iand/gtree@latest

Documentation is at https://pkg.go.dev/github.com/iand/gtree

License

This is free and unencumbered software released into the public domain. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SVG 

func SVG(lay Layout) (string, error)

SVG generates an SVG (Scalable Vector Graphics) representation of the provided layout. It takes a Layout interface as input and returns a string containing the SVG markup, or an error if the generation fails.

The SVG output includes: - The XML declaration and SVG root element with specified width and height based on the layout dimensions. - A white background covering the entire SVG canvas. - The title of the chart, if provided, rendered at the top of the SVG. - Any notes, rendered below the title, with appropriate spacing. - Blurbs representing individuals or family members, each with their associated text and optional background rectangle if debug mode is enabled. - Connectors, represented as paths, connecting blurbs according to their relationships.

The function iterates over the layout elements (title, notes, blurbs, connectors), converts their properties to SVG-compatible attributes, and appends them to an internal buffer. Finally, it returns the complete SVG as a string.

Types

type AncestorChart 

type AncestorChart struct {
	Title string
	Notes []string
	Root  *AncestorPerson
}

AncestorChart represents a horizontal ancestor chart, where the root person is positioned on the left, and successive generations extend to the right. Ancestors in each generation are aligned vertically, visually depicting the lineage from the root person to their ancestors.

func (*AncestorChart) Layout 

func (ch *AncestorChart) Layout(opts *AncestorLayoutOptions) *AncestorLayout

Layout generates the layout for the ancestor chart based on the provided options.

type AncestorLayout 

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

AncestorLayout represents the layout of an ancestor chart, including dimensions and layout options.

func (*AncestorLayout) Blurbs 

func (l *AncestorLayout) Blurbs() []*Blurb

Blurbs returns all the blurbs in the layout.

func (*AncestorLayout) Connectors 

func (l *AncestorLayout) Connectors() []*Connector

Connectors returns all the connectors in the layout.

func (*AncestorLayout) Debug 

func (l *AncestorLayout) Debug() bool

Debug reports whether the layout is in debug mode.

func (*AncestorLayout) Height 

func (l *AncestorLayout) Height() Pixel

Height returns the height of the layout.

func (*AncestorLayout) Margin 

func (l *AncestorLayout) Margin() Pixel

Margin returns the margin of the layout.

func (*AncestorLayout) Notes 

func (l *AncestorLayout) Notes() []TextElement

Notes returns the notes elements of the layout.

func (*AncestorLayout) Title 

func (l *AncestorLayout) Title() TextElement

Title returns the title element of the layout.

func (*AncestorLayout) Width 

func (l *AncestorLayout) Width() Pixel

Width returns the width of the layout.

type AncestorLayoutOptions 

type AncestorLayoutOptions struct {
	Debug bool

	LineWidth Pixel // width of any drawn lines
	Margin    Pixel // margin to add to entire drawing
	Hspace    Pixel // the horizontal space to leave between blurbs in different generations
	Vspace    Pixel // the vertical space to leave between blurbs in the same generation
	LineGap   Pixel // the distance to leave between a connecting line and any text

	HookLength Pixel // the length of the line drawn from the parent or a child to the vertical line that joins them

	TitleStyle   TextStyle // TitleStyle is the style of the font to use for the title of the chart.
	NoteStyle    TextStyle // NoteStyle is the style of the font to use for the notes of the chart.
	HeadingStyle TextStyle // HeadingStyle is the style of the font to use for the first line of each blurb.
	DetailStyle  TextStyle // DetailStyle is the style of the font to use for the subsequent lines of each blurb after the first.

	DetailWrapWidth Pixel // DetailWrapWidth is the maximum width of detail text before wrapping to a new line.
}

AncestorLayoutOptions defines various layout parameters for rendering the ancestor chart.

func DefaultAncestorLayoutOptions 

func DefaultAncestorLayoutOptions() *AncestorLayoutOptions

DefaultAncestorLayoutOptions returns the default layout options for rendering the ancestor chart.

type AncestorPerson 

type AncestorPerson struct {
	ID      int
	Details []string
	Father  *AncestorPerson
	Mother  *AncestorPerson
}

AncestorPerson represents an individual in the ancestor chart, including their ID, details, and their parents.

type Blurb 

type Blurb struct {
	ID           int
	HeadingTexts TextSection
	DetailTexts  TextSection
	Tags         []string

	// Text          []string
	CentreText          bool   // true if the text for this blurb is better presented as centred
	Width               Pixel  // Width is the horizontal extent of the Blurb
	AbsolutePositioning bool   // when true, the position of the blurb is controlled by TopPos and LeftPos, otherwise it is calculated relative to neighbours
	TopPos              Pixel  // TopPos is the absolute vertical position of the upper edge of the Blurb
	LeftPos             Pixel  // LeftPos is the absolute horizontal position of the left edge of the Blurb
	Height              Pixel  // Height is the vertical extent of the Blurb
	Col                 int    // column the blurb appears in for layouts that use columns
	Row                 int    // row the blurb appears in for layouts that use rows
	LeftPad             Pixel  // required padding to left of blurb to separate families
	NoShift             bool   // when true the left shift will not be changed
	KeepTightRight      *Blurb // the blurb to the right that this blurb should keep as close as possible to
	LeftNeighbour       *Blurb // the blurb to the left of this one, when non-nil will be used for horizontal positioning
	Parent              *Blurb
	TopHookOffset       Pixel // TopHookOffset is the offset from the left of the blurb where any dropped connecting line should finish (ensures it is within the bounds of the name, even if subsequent detail lines are longer)
	SideHookOffset      Pixel // SideHookOffset is the offset from the top of the blurb where any connecting line should finish

	FirstChild *Blurb
	LastChild  *Blurb
}

Blurb represents a visual element in the layout, typically used to display information about a person in a chart. It includes various properties to control its positioning, text content, and relationships with other blurbs.

func (*Blurb) Bottom 

func (b *Blurb) Bottom() Pixel

Bottom returns the vertical position of the lower edge of the Blurb

func (*Blurb) Left 

func (b *Blurb) Left() Pixel

Left returns the horizontal position of the leftmost edge of the Blurb

func (*Blurb) Right 

func (b *Blurb) Right() Pixel

Right returns the horizontal position of the rightmost edge of the Blurb

func (*Blurb) SideHookY 

func (b *Blurb) SideHookY() Pixel

func (*Blurb) TopHookX 

func (b *Blurb) TopHookX() Pixel

func (*Blurb) X 

func (b *Blurb) X() Pixel

X returns the horizontal position of the centre of the Blurb

func (*Blurb) Y 

func (b *Blurb) Y() Pixel

Y returns the vertical position of the centre of the Blurb

type Connector 

type Connector struct {
	Points []Point
}

Connector represents a connection between two points in the layout, typically used to draw lines between blurbs.

type DescendantChart 

type DescendantChart struct {
	Title string
	Notes []string
	Root  *DescendantPerson
}

DescendantChart represents a chart of descendants, with the earliest ancestor (root person) at the top. Each successive generation is arranged in horizontal rows, with the next generation placed directly below the previous one. This layout visually depicts the lineage, with descendants expanding downward from the root person.

func (*DescendantChart) Layout 

func (ch *DescendantChart) Layout(opts *LayoutOptions) *DescendantLayout

Layout generates the layout for the descendant chart based on the provided options.

type DescendantFamily 

type DescendantFamily struct {
	Other    *DescendantPerson
	Details  []string
	Children []*DescendantPerson
}

DescendantFamily represents a family unit, including the spouse and their children.

type DescendantLayout 

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

DescendantLayout represents the layout of a descendant chart, including dimensions and layout options.

func (*DescendantLayout) Blurbs 

func (l *DescendantLayout) Blurbs() []*Blurb

Blurbs returns all the blurbs in the layout.

func (*DescendantLayout) Connectors 

func (l *DescendantLayout) Connectors() []*Connector

Connectors returns all the connectors in the layout.

func (*DescendantLayout) Debug 

func (l *DescendantLayout) Debug() bool

Debug reports whether the layout is in debug mode.

func (*DescendantLayout) Height 

func (l *DescendantLayout) Height() Pixel

Height returns the height of the layout.

func (*DescendantLayout) Margin 

func (l *DescendantLayout) Margin() Pixel

Margin returns the margin of the layout.

func (*DescendantLayout) Notes 

func (l *DescendantLayout) Notes() []TextElement

Notes returns the notes elements of the layout.

func (*DescendantLayout) Title 

func (l *DescendantLayout) Title() TextElement

Title returns the title element of the layout.

func (*DescendantLayout) Width 

func (l *DescendantLayout) Width() Pixel

Width returns the width of the layout.

type DescendantPerson 

type DescendantPerson struct {
	ID       int
	Headings []string
	Details  []string
	Families []*DescendantFamily
	Tags     []string
}

DescendantPerson represents an individual in the descendant chart, including their ID, details, and families.

type Layout 

type Layout interface {
	Height() Pixel
	Width() Pixel
	Margin() Pixel
	Title() TextElement
	Notes() []TextElement
	Blurbs() []*Blurb
	Connectors() []*Connector
	Debug() bool
}

Layout defines an interface for chart layouts, providing methods to retrieve dimensions, text elements, and layout components such as blurbs and connectors.

type LayoutOptions 

type LayoutOptions struct {
	Debug      bool // Debug indicates whether to emit logging and debug information.
	Iterations int  // Number of iterations of adjustment to run

	Hspace     Pixel // Hspace is the horizontal spacing between blurbs within the same family.
	LineWidth  Pixel // LineWidth is the width of the lines connecting blurbs.
	Margin     Pixel // Margin is the margin added to the entire drawing.
	FamilyDrop Pixel // FamilyDrop is the length of the line drawn from parents to the children group line.
	ChildDrop  Pixel // ChildDrop is the length of the line drawn from the children group line to a child.
	LineGap    Pixel // LineGap is the distance between a connecting line and any text.

	TitleStyle   TextStyle // TitleStyle is the style of the font to use for the title of the chart.
	NoteStyle    TextStyle // NoteStyle is the style of the font to use for the notes of the chart.
	HeadingStyle TextStyle // HeadingStyle is the style of the font to use for the first line of each blurb.
	DetailStyle  TextStyle // DetailStyle is the style of the font to use for the subsequent lines of each blurb after the first.

	DetailWrapWidth Pixel // DetailWrapWidth is the maximum width of detail text before wrapping to a new line.
}

LayoutOptions defines various layout parameters for rendering the descendant chart.

func DefaultLayoutOptions 

func DefaultLayoutOptions() *LayoutOptions

DefaultLayoutOptions returns the default layout options for rendering the descendant chart.

type Parser 

type Parser struct {
	SurnameSeparateLine bool // if true the parser puts the surname on a second header line
}

A Parser parses a textual descendent list.

A descendant list is a list of person entries each consisting of a prefix followed by detail text. Each entry begins on a new line. Leading whitespace is significant (for spouse disambiguation) but trailing is not. Lines consisting only of whitespace are ignored.

The prefix of each entry denotes the relationship of the person to an earlier person. A prefix text may be a generation number followed by a dot (.) which indicates the position of the person in the family tree relative to the root ancestor. A generation number of 1 indicates the root ancestor, 2 indicates their children, and so on.

Alternatively the prefix may be the two characters 'sp' or the single character '+' which indicates that the person is the spouse of the preceding numbered person with equal or lesser indentation.

The entry text may wrap onto subsequent lines until a line with a generation number or spouse prefix is encountered.

The text after the prefix is the person's name followed by optional tags and detail text used for additional information such as birth, death, marriage, and other life events.

If the SurnameSeparateLine field is true then the name will be parsed to detect a surname, which will be placed on a seperate heading line. If the name ends in one or more words delimted by slashes '/' then these will be used as the surname, otherwise the surname will be taken to be the last whole word after a space.

All text up to the first tag delimiter or detail delimiter is to be the name of the person.

Tags may be specified by prefixing words with a hash '#'. Multiple tags may be specified. Any tags must be occur between the name and the detail text delimiter.

Detail text is delimited by parantheses '(' and ')'. All text between the parantheses is assumed to be the detail text.

Any text after the closing detail paranthesis is ignored.

The name and the detail text are trimmed to remove leading and trailing whitespace. Outer matching parantheses are removed from the detail text before trimming.

Any semicolons ';' within the detail text are treated as line breaks, resulting in multiple lines of text.

Identifiers are assigned using the line number of the person's entry. People in a family group are placed in the order the lines are read from the input.

func (*Parser) Parse 

func (p *Parser) Parse(ctx context.Context, r io.Reader) (*DescendantChart, error)

type Pixel 

type Pixel int

Pixel represents a unit of measurement used for layout dimensions, such as font sizes, margins, and positions.

type Point 

type Point struct {
	X Pixel
	Y Pixel
}

Point represents a coordinate in the layout, defined by its X (horizontal) and Y (vertical) position.

type SpreadingDescendantArranger added in v0.0.2 

type SpreadingDescendantArranger struct{}

func (*SpreadingDescendantArranger) Arrange added in v0.0.2 

func (a *SpreadingDescendantArranger) Arrange(l *DescendantLayout)

type TextElement 

type TextElement struct {
	Text  string
	Style TextStyle
}

TextElement represents a piece of text with a specified font size and line height, used in various layout elements.

type TextSection added in v0.0.2 

type TextSection struct {
	Lines []string
	Style TextStyle
}

type TextStyle 

type TextStyle struct {
	FontSize   Pixel  // FontSize is the size of the font to use for the text of each blurb.
	LineHeight Pixel  // LineHeight is the vertical distance between lines of text of the same style.
	Color      string // Color is the color of the text. The default is black #000000.
}

Source Files

View all Source files

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.