psv

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 23, 2023 License: MIT Imports: 10 Imported by: 0

README

PSV - Pipe Separated Values

(or "Data Table Parser And Generator")

Introduction

psv was initially created to help write "nice looking tables for gherkin scenarios". Don't worry if you don't know what "gherkin scenarios" means, the important bits are "nice looking" and "tables [of data in a text file]"

Now, psv is a unix command line utility and go package to help maintain and utilise data in simple, text-based tables using a variant of the Pipe Separated Values format.

In short, psv helps you "draw" tables of data in text files and/or use tabular data programmatically.

Index

Introductory examples

Creating psv Tables Textually

For example, psv can help you turn this, deliberately sloppily hacked up text (for demonstration purposes):

                  Controls
    +--+
        |key|action             |                alternative
    | - | --- |
|h|left
                      |   j|down
|k  |up
        |  l |      right ||||||||
    :  :
    |   :wq |   write & quit |      ZZ
        +----------

into this:

                  Controls
    +-----+--------------+-------------+
    | key | action       | alternative |
    | --- | ------------ | ----------- |
    | h   | left         |             |
    | j   | down         |             |
    | k   | up           |             |
    | l   | right        |             |
    :     :              :             :
    | :wq | write & quit | ZZ          |
    +----------------------------------+

with a single call to psv (in this case, the vim [^1] command: vip!psv [^2]).

The magic being that each line beginning with a | is split into cells and re-formatted so they all get the same level of indentation, that all columns line up nicely and that any superfluous or missing |'s are removed or added as needed. Additionally, the : : : line is also considered to be part of the table and is aligned appropriately. (see ruler formatting)

[^1]: You don't have to use vim! psv can be used from any editor that lets you pipe text through shell commands.

[^2]: which translates to: - v start a visual selection ... - i select everything in ... - p the current paragraph - !psv and replace the current selection with whatever psv makes of it.

Using psv Tables Programmatically

psv Tables can also help improve the readibility of test data.

Here is an example of an actual test suite (containing 14 individual unit tests) from psv's own unit testing code (sort_test.go):

func TestSingleSectionSorting(t *testing.T) {

    testTable, _ := psv.TableFromString(`
        | 0 | b | 3  | partial
        | 1 | D
        | 2 | E | 5
        | 3 | a | 4  | unequal
        | 4 | c | 20
        | 5 | C | 10 | row | lengths
        | 6 | e | 5
        | 7 | d | 7
        `)

    testCases := sortingTestCasesFromTable(`
	| name                         | sort  | columns | exp-col | exp-rows        |
	| ---------------------------- | ----- | ------- | ------- | --------------- |
	| no sort                      | false |         |         | 0 1 2 3 4 5 6 7 |
	| default sort                 |       |         |         | 0 1 2 3 4 5 6 7 |
	| sort only when asked to      | false | 2       |         | 0 1 2 3 4 5 6 7 |
	| reverse default sort         |       | ~       |         | 7 6 5 4 3 2 1 0 |
	| reverse reverse default sort |       | ~~      |         | 0 1 2 3 4 5 6 7 |
	| indexed column sort          |       | 2       |         | 3 0 4 5 7 1 6 2 |
	| indexed column sort          |       | 2       | 2       | a b c C d D e E |
	| reverse column sort          |       | ~2      |         | 2 6 1 7 5 4 0 3 |
	| third column sort            |       | 3       |         | 1 5 4 0 3 2 6 7 |
	| numeric sort                 |       | #3      |         | 1 0 3 2 6 7 5 4 |
	| reverse numeric sort         |       | ~#3     |         | 4 5 7 6 2 3 0 1 |
	| numeric reverse sort         |       | #~3     |         | 4 5 7 6 2 3 0 1 |
	| reverse reverse column sort  |       | ~ #~3   |         | 1 0 3 2 6 7 5 4 |
	| partial column sort          |       | 4 2     |         | 4 7 1 6 2 0 5 3 |
	| non-existent column sort     |       | 9       |         | 0 1 2 3 4 5 6 7 |
	`)

    runSortingTestCases(t, testTable, testCases)
}

