psv

README

PSV - Pipe Separated Values

psv is a tool for maintaining plaintext tables of Pipe Separated Values.

For example, this markdown table was formatted by psv:

# My top-secret recipe for perfect hard-boiled eggs:

| Step |        Description         |
| ---- | -------------------------- |
| 1    | boil water                 |
| 2    | add eggs                   |
| 3    | get distracted by the kids |
| 4    | serve 3 hours later        |

Links

• Online Tutorial & Demos
• Source
• Issues

Plaintext Tables

The PSV format used and provided by psv is similar in concept to Comma-Separated Values (CSV), Tab-Separated Values (TSV) or Delimiter-Separated Values (DSV), but with the distinction that additional spaces are used so that

• all rows have the same number of columns
• and all columns align vertically

PSV tables are deliberately human readable, while also still being machine readable.

Markdown tables are also supported. See the markdown annex for details.

Intended Use Cases

psv was created with the following use cases in mind:

• reformatting plaintext tables (e.g. in text or markdown files)
• generating tables of data from command line programs
• iterating over tables of unit test cases for data-driven testing (in golang code)
• editing data tables in cucumber's BDD scenarios

Feature Overview

psv was written to help maintain nice-looking tables of data. As a command line program it can be used to reformat existing tables (e.g. directly from your editor) by piping blocks of text through it.

Table Reformatting

The psv command line utility reads text from STDIN, reformats any PSV tables it finds, and writes the reformatted text to STDOUT.

1. Any line beginning with a | (pipe) character is considered to be table row.
   1. Every row within a table will be reformated to have the same number of fields as the longest row in the table.
   2. trailing empty fields (to the right of each table) are inserted or removed automatically, to ensure that each row has the same length.
2. any line which does not begin with a | character is treated as a table separator.
3. non-table lines are copied from STDIN to STDOUT unchanged.

Horizontal Rulers

One of the main features of psv is the way that it supports horizontal rulers.

These serve 2 purposes:

• visual separation between sections of a table
• as a holder of column formatting and sorting hints

How do I create a ruler?

The easiest possible ruler is simply a line containing only |- or | - (with a space).

These rulers simply create a line of dashes as wide as the table. The |- pattern leaves the lines unpadded, whereas | - adds a space around each column separator.

Formatting Hints

psv also supports additional formatting hints, such as left/right alignment or sorting information, to help make the resulting tables more aesthetically pleasing.

The available hints are:

Hint	Description	psv	markdown	parsing rules
:-	left aligned (default)	yes	yes	: must be the first non-whitespace character
-:	right aligned	yes	yes	: must be the last non-whitespace character
::	centered	yes	yes	a column with 2 or more :s will be centered
-:-	centered	yes	no - use ::	: must have at least one - or = on either side
.	numerically aligned	yes	no	. can be placed anywhere
..	version aligned	yes	no	a column with 2 or more .s will be sorted by version
^ + optional 0..9	sort, ascending	yes	no	^ can be placed anywhere
v + optional 0..9	sort, descending	yes	no	v can be placed anywhere

Note psv tables with sorting or numerical hints cannot be used in markdown documents, as markdown does not support the ., ^ or v hints.

Formatting hints may be placed in any of a table's horizontal rulers. - only the first ruler with hints is used to format a table - formatting hints are re-produced when re-formatting a psv table

References

• psv format specification (RFC-Style)
• CSV MIME Type -- RFC 4180
• Markdown -- John Gruber
• Markdown Tables Specification -- markdownguide.org
• Markdown Table Generator
• Multimarkdown

Background

• Video: There's no such thing as plain text -- Dylan Beattie / youtube

Copyright

Copyright 2022-2026 Stephen Riehm japh-codeberg@opensauce.de

License

psv is free software, licensed under the GNU AGPL v3 LICENSE. We encourage forking and changing the code, hacking around with it, and experimenting.

See gnu.org/licenses/why-affero-gpl for the differences between AGPL versus GPL licensing, and gnu.org/licenses/gpl-faq for FAQ's about GPL licenses, including the AGPL.

If you modify the psv source code, and run that modified code in a way that's accessible over a network, you must make your modifications to the source code available following the guidelines of the license:

If you modify this Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software.

Dependencies

Project	Purpose	License
urfave/cli	Commandline Parsing	MIT
spf13/pflag	Commandline Parsing	BSD-3-Clause
cucumber/godog	BDD Testing	MIT

Documentation

Index

• func Replace(s, old, new string) string
• func Unquote(s, quotes string) string
• func WithCommandArgs(args []string) options.Option
• func WithLocaleTag(localeTag string) options.Option
• func WithPrefix(prefix string) options.Option
• func WithPrefixPattern(pattern string) options.Option
• func WithProfile(profile *profile.Profile) options.Option
• func WithProfileName(name string) options.Option
• type Document
  • func NewDocument(opts ...options.Option) *Document
• type Option
• type Options
  • func NewOptions(opts ...options.Option) *Options
• type Profile
• type Row
• type Ruler
  • func NewRulerFromTemplate(template string) Ruler
• type Table
  • func NewTable(opts ...options.Option) *Table

Functions

func Replace

func Replace(s, old, new string) string

Replace returns a copy of the string s with all non-overlapping instances of old replaced by new.

Replace just calls strings.ReplaceAll

func Unquote

func Unquote(s, quotes string) string

Unquote returns a copy of a string with a single pair of identical characters removed from the start and end of the original string.

Purpose:

• allow data with leading or trailing whitespace to be stored in psv tables, e.g. " "
• Unquote() is intended to be used on individual data strings
• quoted strings cannot be used to prevent pipe characters from being used as column separators! i.e. "|" will not work! Use \| instead

Example:

t := psv.TableFromString(`
          | string | unicode |
          | ------ | ------- |
          | " "    | 0x20    |
          `)
for _, row := range t.DataRows() {
   s := psv.Unquote(row.Field("string"),`"`)  // remove quotes before processing
   ...
}

func WithCommandArgs

func WithCommandArgs(args []string) options.Option

any number of inline commands, e.g. sort insert wip delete bad ...

func WithLocaleTag

func WithLocaleTag(localeTag string) options.Option

see also "locale" command

func WithPrefix

func WithPrefix(prefix string) options.Option

see also "prefix" command

func WithPrefixPattern

func WithPrefixPattern(pattern string) options.Option

see also "prefix" command

func WithProfile

func WithProfile(profile *profile.Profile) options.Option

see also "profile" command

func WithProfileName

func WithProfileName(name string) options.Option

see also "profile" command

Types

type Document

type Document = document.Document // alias of internal document.Document

func NewDocument

func NewDocument(opts ...options.Option) *Document

type Option

type Option = options.Option // alias of internal options.Option - allow x := []psv.Option{...}

type Options

type Options = options.Options // alias of internal options.Options set of options (not []Option !)

func NewOptions

func NewOptions(opts ...options.Option) *Options

type Profile

type Profile = profile.Profile // alias of internal profile.Profile

type Row

type Row = row.Row[string] // an individual row of data, with Field accessors

type Ruler

type Ruler = ruler.Ruler // characters to use for horizontal lines

func NewRulerFromTemplate

func NewRulerFromTemplate(template string) Ruler

type Table

type Table = table.Table // alias of internal table.Table

func NewTable

func NewTable(opts ...options.Option) *Table