diff --git a/.gitignore b/.gitignore index 149242e9..ad2d8752 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ target/ /*.iws out .gradletasknamecache +.DS_Store diff --git a/src/main/java/org/springframework/shell/TerminalSizeAware.java b/src/main/java/org/springframework/shell/TerminalSizeAware.java index a9fa6d77..00bf20db 100644 --- a/src/main/java/org/springframework/shell/TerminalSizeAware.java +++ b/src/main/java/org/springframework/shell/TerminalSizeAware.java @@ -1,9 +1,25 @@ +/* + * Copyright 2017 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + package org.springframework.shell; /** * To be implemented by command result objects that can adapt to the terminal size when they are being rendered. * - *

An object which does not implement this interface will simply be rendered by invoking its {@link #toString()} + *

An object which does not implement this interface will simply be rendered by invoking its {@link Object#toString()} * method.

* * @author Eric Bottard diff --git a/src/main/java/org/springframework/shell/table/Aligner.java b/src/main/java/org/springframework/shell/table/Aligner.java index 23ac5ce0..e81bc547 100644 --- a/src/main/java/org/springframework/shell/table/Aligner.java +++ b/src/main/java/org/springframework/shell/table/Aligner.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,11 +24,18 @@ package org.springframework.shell.table; public interface Aligner { /** - * Perform text alignment, returning a String array that MUST contain - * {@code cellHeight} lines, each of which MUST be {@code cellWidth} chars in length. + * Perform text alignment, returning a String array that MUST contain {@code cellHeight} + * lines, each of which MUST be {@code cellWidth} chars in length. * - *

Input array is guaranteed to contain lines that have length equal to {@cellWidth}. There - * is no guarantee on the input number of lines though.

+ *

+ * Input array is guaranteed to contain lines that have length equal to {@code cellWidth}. + * There is no guarantee on the input number of lines though. + *

+ * + * @param text the text to align + * @param cellWidth the width of of the table cell + * @param cellHeight the height of the table cell + * @return the aligned text, in a {@code cellHeight} element array */ String[] align(String[] text, int cellWidth, int cellHeight); } diff --git a/src/main/java/org/springframework/shell/table/CellMatcher.java b/src/main/java/org/springframework/shell/table/CellMatcher.java index dda53f14..aee78ec3 100644 --- a/src/main/java/org/springframework/shell/table/CellMatcher.java +++ b/src/main/java/org/springframework/shell/table/CellMatcher.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -26,7 +26,10 @@ package org.springframework.shell.table; public interface CellMatcher { /** - * Return whether a given cell of the table should match. + * @return whether a given cell of the table should match. + * @param row the row being tested. + * @param column the column being tested + * @param model the data model of the table */ public boolean matches(int row, int column, TableModel model); } diff --git a/src/main/java/org/springframework/shell/table/CellMatchers.java b/src/main/java/org/springframework/shell/table/CellMatchers.java index f9fdfff3..183c112a 100644 --- a/src/main/java/org/springframework/shell/table/CellMatchers.java +++ b/src/main/java/org/springframework/shell/table/CellMatchers.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,7 +24,7 @@ package org.springframework.shell.table; public class CellMatchers { /** - * Return a matcher that applies to every cell of the table. + * @return a matcher that applies to every cell of the table. */ public static CellMatcher table() { return new CellMatcher() { @@ -35,7 +35,8 @@ public class CellMatchers { } /** - * Return a matcher that applies to every cell of some column of the table. + * @return a matcher that applies to every cell of some column of the table. + * @param col the column to select */ public static CellMatcher column(final int col) { return new CellMatcher() { @@ -46,7 +47,8 @@ public class CellMatchers { } /** - * Return a matcher that applies to every cell of some row of the table. + * @return a matcher that applies to every cell of some row of the table. + * @param theRow the row to select */ public static CellMatcher row(final int theRow) { return new CellMatcher() { @@ -56,6 +58,10 @@ public class CellMatchers { }; } + /** + * @param clazz the type that cells should contain + * @return a matcher that matches cells whose content is of a certain type + */ public static CellMatcher ofType(final Class clazz) { return new CellMatcher() { @Override diff --git a/src/main/java/org/springframework/shell/table/SizeConstraints.java b/src/main/java/org/springframework/shell/table/SizeConstraints.java index f81b842b..cec862c6 100644 --- a/src/main/java/org/springframework/shell/table/SizeConstraints.java +++ b/src/main/java/org/springframework/shell/table/SizeConstraints.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -26,7 +26,7 @@ import org.springframework.util.Assert; public interface SizeConstraints { /** - * Return the minimum and maximum width of the cell, given its raw content. + * @return the minimum and maximum width of the cell, given its raw content. * @param raw the raw String representation of the cell contents (may be reformatted later, eg wrapped) * @param tableWidth the whole available width for the table * @param nbColumns the number of columns in the table diff --git a/src/main/java/org/springframework/shell/table/Table.java b/src/main/java/org/springframework/shell/table/Table.java index 337f72da..8b7b8402 100644 --- a/src/main/java/org/springframework/shell/table/Table.java +++ b/src/main/java/org/springframework/shell/table/Table.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -30,14 +30,14 @@ import org.springframework.shell.TerminalSizeAware; * TableModel, which holds raw table contents. Its rendering logic is then altered by applying * various customizations, in a fashion very similar to what is used e.g. in a spreadsheet * program:
    - *
  1. {@link #format(CellMatcher, Formatter) formatters} know how to derive character data out of raw data. For + *
  2. {@link #formatters formatters} know how to derive character data out of raw data. For * example, numbers are * formatted according to a Locale, or Maps are emitted as a series of {@literal key=value} lines
    3. - *
  3. {@link #size(CellMatcher, SizeConstraints) size constraints} are then applied, which decide how + *
  4. {@link #sizeConstraints size constraints} are then applied, which decide how * much column real estate to allocate to cells
    5. - *
  5. {@link #wrap(CellMatcher, TextWrapper) text wrapping policies} are applied once the column sizes + *
  6. {@link #wrappers text wrapping policies} are applied once the column sizes * are known
    7. - *
  7. finally, {@link #align(CellMatcher, Aligner) alignment} strategies actually render + *
  8. finally, {@link #aligners alignment} strategies actually render * text as a series of space-padded strings that draw nicely on screen.
    9. *
* All those customizations are applied selectively on the Table cells thanks to a {@link CellMatcher}: One can diff --git a/src/main/java/org/springframework/shell/table/TableBuilder.java b/src/main/java/org/springframework/shell/table/TableBuilder.java index 8c69fcbe..2a3bebda 100644 --- a/src/main/java/org/springframework/shell/table/TableBuilder.java +++ b/src/main/java/org/springframework/shell/table/TableBuilder.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -60,6 +60,8 @@ public class TableBuilder { *
  • {@link DelimiterTextWrapper wrapping text} on space characters
    • *
  • {@link SimpleHorizontalAligner left aligning} text.
    • * + * + * @param model the data model of the table to construct */ public TableBuilder(TableModel model) { @@ -109,6 +111,8 @@ public class TableBuilder { /** * Set a border on the outline of the whole table. + * @param style the style to apply + * @return this, for method chaining */ public TableBuilder addOutlineBorder(BorderStyle style) { this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), OUTLINE, style); @@ -117,6 +121,8 @@ public class TableBuilder { /** * Set a border on the outline of the whole table, as well as around the first row. + * @param style the style to apply + * @return this, for method chaining */ public TableBuilder addHeaderBorder(BorderStyle style) { this.addBorder(0, 0, 1, model.getColumnCount(), OUTLINE, style); @@ -125,6 +131,9 @@ public class TableBuilder { /** * Set a border around each and every cell of the table. + * + * @param style the style to apply + * @return this, for method chaining */ public TableBuilder addFullBorder(BorderStyle style) { this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), FULL, style); @@ -134,6 +143,9 @@ public class TableBuilder { /** * Set a border on the outline of the whole table, around the first row and draw vertical lines * around each column. + * + * @param style the style to apply + * @return this, for method chaining */ public TableBuilder addHeaderAndVerticalsBorders(BorderStyle style) { this.addBorder(0, 0, 1, model.getColumnCount(), OUTLINE, style); @@ -143,6 +155,9 @@ public class TableBuilder { /** * Set a border on the inner verticals and horizontals of the table, but not on the outline. + * + * @param style the style to apply + * @return this, for method chaining */ public TableBuilder addInnerBorder(BorderStyle style) { this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), INNER, style); diff --git a/src/main/java/org/springframework/shell/table/TableModel.java b/src/main/java/org/springframework/shell/table/TableModel.java index 355ca8d0..381c261d 100644 --- a/src/main/java/org/springframework/shell/table/TableModel.java +++ b/src/main/java/org/springframework/shell/table/TableModel.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,24 +24,26 @@ package org.springframework.shell.table; public abstract class TableModel { /** - * Return the number of rows that can be queried. + * @return the number of rows that can be queried. * Values between 0 and {@code rowCount-1} inclusive are valid values. */ public abstract int getRowCount(); /** - * Return the number of columns that can be queried. + * @return the number of columns that can be queried. * Values between 0 and {@code columnCount-1} inclusive are valid values. */ public abstract int getColumnCount(); /** - * Return the data value to be displayed at a given row and column, which may be null. + * @return the data value to be displayed at a given row and column, which may be null. + * @param row the row that is being queried + * @param column the column that is being queried */ public abstract Object getValue(int row, int column); /** - * Return a transposed view of this model, where rows become columns and vice-versa. + * @return a transposed view of this model, where rows become columns and vice-versa. */ public TableModel transpose() { return new TableModel() { diff --git a/src/main/java/org/springframework/shell/table/Tables.java b/src/main/java/org/springframework/shell/table/Tables.java index 51e5e1db..52289e08 100644 --- a/src/main/java/org/springframework/shell/table/Tables.java +++ b/src/main/java/org/springframework/shell/table/Tables.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -27,6 +27,10 @@ public class Tables { /** * Install all the necessary formatters, aligners, etc for key-value rendering of Maps. + * + * @param builder the builder to configure + * @param delimiter the delimiter to apply between keys and values + * @return buider for method chaining */ public static TableBuilder configureKeyValueRendering(TableBuilder builder, String delimiter) { return builder.on(CellMatchers.ofType(Map.class)) diff --git a/src/main/java/org/springframework/shell/table/TextWrapper.java b/src/main/java/org/springframework/shell/table/TextWrapper.java index df89ae1f..5838174d 100644 --- a/src/main/java/org/springframework/shell/table/TextWrapper.java +++ b/src/main/java/org/springframework/shell/table/TextWrapper.java @@ -1,5 +1,5 @@ /* - * Copyright 2015 the original author or authors. + * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,13 +18,18 @@ package org.springframework.shell.table; /** * A strategy for applying text wrapping/cropping given a cell width. + * + * @author Eric Bottard */ public interface TextWrapper { /** - * Return a list of lines where each line length MUST be equal to {@code columnWidth} (padding with spaces if + * @return a list of lines where each line length MUST be equal to {@code columnWidth} (padding with spaces if * appropriate). There is no constraint on the number of lines returned however (typically, will be greater than * the input number if wrapping occurred). + * + * @param original the text in its original form + * @param columnWidth the width to conform to */ String[] wrap(String[] original, int columnWidth); }