contrib/kyua/utils/text/table.hpp

   1 // Copyright 2012 The Kyua Authors.
   2 // All rights reserved.
   3 //
   4 // Redistribution and use in source and binary forms, with or without
   5 // modification, are permitted provided that the following conditions are
   6 // met:
   7 //
   8 // * Redistributions of source code must retain the above copyright
   9 //   notice, this list of conditions and the following disclaimer.
  10 // * Redistributions in binary form must reproduce the above copyright
  11 //   notice, this list of conditions and the following disclaimer in the
  12 //   documentation and/or other materials provided with the distribution.
  13 // * Neither the name of Google Inc. nor the names of its contributors
  14 //   may be used to endorse or promote products derived from this software
  15 //   without specific prior written permission.
  16 //
  17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 /// \file utils/text/table.hpp
  30 /// Table construction and formatting.
  31
  32 #if !defined(UTILS_TEXT_TABLE_HPP)
  33 #define UTILS_TEXT_TABLE_HPP
  34
  35 #include "utils/text/table_fwd.hpp"
  36
  37 #include <cstddef>
  38 #include <string>
  39 #include <vector>
  40
  41 namespace utils {
  42 namespace text {
  43
  44
  45 /// Representation of a table.
  46 ///
  47 /// A table is nothing more than a matrix of rows by columns.  The number of
  48 /// columns is hardcoded at construction times, and the rows can be accumulated
  49 /// at a later stage.
  50 ///
  51 /// The only value of this class is a simpler and more natural mechanism of the
  52 /// construction of a table, with additional sanity checks.  We could as well
  53 /// just expose the internal data representation to our users.
  54 class table {
  55     /// Widths of the table columns so far.
  56     widths_vector _column_widths;
  57
  58     /// Type defining the collection of rows in the table.
  59     typedef std::vector< table_row > rows_vector;
  60
  61     /// The rows of the table.
  62     ///
  63     /// This is actually the matrix representing the table.  Every element of
  64     /// this vector (which are vectors themselves) must have _ncolumns items.
  65     rows_vector _rows;
  66
  67 public:
  68     table(const table_row::size_type);
  69
  70     widths_vector::size_type ncolumns(void) const;
  71     widths_vector::value_type column_width(const widths_vector::size_type)
  72         const;
  73     const widths_vector& column_widths(void) const;
  74
  75     void add_row(const table_row&);
  76
  77     bool empty(void) const;
  78
  79     /// Constant iterator on the rows of the table.
  80     typedef rows_vector::const_iterator const_iterator;
  81
  82     const_iterator begin(void) const;
  83     const_iterator end(void) const;
  84 };
  85
  86
  87 /// Settings to format a table.
  88 ///
  89 /// This class implements a builder pattern to construct an object that contains
  90 /// all the knowledge to format a table.  Once all the settings have been set,
  91 /// the format() method provides the algorithm to apply such formatting settings
  92 /// to any input table.
  93 class table_formatter {
  94     /// Text to use as the separator between cells.
  95     std::string _separator;
  96
  97     /// Colletion of widths of the columns of a table.
  98     std::size_t _table_width;
  99
 100     /// Widths of the table columns.
 101     ///
 102     /// Note that this only includes widths for the column widths explicitly
 103     /// overriden by the caller.  In other words, this vector can be shorter
 104     /// than the table passed to the format() method, which is just fine.  Any
 105     /// non-specified column widths are assumed to be width_auto.
 106     widths_vector _column_widths;
 107
 108 public:
 109     table_formatter(void);
 110
 111     static const std::size_t width_auto;
 112     static const std::size_t width_refill;
 113     table_formatter& set_column_width(const table_row::size_type,
 114                                       const std::size_t);
 115     table_formatter& set_separator(const char*);
 116     table_formatter& set_table_width(const std::size_t);
 117
 118     std::vector< std::string > format(const table&) const;
 119 };
 120
 121
 122 }  // namespace text
 123 }  // namespace utils
 124
 125 #endif  // !defined(UTILS_TEXT_TABLE_HPP)