001/*
002  Licensed to the Apache Software Foundation (ASF) under one or more
003  contributor license agreements.  See the NOTICE file distributed with
004  this work for additional information regarding copyright ownership.
005  The ASF licenses this file to You under the Apache License, Version 2.0
006  (the "License"); you may not use this file except in compliance with
007  the License.  You may obtain a copy of the License at
008
009      https://www.apache.org/licenses/LICENSE-2.0
010
011  Unless required by applicable law or agreed to in writing, software
012  distributed under the License is distributed on an "AS IS" BASIS,
013  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014  See the License for the specific language governing permissions and
015  limitations under the License.
016 */
017package org.apache.commons.cli.help;
018
019import java.util.List;
020
021/**
022 * The definition of a table to display.
023 * <p>
024 * Aa table definition contains a caption and data that describes each column. Every column in the table may have
025 * </p>
026 * <ul>
027 * <li>A caption.</li>
028 * <li>A {@link TextStyle} that describes the width of the entry, its offset from the previous column (leftPad) and how much each line after the first should be
029 * indented (indent).</li>
030 * <li>A heading (String) is placed at the top of the column</li>
031 * <li>A collection of rows</li>
032 * </ul>
033 *
034 * @since 1.10.0
035 */
036public interface TableDefinition {
037
038    /**
039     * A helper function to create a table instance from the various components.
040     *
041     * @param caption     The caption, may be {@code null}.
042     * @param columnStyle a list of TextStyle elements defining the columns.
043     * @param headers     the list of column headers.
044     * @param rows        a collection of rows.
045     * @return A TableDefinition returning the parameters as appropriate.
046     */
047    static TableDefinition from(final String caption, final List<TextStyle> columnStyle, final List<String> headers, final Iterable<List<String>> rows) {
048        return new TableDefinition() {
049
050            @Override
051            public String caption() {
052                return caption;
053            }
054
055            @Override
056            public List<TextStyle> columnTextStyles() {
057                return columnStyle;
058            }
059
060            @Override
061            public List<String> headers() {
062                return headers;
063            }
064
065            @Override
066            public Iterable<List<String>> rows() {
067                return rows;
068            }
069        };
070    }
071
072    /**
073     * Gets the caption for the table. May be @{code null}.
074     *
075     * @return The caption for the table. May be @{code null}.
076     */
077    String caption();
078
079    /**
080     * Gets the list TextStyles. One for each column in order.
081     *
082     * @return the list of TextStyles.
083     */
084    List<TextStyle> columnTextStyles();
085
086    /**
087     * Gets the list of header strings. One for each column in order.
088     *
089     * @return The list of header strings.
090     */
091    List<String> headers();
092
093    /**
094     * Gets the collection of rows.
095     * <p>
096     * Each row is a list of Strings, one for each column in the table.
097     * </p>
098     *
099     * @return The collection of rows.
100     */
101    Iterable<List<String>> rows();
102}