In the example above, two tables are defined:

  • testTable is the reference table to be tested

    • it simply contains a few rows of pseudo-random data, in various forms suitable for testing some features of psv

  • testCases then defines a series of individual unit tests to be run on testTable

    • the first two rows (|name|... and |---|...) define a header for the table
      • psv infers(!) that "a single, separate row, followed by a ruler" means that the text in each cell defines the name of each respective column, for all following rows, or until another header is found.
      • this is only used for convenience and is not required in any way!
        • but it allows us to discard or rearrange columns without regard for how the table data is converted to sortingTestCase structs
        • see the sortingTestCasesFromTable function in the source code for details
    • each row after the ruler then defines a single unit-test to be run against the testTable
    • to add a new unit test, you just need to add a row to the testCases table
      • you can of course use psv to reformat the table if your column alignment gets messed up 😄
    • the sortingTestCasesFromTable() function converts the table of strings into a slice of sortingTestCase structs

  • finally, the runSortingTestCases() function sorts the testTable according to the conditions in each sortingTestCase and checks that the results match the expectations.

Detailed Description

psv reads, formats and writes simple tables of data in text files.

In doing so, psv focuses on human readibility and ease of use, rather than trying to provide a loss-less, ubiquitous, machine-readable data transfer format.

The same could be said of markdown, and indeed, psv can be used to generate github-style markdown tables that look nice in their markdown source code, and not just after they have been converted to HTML by the markdown renderer.

Another intended use case is data tables in Gherkin files, which are a central component of Behaviour Driven Development (BDD).

However, the real reason for creating psv was to be able to use text tables as the source of data for running automated tests. Hence the go package.

Main Features

  • normalisation of rows and columns, so that every row has the same number of cells
  • automatic table indentation and column alignment
  • the ability to automatically draw horizontal separation lines, called rulers
  • the ability to re-format existing tables, while leaving lines which "do not look like table rows" unchanged
  • a simple way to read data from tables into go programs via the psv go package
  • the (limited) ability to sort table data
    • without interfering with the rest of the table's formatting
  • and more ...
Not Supported

psv is not intended to replace spreadsheets etc 😄

