PrettyTables.jl v3

.github/workflows/ci-v3.yml

@@ -0,0 +1,38 @@
+name: CI-v3
+on:
+  pull_request:
+    branches:
+      - v3
+  push:
+    branches:
+      - v3
+    tags: '*'
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.10'
+          - '1'  # This automatically expands to the latest stable 1.x release.
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

CHANGELOG.md

@@ -1,12 +1,25 @@
 PrettyTables.jl Changelog
 =========================
 
+Version 3.0.0
+-------------
+
+- ![BREAKING][badge-breaking] This new version contains many breaking changes. The API was
+  almost entirely redesigned to improve the package maintainability and to add new features.
+  Please, check the documentation for more details.
+
 Version 2.4.0
 -------------
 
 - ![Info][badge-info] Bump StringManipulation.jl version.
 - ![Deprecation][badge-deprecation] Drop support for Julia versions lower than 1.10.
 
+Version 2.3.3
+-------------
+
+- ![Info][badge-info] Bump StringManipulation.jl version.
+- ![Deprecation][badge-deprecation] Drop support for Julia versions lower than 1.10.
+
 Version 2.3.2
 -------------
 

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2019-2024: Ronan Arraes Jardim Chagas
+Copyright (c) 2019-2025: Ronan Arraes Jardim Chagas
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

Project.toml

@@ -11,6 +11,7 @@ LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 StringManipulation = "892a3eda-7b42-436c-8928-eab12a02cf0e"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
@@ -22,6 +23,7 @@ Markdown = "1.10"
 OffsetArrays = "1"
 PrecompileTools = "1"
 Printf = "1.10"
+REPL = "1.10"
 Reexport = "0.2, 1"
 StringManipulation = "0.4"
 Tables = "0.2, 1"

README.md

