From 60f040d280ac2993fdf5d16e37bfdf734d5fc4aa Mon Sep 17 00:00:00 2001 From: Rick Porter Date: Tue, 10 Nov 2026 05:44:05 -0500 Subject: [PATCH] Add javadocs for public classes/methods --- .../prettytable/BuilderConfig.java | 243 ++++++++++++++++++ .../prettytable/HorizontalAlign.java | 13 + .../rickwporter/prettytable/OutputFormat.java | 14 + .../rickwporter/prettytable/PrettyObject.java | 25 ++ .../rickwporter/prettytable/PrettyTable.java | 214 ++++++++++++++- .../rickwporter/prettytable/TableBuilder.java | 39 +++ .../rickwporter/prettytable/TableGlyphs.java | 33 +++ .../prettytable/TableRenderInterface.java | 12 + 8 files changed, 592 insertions(+), 1 deletion(-) diff --git a/src/main/java/rickwporter/prettytable/BuilderConfig.java b/src/main/java/rickwporter/prettytable/BuilderConfig.java index c4dc6e6..50ced50 100644 --- a/src/main/java/rickwporter/prettytable/BuilderConfig.java +++ b/src/main/java/rickwporter/prettytable/BuilderConfig.java @@ -5,6 +5,11 @@ import java.util.List; import java.util.Objects; +/** + * Labels, truncation limits, and column selection for {@link TableBuilder} and {@link PrettyObject}. + * Each setter returns this config so calls can be chained. String setters reject {@code null}. + * List setters store a copy of the given list. + */ public final class BuilderConfig { static final int DEFAULT_KEY_MAX_LEN = 35; static final int DEFAULT_VALUE_MAX_LEN = 50; @@ -30,172 +35,410 @@ public final class BuilderConfig { private OutputFormat format = OutputFormat.RICH; private List columns = null; + /** + * Creates a config with the default labels, limits, and format. + */ + public BuilderConfig() { + } + + /** + * Returns the header for a list of strings, numbers, or booleans. + * + * @return the header, {@code Items} by default + */ public String getItemsLabel() { return this.itemsLabel; } + /** + * Sets the header for a list of strings, numbers, or booleans. + * + * @param label column header + * @return this config + * @throws NullPointerException if {@code label} is null + */ public BuilderConfig setItemsLabel(String label) { this.itemsLabel = Objects.requireNonNull(label); return this; } + /** + * Returns the left header of a map table. + * + * @return the header, {@code Property} by default + */ public String getPropertyLabel() { return this.propertyLabel; } + /** + * Sets the left header of a map table. + * + * @param label column header + * @return this config + * @throws NullPointerException if {@code label} is null + */ public BuilderConfig setPropertyLabel(String label) { this.propertyLabel = Objects.requireNonNull(label); return this; } + /** + * Returns the header used for the remaining fields of a named list item. + * + * @return the header, {@code Properties} by default + */ public String getPropertiesLabel() { return this.propertiesLabel; } + /** + * Sets the header used for the remaining fields of a named list item. + * + * @param label column header + * @return this config + * @throws NullPointerException if {@code label} is null + */ public BuilderConfig setPropertiesLabel(String label) { this.propertiesLabel = Objects.requireNonNull(label); return this; } + /** + * Returns the right header of a map table. + * + * @return the header, {@code Value} by default + */ public String getValueLabel() { return this.valueLabel; } + /** + * Sets the right header of a map table. + * + * @param label column header + * @return this config + * @throws NullPointerException if {@code label} is null + */ public BuilderConfig setValueLabel(String label) { this.valueLabel = Objects.requireNonNull(label); return this; } + /** + * Returns the header used when list items have no name field. + * + * @return the header, {@code Values} by default + */ public String getValuesLabel() { return this.valuesLabel; } + /** + * Sets the header used when list items have no name field. + * + * @param label column header + * @return this config + * @throws NullPointerException if {@code label} is null + */ public BuilderConfig setValuesLabel(String label) { this.valuesLabel = Objects.requireNonNull(label); return this; } + /** + * Returns the text used when a later row has no name field. + * + * @return the label, {@code Unknown} by default + */ public String getUnknownLabel() { return this.unknownLabel; } + /** + * Sets the text used when a later row has no name field. + * + * @param label replacement text + * @return this config + * @throws NullPointerException if {@code label} is null + */ public BuilderConfig setUnknownLabel(String label) { this.unknownLabel = Objects.requireNonNull(label); return this; } + /** + * Returns the text used for a null value. + * + * @return the text, {@code None} by default + */ public String getNullValue() { return this.nullValue; } + /** + * Sets the text used for a null value. + * + * @param text replacement text + * @return this config + * @throws NullPointerException if {@code text} is null + */ public BuilderConfig setNullValue(String text) { this.nullValue = Objects.requireNonNull(text); return this; } + /** + * Returns the text used for {@code true}. + * + * @return the text, {@code True} by default + */ public String getTrueValue() { return this.trueValue; } + /** + * Sets the text used for {@code true}. + * + * @param text replacement text + * @return this config + * @throws NullPointerException if {@code text} is null + */ public BuilderConfig setTrueValue(String text) { this.trueValue = Objects.requireNonNull(text); return this; } + /** + * Returns the text used for {@code false}. + * + * @return the text, {@code False} by default + */ public String getFalseValue() { return this.falseValue; } + /** + * Sets the text used for {@code false}. + * + * @param text replacement text + * @return this config + * @throws NullPointerException if {@code text} is null + */ public BuilderConfig setFalseValue(String text) { this.falseValue = Objects.requireNonNull(text); return this; } + /** + * Returns the caption template for a list table. + * {}, {@code %d}, and {@code %s} are replaced with the item count. + * + * @return the template, Found {} items by default + */ public String getItemsCaption() { return this.itemsCaption; } + /** + * Sets the caption template for a list table. + * {}, {@code %d}, and {@code %s} are replaced with the item count. A template with + * none of those markers is printed unchanged. + * + * @param template caption template + * @return this config + * @throws NullPointerException if {@code template} is null + */ public BuilderConfig setItemsCaption(String template) { this.itemsCaption = Objects.requireNonNull(template); return this; } + /** + * Returns the marker appended when a key, value, or URL is cut off. + * + * @return the marker, {@code ...} by default + */ public String getEllipsis() { return this.ellipsis; } + /** + * Sets the marker appended when a key, value, or URL is cut off. + * + * @param marker truncation marker + * @return this config + * @throws NullPointerException if {@code marker} is null + */ public BuilderConfig setEllipsis(String marker) { this.ellipsis = Objects.requireNonNull(marker); return this; } + /** + * Returns the header used for a {@code *} column. + * + * @return the header, {@code Properties} by default + */ public String getWildcardHeader() { return this.wildcardHeader; } + /** + * Sets the header used for a {@code *} column. + * + * @param header column header + * @return this config + * @throws NullPointerException if {@code header} is null + */ public BuilderConfig setWildcardHeader(String header) { this.wildcardHeader = Objects.requireNonNull(header); return this; } + /** + * Returns the prefixes that mark a value as a URL. + * URL values use {@link #getUrlMaxLen()} instead of {@link #getValueMaxLen()}. + * + * @return the prefixes, {@code http://}, {@code https://}, and {@code ftp://} by default + */ public List getUrlPrefixes() { return this.urlPrefixes; } + /** + * Sets the prefixes that mark a value as a URL. + * + * @param prefixes prefixes to match at the start of a value + * @return this config + * @throws NullPointerException if {@code prefixes} is null + */ public BuilderConfig setUrlPrefixes(List prefixes) { this.urlPrefixes = new ArrayList(Objects.requireNonNull(prefixes)); return this; } + /** + * Returns the maximum length of a URL value before the ellipsis is appended. + * + * @return the maximum length, {@code 100} by default + */ public int getUrlMaxLen() { return this.urlMaxLen; } + /** + * Sets the maximum length of a URL value before the ellipsis is appended. + * + * @param maxLen maximum length in characters + * @return this config + */ public BuilderConfig setUrlMaxLen(int maxLen) { this.urlMaxLen = maxLen; return this; } + /** + * Returns the fields tried, in order, as the row name of a list of maps. + * + * @return the field names, {@code name} then {@code id} by default + */ public List getKeyFields() { return this.keyFields; } + /** + * Sets the fields tried, in order, as the row name of a list of maps. + * + * @param fields field names, most preferred first + * @return this config + * @throws NullPointerException if {@code fields} is null + */ public BuilderConfig setKeyFields(List fields) { this.keyFields = new ArrayList(Objects.requireNonNull(fields)); return this; } + /** + * Returns the maximum length of a key before the ellipsis is appended. + * + * @return the maximum length, {@code 35} by default + */ public int getKeyMaxLen() { return this.keyMaxLen; } + /** + * Sets the maximum length of a key before the ellipsis is appended. + * + * @param maxLen maximum length in characters + * @return this config + */ public BuilderConfig setKeyMaxLen(int maxLen) { this.keyMaxLen = maxLen; return this; } + /** + * Returns the maximum length of a non-URL value before the ellipsis is appended. + * + * @return the maximum length, {@code 50} by default + */ public int getValueMaxLen() { return this.valueMaxLen; } + /** + * Sets the maximum length of a non-URL value before the ellipsis is appended. + * + * @param maxLen maximum length in characters + * @return this config + */ public BuilderConfig setValueMaxLen(int maxLen) { this.valueMaxLen = maxLen; return this; } + /** + * Returns the format stored on tables this config builds. + * + * @return the format, {@link OutputFormat#RICH} by default + */ public OutputFormat getFormat() { return this.format; } + /** + * Sets the format stored on tables this config builds. + * + * @param outputFormat output format + * @return this config + * @throws NullPointerException if {@code outputFormat} is null + */ public BuilderConfig setFormat(OutputFormat outputFormat) { this.format = Objects.requireNonNull(outputFormat); return this; } + /** + * Returns the columns selected for a list of maps. + * A {@code null} or empty selection leaves the default list layout in place. + * + * @return the column names, or {@code null} when none are selected + */ public List getColumns() { return this.columns; } + /** + * Selects columns for a list of maps. + * A {@code *} entry collects every field that is not named in {@code columnNames}, under + * {@link #getWildcardHeader()}. {@code null} or an empty list leaves the default list layout + * in place. Column selection does not apply to a map. + * + * @param columnNames column names in display order, or {@code null} + * @return this config + */ public BuilderConfig setColumns(List columnNames) { if (columnNames == null) { this.columns = null; diff --git a/src/main/java/rickwporter/prettytable/HorizontalAlign.java b/src/main/java/rickwporter/prettytable/HorizontalAlign.java index 4cfbdab..5f78505 100644 --- a/src/main/java/rickwporter/prettytable/HorizontalAlign.java +++ b/src/main/java/rickwporter/prettytable/HorizontalAlign.java @@ -1,8 +1,16 @@ package rickwporter.prettytable; +/** + * Horizontal placement of cell text in text, rich, and HTML output. + */ public enum HorizontalAlign { + /** Centers the cell text. The HTML style is {@code text-align:center}. */ CENTER("text-align:center"), + + /** Aligns the cell text to the left. The HTML style is {@code text-align:left}. */ LEFT("text-align:left"), + + /** Aligns the cell text to the right. The HTML style is {@code text-align:right}. */ RIGHT("text-align:right"); private final String htmlStyle; @@ -11,6 +19,11 @@ public enum HorizontalAlign { this.htmlStyle = html; } + /** + * Returns the CSS declaration written onto HTML header and body cells. + * + * @return a style such as {@code text-align:left} + */ public String getHtmlStyle() { return this.htmlStyle; } diff --git a/src/main/java/rickwporter/prettytable/OutputFormat.java b/src/main/java/rickwporter/prettytable/OutputFormat.java index 15dc2be..a86b9fc 100644 --- a/src/main/java/rickwporter/prettytable/OutputFormat.java +++ b/src/main/java/rickwporter/prettytable/OutputFormat.java @@ -1,10 +1,24 @@ package rickwporter.prettytable; +/** + * Output produced by {@link PrettyTable} and {@link PrettyObject}. + */ public enum OutputFormat { + /** ASCII rules and vertical bars. */ TEXT, + + /** Unicode box-drawing rules and vertical bars. */ RICH, + + /** Comma-separated values. */ CSV, + + /** An HTML table. */ HTML, + + /** A JSON array of the header row followed by one object per data row. */ JSON, + + /** A YAML list of the header row followed by one mapping per data row. */ YAML, } diff --git a/src/main/java/rickwporter/prettytable/PrettyObject.java b/src/main/java/rickwporter/prettytable/PrettyObject.java index 5d57ce3..a2cfc6b 100644 --- a/src/main/java/rickwporter/prettytable/PrettyObject.java +++ b/src/main/java/rickwporter/prettytable/PrettyObject.java @@ -8,14 +8,30 @@ import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator; import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; +/** + * Renders a value as a string. + * {@code null} becomes an empty string. A string, number, or boolean is rendered with + * {@link String#valueOf(Object)}. JSON and YAML write the value with Jackson. Every other format + * builds a {@link PrettyTable} from a {@link java.util.Map} or {@link java.util.List}. + */ public final class PrettyObject { private static final String INDENT = " "; private BuilderConfig config; + /** + * Creates a renderer that uses {@link BuilderConfig} defaults. + */ public PrettyObject() { this(null); } + /** + * Creates a renderer that uses {@code options} for table output. + * JSON and YAML ignore the config and write the value as given. A {@code null} config uses + * {@link BuilderConfig} defaults. + * + * @param options labels, limits, and format settings, or {@code null} + */ public PrettyObject(BuilderConfig options) { this.config = options == null ? new BuilderConfig() : options; } @@ -55,6 +71,15 @@ String renderYaml(Object object, YAMLMapper mapper) { } } + /** + * Renders {@code object} in {@code format}. + * + * @param format output format + * @param object value to render, or {@code null} + * @return the rendered text, or an empty string when {@code object} is {@code null} + * @throws IllegalArgumentException if a table format is given a value that is not a map or list + * @throws IllegalStateException if JSON or YAML writing fails + */ public String render(OutputFormat format, Object object) { if (object == null) { return ""; diff --git a/src/main/java/rickwporter/prettytable/PrettyTable.java b/src/main/java/rickwporter/prettytable/PrettyTable.java index c3cdce9..107ddcf 100644 --- a/src/main/java/rickwporter/prettytable/PrettyTable.java +++ b/src/main/java/rickwporter/prettytable/PrettyTable.java @@ -7,6 +7,14 @@ import java.util.regex.Pattern; +/** + * A table of cells that can be rendered as text, rich text, CSV, HTML, JSON, or YAML. + * + *

The default format is {@link OutputFormat#TEXT}. Text and rich output show the header and + * the border, omit rules between data rows, and clear repeated leading cells. A caption is omitted + * until one is set. Cells are centered until an alignment is set. A cell may itself be a + * {@code PrettyTable}, and that nested table is rendered in its own format. + */ public final class PrettyTable { private static final Pattern NEWLINE = Pattern.compile("\\R"); @@ -21,22 +29,51 @@ public final class PrettyTable { private boolean omitRedundant = true; private String caption = null; + /** + * Creates a table with the given column headers. + * Passing no headers leaves the table without a header row. + * + * @param hdrs column headers, in display order + */ public PrettyTable(String... hdrs) { this.headers.addAll(Arrays.asList(hdrs)); } + /** + * Returns the column headers in display order. + * + * @return the headers, possibly empty + */ public List getHeaders() { return this.headers; } - public void addRow(Object... row) { + /** + * Appends a row. + * A nested {@code PrettyTable} cell is rendered with that table's own format. + * + * @param row cell values, in column order + */ + public void addRow(Object... row) { this.rows.add(Arrays.asList(row)); } + /** + * Returns the number of data rows. + * + * @return the row count + */ public int getRowCount() { return this.rows.size(); } + /** + * Returns the cells in one data row. + * + * @param rowIndex zero-based row index + * @return the row, or {@code null} when {@code rowIndex} is past the last row + * @throws IndexOutOfBoundsException if {@code rowIndex} is negative + */ public List getRow(int rowIndex) { if (this.rows.size() <= rowIndex) { return null; @@ -44,10 +81,24 @@ public List getRow(int rowIndex) { return this.rows.get(rowIndex); } + /** + * Returns the data rows in display order. + * + * @return the rows, possibly empty + */ public List> getRows() { return this.rows; } + /** + * Returns one cell. + * + * @param rowIndex zero-based row index + * @param columnIndex zero-based column index + * @return the cell, or {@code null} when either index is past the end of the table + * @throws IndexOutOfBoundsException if {@code rowIndex} is negative, or if the row exists and + * {@code columnIndex} is negative + */ public Object getCell(int rowIndex, int columnIndex) { List row = this.getRow(rowIndex); if (row == null || row.size() <= columnIndex) { @@ -56,10 +107,23 @@ public Object getCell(int rowIndex, int columnIndex) { return row.get(columnIndex); } + /** + * Returns the alignment used for columns that have no explicit alignment. + * The default is {@link HorizontalAlign#CENTER}. + * + * @return the default alignment + */ public HorizontalAlign getDefaultHorizAlign() { return this.defaultHorizontal; } + /** + * Sets the horizontal alignment of one column. + * Columns before {@code column} that have no alignment keep the default. + * + * @param column zero-based column index + * @param fmt alignment for that column + */ public void setHorizAlign(int column, HorizontalAlign fmt) { for (int cIdx = this.hAligns.size(); cIdx <= column; cIdx++) { this.hAligns.add(this.defaultHorizontal); @@ -67,63 +131,155 @@ public void setHorizAlign(int column, HorizontalAlign fmt) { this.hAligns.set(column, fmt); } + /** + * Replaces the per-column alignments. + * Columns past the end of {@code fmts} use {@link #getDefaultHorizAlign()}. + * + * @param fmts alignments, in column order + */ public void setHorizAligns(HorizontalAlign... fmts) { this.hAligns.clear(); this.hAligns.addAll(Arrays.asList(fmts)); } + /** + * Returns the per-column alignments that have been set. + * + * @return the alignments, possibly empty + */ public List getHorizAligns() { return this.hAligns; } + /** + * Sets the format used by {@link #toString()}. + * The default is {@link OutputFormat#TEXT}. + * + * @param format output format + */ public void setOutputFormat(OutputFormat format) { this.defaultOutput = format; } + /** + * Returns the format used by {@link #toString()}. + * + * @return the output format + */ public OutputFormat getDefaultOutput() { return this.defaultOutput; } + /** + * Shows or hides the header row in text and rich output. + * Hidden headers are also left out of the column-width calculation. The default is to show + * the header. CSV, HTML, JSON, and YAML ignore this setting. + * + * @param visible {@code true} to include the header row + */ public void setShowHeader(boolean visible) { this.showHeader = visible; } + /** + * Returns whether text and rich output include the header row. + * + * @return {@code true} when the header is shown + */ public boolean isShowHeader() { return this.showHeader; } + /** + * Shows or hides the border in text and rich output. + * Hiding the border also hides row dividers. Cell padding and alignment remain. The default + * is to show the border. CSV, HTML, JSON, and YAML ignore this setting. + * + * @param visible {@code true} to draw rules and vertical borders + */ public void setShowLines(boolean visible) { this.showLines = visible; } + /** + * Returns whether text and rich output draw the border. + * + * @return {@code true} when the border is shown + */ public boolean isShowLines() { return this.showLines; } + /** + * Draws or omits a rule under data rows in text and rich output. + * A row that shares a leading prefix with the row above has no rule under it while redundant + * cells are being removed. {@link #setShowLines(boolean) Hiding the border} hides these rules + * as well. The default is no row dividers. CSV, HTML, JSON, and YAML ignore this setting. + * + * @param visible {@code true} to draw a rule under data rows + */ public void setRowDividers(boolean visible) { this.rowDividers = visible; } + /** + * Returns whether text and rich output draw a rule under data rows. + * + * @return {@code true} when row dividers are drawn + */ public boolean isRowDividers() { return this.rowDividers; } + /** + * Clears or keeps repeated leading cells in text, rich, and HTML output. + * The default is to clear them. {@link #formattedString(OutputFormat)} uses this setting. + * {@link #formattedString(OutputFormat, boolean)} overrides it for that call. CSV, JSON, and + * YAML keep every cell either way. + * + * @param remove {@code true} to clear repeated leading cells + */ public void setRemoveRedundant(boolean remove) { this.omitRedundant = remove; } + /** + * Returns whether text, rich, and HTML output clear repeated leading cells. + * + * @return {@code true} when repeated leading cells are cleared + */ public boolean isRemoveRedundant() { return this.omitRedundant; } + /** + * Sets the caption printed under a text or rich table. + * A {@code null} or empty caption is skipped. Any other caption is printed unchanged, including + * its newlines. CSV, HTML, JSON, and YAML ignore this setting. + * + * @param value caption text, or {@code null} to omit it + */ public void setCaption(String value) { this.caption = value; } + /** + * Returns the caption, or {@code null} when none is set. + * + * @return the caption + */ public String getCaption() { return this.caption; } + /** + * Returns the widest line in one column. + * The header is included when it is shown and this column has one. Newlines split a cell into + * separate lines. + * + * @param column zero-based column index + * @return the width in characters + */ public int getMaxWidthForColumn(int column) { int maxWidth = 0; if (this.showHeader && column < this.headers.size()) { @@ -161,6 +317,14 @@ private void sortRows(List indices) { }); } + /** + * Sorts the rows by the named headers, from the first name to the last. + * A cell that parses as a float is compared numerically. Any other cell is compared as text. + * Rows that compare equal keep their relative order. + * + * @param order header names, most significant first + * @throws ArrayIndexOutOfBoundsException if a name is not a header + */ public void sortByHeader(String... order) { List indices = new ArrayList<>(); for (String hdr : order) { @@ -169,15 +333,35 @@ public void sortByHeader(String... order) { this.sortRows(indices); } + /** + * Sorts the rows by column index, from the first index to the last. + * A cell that parses as a float is compared numerically. Any other cell is compared as text. + * Rows that compare equal keep their relative order. + * + * @param indices column indexes, most significant first + * @throws ArrayIndexOutOfBoundsException if an index is outside the row + */ public void sortByIndex(Integer... indices) { this.sortRows(Arrays.asList(indices)); } + /** + * Returns the number of columns. + * The count is the number of headers, or the length of the first row when there are no headers. + * + * @return the column count + */ public int getMaxColumns() { // get the # of columns from the first row when there are no headers return this.headers.isEmpty() ? this.rows.get(0).size() : this.headers.size(); } + /** + * Returns the widest line in each column, in column order. + * + * @return one width per column + * @see #getMaxWidthForColumn(int) + */ public List getMaxWidths() { List maxWidths = new ArrayList<>(); for (int cIdx = 0; cIdx < this.getMaxColumns(); cIdx++) { @@ -210,10 +394,26 @@ String toYaml() { return formattedString(OutputFormat.YAML, false); } + /** + * Renders the table in {@code format}, using {@link #isRemoveRedundant()}. + * + * @param format output format + * @return the rendered table + * @throws IllegalArgumentException if {@code format} is not supported + */ public String formattedString(OutputFormat format) { return this.formattedString(format, this.omitRedundant); } + /** + * Renders the table in {@code format}. + * {@code removeRedundant} applies to text, rich, and HTML. CSV, JSON, and YAML keep every cell. + * + * @param format output format + * @param removeRedundant whether text, rich, and HTML clear repeated leading cells + * @return the rendered table + * @throws IllegalArgumentException if {@code format} is not supported + */ public String formattedString(OutputFormat format, boolean removeRedundant) { final TableRenderInterface renderer; if (format == OutputFormat.TEXT) { @@ -234,10 +434,22 @@ public String formattedString(OutputFormat format, boolean removeRedundant) { return render(renderer, removeRedundant); } + /** + * Renders the table with a caller-supplied renderer. + * + * @param renderer renderer to use + * @param removeRedundant passed through to {@link TableRenderInterface#render} + * @return the rendered table + */ public String render(TableRenderInterface renderer, boolean removeRedundant) { return renderer.render(this, removeRedundant); } + /** + * Renders the table in the format from {@link #getDefaultOutput()}. + * + * @return the rendered table + */ public String toString() { return this.formattedString(this.defaultOutput); } diff --git a/src/main/java/rickwporter/prettytable/TableBuilder.java b/src/main/java/rickwporter/prettytable/TableBuilder.java index c4ec65f..fe63772 100644 --- a/src/main/java/rickwporter/prettytable/TableBuilder.java +++ b/src/main/java/rickwporter/prettytable/TableBuilder.java @@ -8,20 +8,52 @@ import java.util.Map; import java.util.Set; +/** + * Builds a {@link PrettyTable} from a {@link Map} or a {@link List}. + * + *

A map becomes a property/value table. Nested maps become nested tables, and a list of plain + * values is joined into one cell. A list of strings, numbers, or booleans becomes one column with + * an item-count caption. A list of maps uses the first matching + * {@linkplain BuilderConfig#getKeyFields() key field} as the row name, with that field's header + * capitalized. One other field becomes the second column. Further fields are nested under the + * properties label. {@link BuilderConfig#getColumns()} selects columns for a list of maps, and a + * {@code *} column gathers every field that was not named. + * + *

Keys, values, and URLs are cut off with the config's ellipsis. Built tables are left-aligned + * and do not clear repeated cells. + */ public final class TableBuilder { private static final String WILDCARD_COLUMN = "*"; private static final Object MANY_KEYS = new Object(); private final BuilderConfig config; + /** + * Creates a builder that uses {@link BuilderConfig} defaults. + */ public TableBuilder() { this(null); } + /** + * Creates a builder that uses {@code options}. + * A {@code null} config uses {@link BuilderConfig} defaults. + * + * @param options labels, limits, columns, and format, or {@code null} + */ public TableBuilder(BuilderConfig options) { this.config = options == null ? new BuilderConfig() : options; } + /** + * Builds a table from {@code data} and sets its output format to {@code format}. + * The config's format is restored before this method returns. + * + * @param format format stored on the table + * @param data a map, a list, or an empty value + * @return the table, or {@code null} when {@code data} is {@code null} or empty + * @throws IllegalArgumentException if {@code data} cannot be turned into a table + */ public PrettyTable build(OutputFormat format, Object data) { OutputFormat original = this.config.getFormat(); this.config.setFormat(format); @@ -32,6 +64,13 @@ public PrettyTable build(OutputFormat format, Object data) { return result; } + /** + * Builds a table from {@code data} using {@link BuilderConfig#getFormat()}. + * + * @param data a map, a list, or an empty value + * @return the table, or {@code null} when {@code data} is {@code null} or empty + * @throws IllegalArgumentException if {@code data} cannot be turned into a table + */ public PrettyTable build(Object data) { if (isNothing(data)) { return null; diff --git a/src/main/java/rickwporter/prettytable/TableGlyphs.java b/src/main/java/rickwporter/prettytable/TableGlyphs.java index a0a5ade..4a8b232 100644 --- a/src/main/java/rickwporter/prettytable/TableGlyphs.java +++ b/src/main/java/rickwporter/prettytable/TableGlyphs.java @@ -1,11 +1,24 @@ package rickwporter.prettytable; +/** + * Four characters that draw one horizontal rule or one vertical border. + * In order they are the left edge, the repeated fill, the junction between columns, and the right edge. + * The fill of a vertical border is unused. + */ public final class TableGlyphs { private Character mLeft; private Character mFill; private Character mJunction; private Character mRight; + /** + * Creates a glyph set. + * + * @param left character at the left edge + * @param fill character repeated across a column, unused for a vertical border + * @param junction character between columns + * @param right character at the right edge + */ public TableGlyphs(Character left, Character fill, Character junction, Character right) { this.mLeft = left; this.mFill = fill; @@ -13,18 +26,38 @@ public TableGlyphs(Character left, Character fill, Character junction, Character this.mRight = right; } + /** + * Returns the left-edge character. + * + * @return the left-edge character + */ public Character left() { return this.mLeft; } + /** + * Returns the fill character. + * + * @return the fill character + */ public Character fill() { return this.mFill; } + /** + * Returns the character drawn between columns. + * + * @return the junction character + */ public Character junction() { return this.mJunction; } + /** + * Returns the right-edge character. + * + * @return the right-edge character + */ public Character right() { return this.mRight; } diff --git a/src/main/java/rickwporter/prettytable/TableRenderInterface.java b/src/main/java/rickwporter/prettytable/TableRenderInterface.java index ba8c8f5..7f36941 100644 --- a/src/main/java/rickwporter/prettytable/TableRenderInterface.java +++ b/src/main/java/rickwporter/prettytable/TableRenderInterface.java @@ -1,5 +1,17 @@ package rickwporter.prettytable; +/** + * Turns a {@link PrettyTable} into a string. + */ public interface TableRenderInterface { + /** + * Renders {@code table}. + * Text, rich, and HTML renderers clear repeated leading cells when {@code removeRedundant} is + * true. CSV, JSON, and YAML keep every cell. + * + * @param table table to render + * @param removeRedundant whether repeated leading cells should be cleared + * @return the rendered table + */ String render(PrettyTable table, boolean removeRedundant); }