Among a myriad of other non-features, the following are definitely not supported by psv:

  • the inclusion of | characters in a cell's data
  • multi-line cell data
  • any kind of cell merging or splitting
  • sorting of complex data formats, including:
    • date and/or timestamps (unless they are in ISO-8601 format, which sorts nicely)
    • signed numbers (+ and - signs confuse go's collators 😦)
    • floating point numbers
    • scientific notation
    • hexadecimal notation
  • ...
Design Principles
  • self contained
    • psv is a single go binary with no external dependencies
    • the psv go package is a single package, also with no external dependecies other than go's standard packages
      • exception: I do include another package of mine to provide simplified testing with meaningful success and error messages.
    • all psv actions occur locally (no network access required)
  • non-destructive
    • if psv doesn't know how to interperet a line of text, the text remains unchanged
      • only data rows (lines beginning with a |) and rulers are re-formatted, all other lines remain unchanged
  • idempotent
    • any table generated by psv can also be read be psv
    • running a formatted table through psv again must not change the table in any way
  • easy of use
    • normal use should not require any configuration or additional parameters
TODO's

  • add ability to configure the scanner

    • allow auto-indent detection
      • -I detect indent by capturing the indent before the first | encountered
    • explicitly specify ruler characters (for cli)
      • default autodetect
      • explicit rulers
        • turns off autodetection
        • allows the use of + and - as data
        • options:
          • -rh '-' horizontal ruler
          • -ro '|' outer ruler
          • -ri ':' inner ruler
          • -rc '+' corners
          • -rp 'ophi'
            • o outer vertical ruler
            • p padding character
            • h horizontal ruler (default: same as padding character)
            • i inner vertical ruler (default: same as outer ruler)

  • Replace table.Data with table.DataRows

Installation

psv consists of two components: the psv command and the psv go package.

To use the psv command, you only need the psv binary in your PATH, e.g. ~/bin/psv (see binary installation below).

If you don't want to install "a binary, downloaded from the 'net", you can download the source, (inspect it 😄), and build your own version.

Source Installation
Prerequisites
  • go 1.18 or later
  • make (optional, but recommended)
Build Steps

Clone the psv git repository and use make to build, test and install psv in your $GOBIN directory (typically $GOPATH/bin or ~/Go/bin)

git clone -o codeberg https://codeberg.org/japh/psv
cd psv
make install
psv -v
Binary Installation

Note: currently only available for darwin amd64 (64-bit Intel Macs)

  • download the latest psv.gz from https://codeberg.org/japh/psv/releases
  • verify psv.gz with gpg --verify psv.gz.asc
  • compare psv.gz's checksums against those provided with shasum -c psv.gz.sha256
  • unpack psv.gz with gunzip psv.gz
  • copy psv to any directory in your $PATH, or use it directly via ./psv
  • don't forget to check that it is executable, e.g. chmod +x psv

Now you can use the psv command...

Using The psv Package In Go Projects
Prerequisites
  • go 1.18 or later

To use psv in your go project, simply import codeberg.org/japh/psv and go mod tidy will download it, build it and make it available for your project.

See the psv package documentation for the API and code examples.

Alternatives

  • csv, tsv and delimeter-separated-values tables | wikipedia

    • generally, psv tables are just a single type of delimeter separated values format

  • ASCII Table Writer

    • go package for creating tables of almost any form
    • more traditional table.SetHeader, table.SetFooter() interface
    • more features (incl. colors)
    • does not read tables
      • no good for defining test cases etc in code

  • psv-spec

    • an attempt to standardize a CSV replacement using pipes as the delimiter
    • focuses on electronic data transfers
    • does not provide a tabular layout
    • escaping just |, \, \n and \r is nice
      • but does not allow for whitespace quoting
      • future: | " " | could be used by psv to represent a space

Copyright 2022 Stephen Riehm japh-codeberg@opensauce.de

Documentation

Overview

Package psv converts arrays of structs or maps into pretty, pipe-separated text tables, and vice-versa.

Example 

data := []map[string]string{
    {"name":"Joe", "age":"42"},
    {"name":"Freddie", "age":"41"},
    {"name":"Amy", "age":"don't ask"},
}

tbl := table.Marshal(data)
tbl.Columns = []string{"age","name"}
tbl.Indent = "    "
tbl.Decorations = []table.Decoration{
    {Line:0,Text:`The "who's-who" list of people`},
    {Line:1},
    {Line:2,Ruler:"+ -"},
    {Line:4,Ruler:"|==="},
}
fmt.Println(tbl.Encode())

Output 

The "who's-who" list of people

+ --------- + ------- +
| age       | name    |
|=====================|
| 42        | Joe     |
| 41        | Freddie |
| don't ask | Amy     |

The table data and appearance can be set up via any of the following examples: 

// convert a string into a table
tbl := table.DecodeString(string)
// all decorations are retained for re-rendering, e.g.
fmt.Println(tbl.Encode())

// convert a string into a data structure
// data returned in interface{}
table.Unmarshal(string,interface{})

// create a table from scratch (string data only)
tbl := table.NewTable()
tbl.Indent = "..."
tbl.Decorations = []*Decoration{...}
tbl.Data = [][]string{...}
fmt.Println(tbl.Encode())

// convert a data structure into a table (for rendering)
tbl := table.Marshal(interface{})
// optionally modify aspects of the table
tbl.Indent = "..."
tbl.Decorations = []*Decoration{...}
fmt.Println(tbl.Encode())

References

This package focusses on data representation, human readability and the exchange of intentions, which a computer may incidentally be able to make sense of. Mostly, each cell of a table is a simple, single string value, however, with a bit of additional work, the string values may be mapped to slices or maps of slightly more complicated (incl. custom) structures.

The lack of support for every last, complicated, nested structure is intentional.

There a large number of csv, tsv, dsv packages availble on pkg.go.dev, but they all seem to concentrate on "machine readable data exchange". Nevertheless, they served as inspiration for this package as well.

psv always *felt* like a package I should not have to write, but I was unable to find an existing program with suitable features:

- simple to use, suitable for as an editor plugin / shell pipe - align columnated data - while ignoring lines which aren't columnated

The unix tools [column] and [tbl] and go's own encoding/csv package all served as a good basis, but they all follow different goals.

Basic Concepts

Table is the central struct provided by psv. With a Table struct you can then add rows of data as well as Decorations (non-table rows to be interspersed before, between or after the data rows) and additional formatting such as indents.

Creating Tables

Reading Tables

The table parser expects an bufio.Scanner, from which it will extract all rows of data (beginning with a '|' character), while retaining enough information to re-construct the original text it was given.

For convenience, psv.TableFromString() may be used to parse in-situ tables, ideal for testing etc.

e.g. 

colors, _ := psv.TableFromString(`
                                | color | rgb | hue |
                                | ----- | --- | --- |
                                | red   | f00 | 0   |
                                | green | 0f0 | 120 |
                                | blue  | 00f | 240 |
                                `)

for _, row := range colors.DataRows()[1:] { // [1:] skips the header row
    ...
}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Decoration 

type Decoration struct {
	Line   int    // 1-based number of this line's position in the resulting table
	Indent string // only used to re-construct original indentation outside a table's bounds
	Text   string // un-indented text to be inserted into the table, may be ""
	Ruler  string // ruler specification, see Ruler type
}

Decoration specifies a single non-table text line to be positioned at a specific point in the generated table string.

func (*Decoration) Clone added in v0.1.1 

func (d *Decoration) Clone() *Decoration

type Indenter 

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

Indenter is used to track how a table was, and should be, indented.

When decoding tables, the Table's Indenter is used to automatically detect and track the indent of the first line of the table.

When encoding tables, the Table's Indenter provides the desired indentation for each table row.

In addition, the Indenter is also responsible for detecting and reconstructing a consistent 'comment style', if it was provided with a non-whitespace indent pattern.

Example 
package main

import (
	"fmt"

	"codeberg.org/japh/psv"
)

func main() {

	inputLines := []string{
		``,
		`hello`,
		`    hello`,
		`// hello`,
		`// // hello`,
		`    //    hello`,
	}

	patterns := []struct {
		pattern string
		isFinal bool
	}{
		{pattern: ""},
		{pattern: ``, isFinal: true},
		{pattern: `0`},
		{pattern: `-1`},
		{pattern: `-0`},
		{pattern: `+1`},
		{pattern: `1`},
		{pattern: `63`},
		{pattern: `64`},
		{pattern: `  `},
		{pattern: `//`},
		{pattern: ` //`},
		{pattern: ` // `},
		{pattern: `> >`},
		{pattern: ` > >`},
		{pattern: ` > > `},
	}

PATTERNS:
	for _, p := range patterns {
		for _, l := range inputLines {
			i := psv.NewIndenter()

			fmt.Printf("indent option:    %q\n", p.pattern)

			if p.pattern != "" || p.isFinal {
				err := i.SetIndent(p.pattern)
				if err != nil {
					fmt.Printf("failed to set indent: %q\n\n", err)
					continue PATTERNS
				}
			}

			fmt.Printf("indenter:         %s\n", i.String())

			found := i.FindIndent(l)
			i.FinalizeIndent()

			fmt.Printf("input line:       %q\n", l)
			fmt.Printf("detected  indent: %q\n", found)
			fmt.Printf("finalised indent: %q\n", i.Indent()+l[len(found):])
			fmt.Println()
		}
		fmt.Println("----")
	}

}

Output:

indent option:    ""
indenter:         "" (default)
input line:       ""
detected  indent: ""
finalised indent: ""

indent option:    ""
indenter:         "" (default)
input line:       "hello"
detected  indent: ""
finalised indent: "hello"

indent option:    ""
indenter:         "" (default)
input line:       "    hello"
detected  indent: "    "
finalised indent: "    hello"

indent option:    ""
indenter:         "" (default)
input line:       "// hello"
detected  indent: ""
finalised indent: "// hello"

indent option:    ""
indenter:         "" (default)
input line:       "// // hello"
detected  indent: ""
finalised indent: "// // hello"

indent option:    ""
indenter:         "" (default)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: "    //    hello"

----
indent option:    ""
indenter:         "" (finalised)
input line:       ""
detected  indent: ""
finalised indent: ""

indent option:    ""
indenter:         "" (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: "hello"

indent option:    ""
indenter:         "" (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: "hello"

indent option:    ""
indenter:         "" (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: "// hello"

indent option:    ""
indenter:         "" (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: "// // hello"

indent option:    ""
indenter:         "" (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: "//    hello"

----
indent option:    "0"
indenter:         "" (finalised)
input line:       ""
detected  indent: ""
finalised indent: ""

indent option:    "0"
indenter:         "" (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: "hello"

indent option:    "0"
indenter:         "" (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: "hello"

indent option:    "0"
indenter:         "" (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: "// hello"

indent option:    "0"
indenter:         "" (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: "// // hello"

indent option:    "0"
indenter:         "" (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: "//    hello"

----
indent option:    "-1"
failed to set indent: "indent must be an unsigned integer <64 or non-numeric string"

indent option:    "-0"
failed to set indent: "indent must be an unsigned integer <64 or non-numeric string"

indent option:    "+1"
failed to set indent: "indent must be an unsigned integer <64 or non-numeric string"

indent option:    "1"
indenter:         " " (finalised)
input line:       ""
detected  indent: ""
finalised indent: " "

indent option:    "1"
indenter:         " " (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: " hello"

indent option:    "1"
indenter:         " " (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: " hello"

indent option:    "1"
indenter:         " " (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: " // hello"

indent option:    "1"
indenter:         " " (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: " // // hello"

indent option:    "1"
indenter:         " " (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: " //    hello"

----
indent option:    "63"
indenter:         "                                                               " (finalised)
input line:       ""
detected  indent: ""
finalised indent: "                                                               "

indent option:    "63"
indenter:         "                                                               " (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: "                                                               hello"

indent option:    "63"
indenter:         "                                                               " (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: "                                                               hello"

indent option:    "63"
indenter:         "                                                               " (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: "                                                               // hello"

indent option:    "63"
indenter:         "                                                               " (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: "                                                               // // hello"

indent option:    "63"
indenter:         "                                                               " (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: "                                                               //    hello"

----
indent option:    "64"
failed to set indent: "indent must be an unsigned integer <64 or non-numeric string"

indent option:    "  "
indenter:         "  " (finalised)
input line:       ""
detected  indent: ""
finalised indent: "  "

indent option:    "  "
indenter:         "  " (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: "  hello"

indent option:    "  "
indenter:         "  " (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: "  hello"

indent option:    "  "
indenter:         "  " (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: "  // hello"

indent option:    "  "
indenter:         "  " (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: "  // // hello"

indent option:    "  "
indenter:         "  " (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: "  //    hello"

----
indent option:    "//"
indenter:         "//" (default)
input line:       ""
detected  indent: ""
finalised indent: "// "

indent option:    "//"
indenter:         "//" (default)
input line:       "hello"
detected  indent: ""
finalised indent: "// hello"

indent option:    "//"
indenter:         "//" (default)
input line:       "    hello"
detected  indent: "    "
finalised indent: "//    hello"

indent option:    "//"
indenter:         "//" (default)
input line:       "// hello"
detected  indent: "// "
finalised indent: "// hello"

indent option:    "//"
indenter:         "//" (default)
input line:       "// // hello"
detected  indent: "// // "
finalised indent: "// // hello"

indent option:    "//"
indenter:         "//" (default)
input line:       "    //    hello"
detected  indent: "    //    "
finalised indent: "    //    hello"

----
indent option:    " //"
indenter:         " //" (finalised)
input line:       ""
detected  indent: ""
finalised indent: " //"

indent option:    " //"
indenter:         " //" (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: " //hello"

indent option:    " //"
indenter:         " //" (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: " //hello"

indent option:    " //"
indenter:         " //" (finalised)
input line:       "// hello"
detected  indent: "// "
finalised indent: " //hello"

indent option:    " //"
indenter:         " //" (finalised)
input line:       "// // hello"
detected  indent: "// // "
finalised indent: " //hello"

indent option:    " //"
indenter:         " //" (finalised)
input line:       "    //    hello"
detected  indent: "    //    "
finalised indent: " //hello"

----
indent option:    " // "
indenter:         " // " (finalised)
input line:       ""
detected  indent: ""
finalised indent: " // "

indent option:    " // "
indenter:         " // " (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: " // hello"

indent option:    " // "
indenter:         " // " (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: " // hello"

indent option:    " // "
indenter:         " // " (finalised)
input line:       "// hello"
detected  indent: "// "
finalised indent: " // hello"

indent option:    " // "
indenter:         " // " (finalised)
input line:       "// // hello"
detected  indent: "// // "
finalised indent: " // hello"

indent option:    " // "
indenter:         " // " (finalised)
input line:       "    //    hello"
detected  indent: "    //    "
finalised indent: " // hello"

----
indent option:    "> >"
indenter:         "> >" (default)
input line:       ""
detected  indent: ""
finalised indent: "> > "

indent option:    "> >"
indenter:         "> >" (default)
input line:       "hello"
detected  indent: ""
finalised indent: "> > hello"

indent option:    "> >"
indenter:         "> >" (default)
input line:       "    hello"
detected  indent: "    "
finalised indent: "> >    hello"

indent option:    "> >"
indenter:         "> >" (default)
input line:       "// hello"
detected  indent: ""
finalised indent: "> > // hello"

indent option:    "> >"
indenter:         "> >" (default)
input line:       "// // hello"
detected  indent: ""
finalised indent: "> > // // hello"

indent option:    "> >"
indenter:         "> >" (default)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: "> >    //    hello"

----
indent option:    " > >"
indenter:         " > >" (finalised)
input line:       ""
detected  indent: ""
finalised indent: " > >"

indent option:    " > >"
indenter:         " > >" (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: " > >hello"

indent option:    " > >"
indenter:         " > >" (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: " > >hello"

indent option:    " > >"
indenter:         " > >" (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: " > >// hello"

indent option:    " > >"
indenter:         " > >" (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: " > >// // hello"

indent option:    " > >"
indenter:         " > >" (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: " > >//    hello"

----
indent option:    " > > "
indenter:         " > > " (finalised)
input line:       ""
detected  indent: ""
finalised indent: " > > "

indent option:    " > > "
indenter:         " > > " (finalised)
input line:       "hello"
detected  indent: ""
finalised indent: " > > hello"

indent option:    " > > "
indenter:         " > > " (finalised)
input line:       "    hello"
detected  indent: "    "
finalised indent: " > > hello"

indent option:    " > > "
indenter:         " > > " (finalised)
input line:       "// hello"
detected  indent: ""
finalised indent: " > > // hello"

indent option:    " > > "
indenter:         " > > " (finalised)
input line:       "// // hello"
detected  indent: ""
finalised indent: " > > // // hello"

indent option:    " > > "
indenter:         " > > " (finalised)
input line:       "    //    hello"
detected  indent: "    "
finalised indent: " > > //    hello"

----

func NewIndenter 

func NewIndenter() *Indenter

NewIndenter creates a new Indenter

func (*Indenter) Clone added in v0.1.1 

func (i *Indenter) Clone() *Indenter

func (*Indenter) FinalizeIndent 

func (i *Indenter) FinalizeIndent()

FinalizeIndent is called while decoding, to indicate that the first table row has been detected.

The most recently detected indent will then be retained and used for table row encoding.

func (*Indenter) FindIndent 

func (i *Indenter) FindIndent(text string) string

FindIndent checks if the beginning of a line of text matches the current indent pattern and returns the indent string.

The returned string is used to then split the line into <indent> and <text>, and may be used to re-construct the original line if it lies before or after the table's rows

func (*Indenter) Indent 

func (i *Indenter) Indent() string

Indent returns the indent to be used when encoding a table row

func (*Indenter) Prefix 

func (i *Indenter) Prefix() string

Prefix returns the non-whitespace part of the indent pattern provided

func (*Indenter) SetIndent 

func (i *Indenter) SetIndent(pattern string) error

SetIndent explicitly sets a desired indent to use.

If SetIndent has been called, the Indenter will match indents according to the provided pattern, and will re-create indents using the provided pattern.

Special situations:

  • the pattern is just whitesspace (including "")

  • leading whitespace will be removed when decoding

  • the indent string will be used, as provided, when encoding

  • the pattern provided is just a number `n`

  • leading whitespace will be removed when decoding

  • the encoding indent will be `n` of spaces

  • the pattern contains non-whitespace characters

  • any instances of the non-whitespace pattern will be skipped at the beginning of each line

  • if the pattern has no leading or trailing whitespace

  • the skipped indent from the first table row will be re-used to indent all table rows

  • if the pattern has a leading whitespace

  • the indent string will be used as provided

  • the whitespace padding between the indent and the start of text will be retained from the first table row

  • if the pattern has a trailing whitespace

  • only the whitespace before the first non-whitespace character found will be re-used for indenting table rows

  • the indent string will then be used as provided

  • if the pattern has leading and trailing whitespace

  • then the indent will be used, unmodified, for each table row

Example (Remove_indents) 
package main

import (
	"codeberg.org/japh/psv"
)

func main() {

	testCases := []string{
		"",  // explicitly request an empty-string indent
		"0", // explicitly set the indent width to 0
	}

	for _, testIndent := range testCases {
		tbl := psv.NewTable()
		tbl.SetIndent(testIndent)
		tbl.DecodeString(``)
	}

}

Output:

func (*Indenter) String 

func (i *Indenter) String() string

String is only used for 'nice output' while debugging

type Options 

type Options struct {
	IndentPattern string   // user-provided indent to use
	IndentIsFinal bool     // flag to force the use of Options.Indent (required to force the use of "")
	Squash        bool     // squash multiple blank lines into a single blank line when encoding
	Sort          bool     // sort data rows, see also: SortColumns and SortSections
	SortLanguage  string   // the BCP 47 locale to use for collation rules
	SortColumns   []string // list of column names or numbers to use for sorting
	SortSections  []string // list of section names or numbers to use for sorting
}

Options is used by Table to store user specified configuration settings

type Ruler 

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

Ruler represents a horizontal separator to be placed within a table.

Rulers only contain the characters |, :, *, +, - and optional spaces.

When a table is rendered, rulers are generated to fit the column widths of the table.

If the input string contains 4 runes or less, it is interpreted as a format: 

e.g.   '| -:'
        |||+--  internal column separator
        ||+---  horizonal line
        |+----  padding
        +-----  outer border

If the input string is more than 4 runes, it is assumed to be a previously-generated ruler, and is analysed to determine the format.

If the format of a ruler cannot be determined, the 'border' rune will be 0 and the original input is used. (non-destructive failure)

func NewRuler 

func NewRuler(input string) (*Ruler, error)

NewRuler creates a new ruler based on a format or previously rendered ruler. Note: a returned error is really only a warning! The returned *Ruler is still valid and usable!

func (*Ruler) Encode 

func (r *Ruler) Encode(widths []int) string

Encode generates a string using the ruler's format to match the column widths provided in 'widths'

Example 
columnWidths := []int{1, 2, 3, 4}
ruler, _ := NewRuler("| -:")

fmt.Println(ruler.Encode(columnWidths))

Output:

| - : -- : --- : ---- |

type Scanner 

type Scanner interface {
	Scan() bool
	Text() string
}

Scanner is the interface required to read an input source, 1 line at a time. Subset of bufio.Scanner

type Section added in v0.1.1 

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

func (*Section) ColumnNames added in v0.1.1 

func (s *Section) ColumnNames() []string

func (*Section) Name added in v0.1.1 

func (s *Section) Name() string

func (*Section) RowCount added in v0.1.1 

func (s *Section) RowCount() int

func (*Section) RowSpan added in v0.1.1 

func (s *Section) RowSpan() (int, int)

type Sorter added in v0.1.1 

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

func (*Sorter) ByColumns added in v0.1.1 

func (s *Sorter) ByColumns(names []string) error

func (*Sorter) InSections added in v0.1.1 

func (s *Sorter) InSections(names []string) error

func (*Sorter) Language added in v0.1.1 

func (s *Sorter) Language(bcp47Tag string)

func (*Sorter) Sort added in v0.1.1 

func (s *Sorter) Sort() error

type Table 

type Table struct {
	Options                   // configuration options
	Data        [][]string    // 2-Dimensional array of string cells indexed by [row][column]
	Decorations []*Decoration // an array of decorations to add to the table

	*Indenter // indent matcher and producer
	// contains filtered or unexported fields
}

Table is a structure used to encapsulate a table of string data, which can be re-rendered with correct indentation and column alignment. The exported fields of Table may be used to customize the rendered result.

func New added in v0.1.1 

func New() *Table

New creates a new, empty table. Use its public fields to setup the data to be printed.

See also: encode_test.go

func NewTable deprecated 

func NewTable() *Table

NewTable creates a new, empty table. Use its public fields to setup the data to be printed.

See also: encode_test.go

Deprecated: prefer psv.New()

func TableFromString added in v0.1.0 

func TableFromString(input string) (*Table, error)

TableFromString Creates a new table from a string containing a psv table. This is the recommended way to read in-situ tables. e.g. 

tbl, err := psv.FromString(`
                           | 1 | one |
                           | 2 | two |
                           :         :
                           `)

func (*Table) AnalyseData 

func (tbl *Table) AnalyseData() (rows, cols int, width []int)

AnalyseData was only created for testing (to allow access to the internal workings of encode()).

Never call this - it provides nothing of use.

func (*Table) AppendDataRow added in v0.1.1 

func (tbl *Table) AppendDataRow(row []string)

AppendDataRow adds a single row of data to the end of the table A row is just a []string Rows do not have to have a specific number of columns, all rows are normalised to a consistent width before encoding

func (*Table) AppendRuler added in v0.1.1 

func (tbl *Table) AppendRuler(ruler string)

AppendRuler add a ruler decoration line to the end of the table.

Rulers are specified by an up-to 4 character string, with 1 character each for the outer borders, column padding, horizonal lines and internal column separator.

e.g.: 

//               ,-----  outer border
//               |,----  padding
//               ||,---  horizonal line
//               |||,--  internal column separator
//               ||||
tbl.AppendRuler("| -:")

func (*Table) AppendText added in v0.1.1 

func (tbl *Table) AppendText(textLines ...string)

AppendText adds any number of text decoration lines to the end of the table.

func (*Table) Clone added in v0.1.1 

func (tbl *Table) Clone() *Table

Clone provides a deep-copy of an existing Table

func (*Table) ColumnNames added in v0.1.1 

func (tbl *Table) ColumnNames() []string

func (*Table) DataRows added in v0.1.1 

func (tbl *Table) DataRows() [][]string

DataRows returns the [][]string of data in the table. The rows returned are guaranteed to all have the same number of columns 

tbl := psv.TableFromString(...).DataRows()
	for _, row := range tbl {
		for _, cell := range row {
			...
		}
	}
}

func (*Table) DecodeString added in v0.1.0 

func (tbl *Table) DecodeString(input string) error

DecodeString extracts data from a block of text containing a PSV table

func (*Table) Encode 

func (tbl *Table) Encode() string

Encode formats a Table struct into a multi-line string

Table.Data is converted into a formatted table Table.Decorations are interspersed and indented according to the formatting rules.

Example (Encoding_decorations) 
package main

import (
	"fmt"

	"codeberg.org/japh/psv"
)

func main() {

	tbl := psv.NewTable()

	tbl.SetIndent("....")
	tbl.Decorations = []*psv.Decoration{
		// column headers
		{Line: 2, Ruler: "+ ="},
		{Line: 3},
		{Line: 4, Text: "Empty rows are kept"},
		{Line: 5, Text: "Decorations appear between rows"},
		{Line: 7},
		{Line: 7, Text: "# Comments are always good"},
		{Line: 7, Text: "# repeating line numbers is not good, but works"},
		// data...
		{Line: 12},
		{Line: 12, Text: "leading and trailing spaces need extra quotes"},
		{Line: 15},
		{Line: 15, Text: "Rulers can be placed anywhere"},
		{Line: 15, Ruler: "+ -"},
		{Line: 20, Text: "and trailing text lines are no problem either"},
	}
	tbl.Data = [][]string{
		{"one", "foo", "two", "three"}, // first row are headers only
		{},                             // empty row
		{"the first", "", "the second", "the third"}, // full row
		{"more data"},                             // partial row
		{`" "`, `" x "`, `'"'`, `" x"`},           // handling of leading and trailing spaces
		{"lorem", "", "ipsum", "upsum", "oopsum"}, // extra column!
	}

	fmt.Print(tbl.Encode())

}

Output:


....| one       | foo   | two        | three     |        |
....+ ========= + ===== + ========== + ========= + ====== +

....Empty rows are kept
....Decorations appear between rows
....|           |       |            |           |        |

....# Comments are always good
....# repeating line numbers is not good, but works
....| the first |       | the second | the third |        |
....| more data |       |            |           |        |

....leading and trailing spaces need extra quotes
....| " "       | " x " | '"'        | " x"      |        |

....Rulers can be placed anywhere
....+ --------- + ----- + ---------- + --------- + ------ +
....| lorem     |       | ipsum      | upsum     | oopsum |

and trailing text lines are no problem either

func (*Table) NewSorter added in v0.1.1 

func (tbl *Table) NewSorter() *Sorter

func (*Table) Read 

func (t *Table) Read(in Scanner) error

Read reads and decodes text lines from a Scanner which provides individual lines from some text source.

func (*Table) Sections added in v0.1.1 

func (tbl *Table) Sections() []*Section

func (*Table) Sort added in v0.1.1 

func (tbl *Table) Sort()

func (*Table) Write 

func (tbl *Table) Write(b Writer)

Encode converts the 2-Dimensional slice of string data in the table into a pretty, pipe-separated table as a single, printable string.

type Writer 

type Writer interface {
	WriteString(string) (int, error) // e.g. bytes.Builder or strings.Builder
}

Writer interface used to produce new PSV tables. Warning: WriteString will be called many times per line.

Notes

Bugs

  • 2022-02-14 it should be possible to just use a slice over the underlying []byte array instead of having to peice the indent and text of a decoration line back together

Source Files

View all Source files

Directories

Path Synopsis

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.