A table is built by adding rows one at a time, then calling {@link #build()} + * to obtain the fully rendered string. Column width is computed automatically + * from the widest cell across all rows. + * + *
Example usage: + *
{@code
+ * AsciiTable table = new AsciiTable(BorderStyle.UNICODE, 3);
+ * table.addHeader("Name", "Food", "PP");
+ * table.addRow("Alice", "4", "12");
+ * table.addRow("Bob", "2", "8");
+ * System.out.println(table.build());
+ * }
+ */
public class AsciiTable {
- //TODO javadoc
+
+ /**
+ * The border style used to draw the table (e.g. Unicode box-drawing,
+ * plain ASCII, rounded corners).
+ */
private final BorderStyle s;
- //TODO javadoc
+ /**
+ * The number of columns in the table.
+ * Every row added via {@link #addRow} must contain exactly this many cells.
+ */
private final int cols;
- //TODO javadoc
+ /**
+ * The rows of the table, each represented as a list of cell strings.
+ * Rows are stored in display order; {@link #addHeader} inserts at index 0.
+ */
private final ListCalling this method after rows have already been added will push + * all existing rows down by one position. + * + * @param cells one string per column, in left-to-right order + */ + public void addHeader(String... cells) { + rows.add(0, Arrays.asList(cells)); + separators.add(0); + } - //TODO javadoc - public void addSeparator() { separators.add(rows.size()-1); } + /** + * Marks the current last row so that a horizontal separator line is + * drawn below it when the table is built. + * + *
Call this method immediately after the row that should be followed + * by the separator. + */ + public void addSeparator() { separators.add(rows.size() - 1); } - //TODO javadoc + /** + * Renders the table to a multi-line string. + * + *
Column width is determined dynamically as the length of the longest + * cell across all rows, plus one padding space. All cells are left-aligned + * and padded or truncated to the same width. + * + * @return the fully rendered table as a single string with embedded newlines + */ public String build() { var sb = new StringBuilder(); - int maxWidth = rows.stream().mapToInt(x->x.stream().mapToInt(y->y.length()).max().getAsInt()).max().getAsInt()+1; - sb.append(hline(s.tl(), s.mt(), s.tr(),maxWidth)).append('\n'); + int maxWidth = rows.stream() + .mapToInt(x -> x.stream().mapToInt(y -> y.length()).max().getAsInt()) + .max().getAsInt() + 1; + sb.append(hline(s.tl(), s.mt(), s.tr(), maxWidth)).append('\n'); for (int i = 0; i < rows.size(); i++) { sb.append(s.v()); @@ -45,14 +114,23 @@ public class AsciiTable { sb.append(rpad(" " + cell, maxWidth)).append(s.v()); sb.append('\n'); if (separators.contains(i) && i < rows.size() - 1) - sb.append(hline(s.sl(), s.sx(), s.sr(),maxWidth)).append('\n'); + sb.append(hline(s.sl(), s.sx(), s.sr(), maxWidth)).append('\n'); } sb.append(hline(s.bl(), s.mb(), s.br(), maxWidth)); return sb.toString(); } - //TODO javadoc - private String hline(String l, String m, String r,int maxWidth) { + /** + * Builds a single horizontal border line spanning all columns. + * + * @param l the left-end character (e.g. {@code ╔}, {@code ╠}, {@code ╚}) + * @param m the column-junction character (e.g. {@code ╦}, {@code ╬}, {@code ╩}) + * @param r the right-end character (e.g. {@code ╗}, {@code ╣}, {@code ╝}) + * @param maxWidth the width in characters of each column segment, + * filled with the horizontal line character of the current style + * @return the rendered horizontal line as a string + */ + private String hline(String l, String m, String r, int maxWidth) { var sb = new StringBuilder(l); for (int i = 0; i < cols; i++) { sb.append(s.h().repeat(maxWidth)); @@ -61,13 +139,40 @@ public class AsciiTable { return sb.append(r).toString(); } - //TODO javadoc + /** + * Right-pads a string with spaces to the given width, or truncates it + * if it exceeds that width. + * + * @param s the input string + * @param w the desired output width in characters + * @return a string of exactly {@code w} characters + */ private static String rpad(String s, int w) { if (s.length() >= w) return s.substring(0, w); return s + " ".repeat(w - s.length()); } - //TODO javadoc + /** + * Places two pre-rendered text blocks side by side, separated by a gap. + * + *
Each block is a list of lines as returned by {@link #build()}. + * Lines in the left block are padded to a uniform width so that the + * right block always starts at the same horizontal position. If one + * block is taller than the other, the shorter one is padded with blank + * lines. + * + *
Example: + *
{@code
+ * List left = Arrays.asList(table1.build().split("\n"));
+ * List right = Arrays.asList(table2.build().split("\n"));
+ * System.out.print(AsciiTable.sideBySide(left, right, 2));
+ * }
+ *
+ * @param left lines of the left block
+ * @param right lines of the right block
+ * @param gap number of blank spaces between the two blocks
+ * @return the merged string with embedded newlines
+ */
public static String sideBySide(List