Quick Reference
Table Formatting
Table Rows
- Table rows begin with a | character.
- Columns are separated by | characters.
- Table rows may be preceded by a prefix
- See also Continuation Lines
Horizontal Rulers
- should/will be preceeded by the same prefix as a table's rows
- must begin with either | or +
- may be padded with one or more whitespace characters
- must contain at least one - or = character
- may contain formatting hints (described below)
Formatting Hints
There are three types of hints, column alignment, sorting direction and sorting priority.
Each field of a ruler may contain any combination of those three hint types.
Column Alignment
All of the patterns in this table are longer than necessary for demonstration purposes!
Only the red characters are actually required.
See Justification for details
| Hint | Effect |
|---|---|
| --- | reset a column's alignment configuration |
| :-- | left align a column |
| --: | right align a column |
| -:- | center align a column |
| :-: | center align a column (markdown style) |
| --. | numeric align a column |
| ..- | version align a column |
Sorting
See Sorting for details
| Hint | Effect |
|---|---|
| ---^ | sort the table by this column in ascending order |
| ---v | sort the table by this column in descending order |
| ---^1 | sort the table, using this column with priority n |
The psv Command Line
The psv command parses its command line much like an english sentance, with the overall structure: command directive columns
Commands
See Commands for details
| Command | Behaviour |
|---|---|
| reformat {directive} | reformat tables from STDIN to STDOUT (default) |
| start [{service}] | Start one of psv's web services (e.g. this tour) |
| usage | Show a short summary of psv's commands |
| help | Show psv's online help |
| version | Show psv's version information |
Directives
| Directive | Behaviour |
|---|---|
| profile {profile-name} | generate tables according to the rules defined in profile {profile-name} |
| match {prefix} … | define which characters may appear before a column's first | pipe character |
| prefix {prefix} … | specify the prefix to use for any rendered tables |
| sort {column} … | sort a table's rows |
| locale {locale-tag} | use the locale {locale-tag} for sorting |
| config {column} … | alter column alignment or sorting configurations |
| put {column} … [ before/after {column} ] | move or insert columns within a table |
| delete {column} … | delete columns from a table |
| move {column} … [ before/after {column} ] | move columns within a table |
| insert {column} … [ before/after {column} ] | add new columns to a table |
| fill {column} … [ with {value} ] | fill columns with data |
| clear {column} … | clear the data in a column (fill with "") |
Column Specifiers
See Column Identification for details
| Specifier | Description |
|---|---|
| {col} | select a column by name or position (1..n) |
| :{name} | select a column by name only |
| .{pos} | select a column by position only (1..n) |
| {col}~ | reset a column's alignment and sorting configuration |
| {col}~- | reset a column's alignment configuration |
| {col}~~ | reset a column's sorting configuration |
| {col}~: | left align a column |
| {col}~-: | right align a column |
| {col}~:: | center align a column |
| {col}~. | numeric align a column |
| {col}~.. | version align a column |
| {col}~^ | sort the table by this column in ascending order |
| {col}~v | sort the table by this column in descending order |
| {col}~n | sort the table, using this column with priority n |
Go API
Tables
| Description | |
|---|---|
| psv.NewTable(...psv.Option) *psv.Table | create a new, empty table |
| table.UnmarshalText([]byte) error | import a table from a string |
| table.MarshalText() ([]byte, error) | format the table as a multi-line string |
| table.FromString(string) *psv.Table | import a table from a string |
| table.String() string | format the table as a multi-line string |
| table.AllRows() []psv.Row | get all rows from a table |
| table.DataRow() psv.Row | returns a single row of data indexed by it's position in the table (0..n-1) |
| table.DataRows() []psv.Row | returns all rows except the first row (asssumed to be column names) |
| table.AppendLine(string) | add a line of unknown type to the table (data, ruler or text) |
| table.AppendFields(...string) | add a new row of strings to a table |
| table.AppendRow([]string) | add a new row of strings to a table |
| table.AppendRows([][]string) | add multiple rows of strings to a table |
| table.AppendRuler(psv.Ruler) | add a ruler to a table |
| table.AppendText(string) | add a decorative text line to a table |
| table.LineCount() int | returns the total number of lines in a table (rows, rulers and text lines) |
| table.RowCount() int | returns the number of rows in a table, including the first row |
| table.RulerCount() int | returns the number of rulers in a table |
| table.TextlineCount() int | returns the number of decorative text lines in a table |
| row.Field(string) string | returns the string value of a named column |
| row.FieldAt(int) string | returns the string value of a column by it's postion in the table (0..n-1) |
Documents
| Description | |
|---|---|
| psv.NewDocument(...psv.Option) *psv.Document | create a new, empty document (for multiple tables) |
| document.UnmarshalText([]byte) error | create a new, empty document (for multiple tables) |
| document.MarshalText() ([]byte, error) |