psv's go module and API

Installation

go get codeberg.org/japh/psv@latest

Reading PSV Data

The steps for reading a PSV table are:

configure a psv.Options, for example:
- define the PrefixMatcher for the table
create a psv.Document
- a psv.Document can hold multiple tables, whereas a cannot!
configure the document via


type PSV interface      {
                        NewDocument() Document
                        NewTable() Table
                        NewLayout() Layout
                        Unquote(str, quotes string) string
                        Replace(str, old, new string) string
                        }

type Layout interface   {
                        WithPrefixMatcher(string) option
                        WithPrefix(string) option
                        WithCommandArgs([]string) option
                        WithStyle(string) option
                        WithLocaleTag(string) option
                        }

type Document interface {
                        UnmarshalText([]byte) error
                        FromString(string)
                        Tables() []Table
                        }

type Table interface    {
                        UnmarshalText([]byte) error
                        FromString(string)
                        ColumnNames() []string
                        AllRows() Row
                        DataRows() Row
                        }

type Row interface      {
                        Field(string) string
                        FieldAt(int) string
                        }

Example: Reading Data from a PSV Table


package main

import (
	"fmt"

	"codeberg.org/japh/psv"
)

func main() {
	text := []byte(`
                    | color | rgb  |
                    | ----- | ---- |
                    | red   | #f00 |
                    | green | #0f0 |
                    | blue  | #00f |
                    `)

	// create an empty document (may contain multiple tables)
	doc := psv.NewDocument()

	// parse a psv file
	doc.UnmarshalText(text)

	// access the data within the table
	for _, tbl := range doc.Tables {

		fmt.Printf("Table with columns: %q\n", tbl.ColumnNames())

		for _, row := range tbl.DataRows() {

			// columns can be accessed by name or position (index)
			fmt.Printf("RGB: %q => %q\n",
				row.Field("rgb"), // access the "rgb" value in this row
				row.FieldAt(0),   // access the 1st field in this row
			)
		}
	}

	// Output:
	// Table with columns: ["color" "rgb"]
	// RGB: "#f00" => "red"
	// RGB: "#0f0" => "green"
	// RGB: "#00f" => "blue"
}

Generating PSV Tables


type PSV interface      {
                        NewDocument() Document
                        NewTable() Table
                        NewLayout() Layout
                        }

type Layout interface   {
                        WithPrefixPattern(string) option
                        WithCommandArgs([]string) option
                        WithStyle(string) option
                        WithLocaleTag(string) option
                        }

type Table interface    {
                        FromString(string)
                        String() string
                        UnmarshalText([]byte) error
                        MarshalText() ([]byte, error)
                        InitPrefix(p string)
                        InitFlags(f []column.Flags)
                        AppendFields(f ...string)
                        AppendRow(r []string)
                        AppendRows(r [][]string)
                        AppendRuler(r ruler.Ruler)
                        AppendText(t string)
                        }

type Document interface {
                        -- all of Table's methods --
                        }

Example: Generating a PSV Table from Data


package main

import (
	"fmt"

	"codeberg.org/japh/psv"
)

func main() {
	data := [][]string{
		{"red", "#f00"},
		{"green", "#0f0"},
		{"blue", "#00f"},
	}

	// create a table (or a document, for multiple tables)
	tbl := psv.NewTable()

	// add a title and blank line
	tbl.AppendText("My favourite colors:")
	tbl.AppendText("")

	// column names are just "the first row of data"
	tbl.AppendFields("color", "rgb")

	// add a custom ruler after the first line of data
	tbl.AppendRuler(psv.NewRulerFromTemplate("| ="))

	// add our data
	tbl.AppendRows(data)

	// generate the table
	fmt.Println(tbl.String())

	// Output:
	// My favourite colors:
	//
	// | color | rgb  |
	// | ===== | ==== |
	// | red   | #f00 |
	// | green | #0f0 |
	// | blue  | #00f |
}