@@ -7,8 +7,17 @@
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![DOI](https://zenodo.org/badge/165340490.svg)](https://zenodo.org/doi/10.5281/zenodo.10015722)
 
-This package has the purpose to print data in matrices in a human-readable format. It was
-inspired in the functionality provided by https://ozh.github.io/ascii-tables/
+This package has the purpose to print data in matrices using different backends. It was
+orizinally inspired in the functionality provided by
+[ASCII Tables](https://ozh.github.io/ascii-tables/).
+
+**PrettyTables.jl** allows to print the data together with some table sections. They can be
+modified by the user to obtain the desired output. The sections currently available are:
+
+![Table Design](./docs/src/assets/table_design.png)
+
+This design is heavily inspired by the R's package [gt](https://github.com/rstudio/gt/) but
+the API is highly different due to the differences between the R and Julia languages.
 
 ## Installation
 
@@ -19,42 +28,110 @@ julia> Pkg.add("PrettyTables")
 
 ## Example
 
+We present in the following an example showing some of the features available in
+**PrettyTables.jl**.
+
 ```julia
-julia> using PrettyTables
+julia> using PrettyTables, StyledStrings
+
+# == Creating the Table ====================================================================
+
+julia> v1_t = 0:5:20
+
+julia> v1_a = ones(length(v1_t)) * 1.0
+
+julia> v1_v = @. 0 + v1_a * v1_t
+
+julia> v1_d = @. 0 + v1_a * v1_t^2 / 2
+
+julia> v2_t = 0:5:20
+
+julia> v2_a = ones(length(v2_t)) * 0.75
+
+julia> v2_v = @. 0 + v2_a * v2_t
+
+julia> v2_d = @. 0 + v2_a * v2_t^2 / 2
 
-julia> t = 0:1:20
-0:1:20
+julia> table = [
+  v1_t v1_a v1_v v1_d
+  v2_t v2_a v2_v v2_d
+];
 
-julia> data = hcat(t, ones(length(t) ), t, 0.5.*t.^2);
+# == Configuring the Table =================================================================
 
-julia> header = (
-           ["Time", "Acceleration", "Velocity", "Distance"],
-           [   "s",     "[m / s²]",  "[m / s]",      "[m]"]
-       )
-(["Time", "Acceleration", "Velocity", "Distance"], ["s", "[m / s²]", "[m / s]", "[m]"])
+julia> title = "Table 1. Data obtained from the test procedure."
 
-julia> hl_p = Highlighter(
-           (data, i, j) -> (j == 4) && (data[i, j] > 9),
-           crayon"blue bold"
-       );
+julia> subtitle = "Comparison between two vehicles"
 
-julia> hl_v = Highlighter(
-           (data, i, j) -> (j == 3) && (data[i, j] > 9),
-           crayon"red bold"
-       );
+julia> column_labels = [
+    [EmptyCells(2), MultiColumn(2, "Estimated Data")],
+    ["Time (s)", "Acceleration", "Velocity", "Position"],
+]
+
+julia> units = [
+  styled"{(foreground=gray):[s]}",
+  styled"{(foreground=gray):[m / s²]}",
+  styled"{(foreground=gray):[m / s]}",
+  styled"{(foreground=gray):[m]}",
+]
+
+julia> push!(column_labels, units)
+
+julia> merge_column_label_cells = :auto
+
+julia> row_group_labels = [
+    1 => "Vehicle #1",
+    6 => "Vehicle #2"
+]
+
+julia> summary_rows = [
+    (data, j) -> maximum(@views data[ 1:5, j]),
+    (data, j) -> maximum(@views data[6:10, j]),
+]
+
+julia> summary_row_labels = [
+    "Max. for Vehicle #1",
+    "Max. for Vehicle #2",
+]
+
+julia> footnotes = [
+    (:column_label, 1, 3) => "Estimated data based on the acceleration measurement."
+]
+
+julia> highlighters = [
+    TextHighlighter((data, i, j) -> (j == 3) && (data[i, j] > 10), crayon"fg:red bold")
+    TextHighlighter((data, i, j) -> (j == 4) && (data[i, j] > 10), crayon"fg:blue bold")
+]
+
+julia> table_format = TextTableFormat(;
+    # Remove vertical lines.
+    @text__no_vertical_lines
+)
+
+julia> style = TextTableStyle(
+    column_label                   = crayon"bold",
+    first_line_merged_column_label = crayon"fg:yellow bold underline",
+    footnote                       = crayon"fg:cyan",
+    row_group_label                = crayon"fg:magenta bold",
+    subtitle                       = crayon"italics",
+    title                          = crayon"fg:yellow bold",
+)
 
-julia> hl_10 = Highlighter(
-           (data, i, j) -> (i == 10),
-           crayon"fg:white bold bg:dark_gray"
-       );
+# == Printing the Table ====================================================================
 
 julia> pretty_table(
-    data;
-    formatters    = ft_printf("%5.2f", 2:4),
-    header        = header,
-    header_crayon = crayon"yellow bold",
-    highlighters  = (hl_10, hl_p, hl_v),
-    tf            = tf_unicode_rounded
+    table;
+    column_labels,
+    footnotes,
+    highlighters,
+    merge_column_label_cells,
+    row_group_labels,
+    style,
+    subtitle,
+    summary_row_labels,
+    summary_rows,
+    table_format,
+    title,
 )
 ```
 

docs/Project.toml

@@ -4,6 +4,7 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
+PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -6,25 +6,30 @@ makedocs(
     format = Documenter.HTML(
         prettyurls = !("local" in ARGS),
         canonical = "https://ronisbr.github.io/PrettyTables.jl/stable/",
+        size_threshold_warn = 1024 * 1024 * 1024,
+        size_threshold = 10 * 1024 * 1024 * 1024,
     ),
     sitename = "Pretty Tables",
     authors = "Ronan Arraes Jardim Chagas",
+    warnonly = [:missing_docs, :cross_references],
     pages = [
-        "Home"               => "index.md",
-        "Usage"              => "man/usage.md",
-        "Back Ends"          => Any[
-            "Text"           => "man/text_backend.md",
-            "HTML"           => "man/html_backend.md",
-            "LaTeX"          => "man/latex_backend.md",
-            "Markdown"       => "man/markdown_backend.md",
+        "Home"                        => "index.md",
+        "Quick Start"                 => "man/quick_start.md",
+        "Usage"                       => "man/usage.md",
+        "Back Ends"                   => Any[
+            "Text"                    => Any[
+                "Text Backend"        => "man/text/text_backend.md",
+                "Pre-defined Formats" => "man/text/predefined_formats.md",
+                "Examples"            => "man/text/text_examples.md",
+            ],
+            "HTML"                    => "man/html/html_backend.md",
+            "LaTeX"                   => Any[
+                "LaTeX Backend"       => "man/latex/latex_backend.md",
+                "Examples"            => "man/latex/latex_examples.md",
+            ],
+            "Markdown"                => "man/markdown/markdown_backend.md",
         ],
-        "Alignment"          => "man/alignment.md",
-        "Formatters"         => "man/formatters.md",
-        "Examples"           => Any[
-            "Text Back End"  => "man/text_examples.md",
-            "HTML Back End"  => "man/html_examples.md",
-        ],
-        "Library"            => "lib/library.md",
+        "Library"                     => "lib/library.md",
     ]
 )