From 5891b18fda8706297b88484abd539f03653b1495 Mon Sep 17 00:00:00 2001 From: masukomi Date: Sat, 4 Feb 2023 16:58:10 -0500 Subject: [PATCH] updated README and Changes & Meta6 --- Changes | 10 ++++++ META6.json | 12 ++++---- README.md | 89 ++++++++++++++++++++++++++++++++++++------------------ 3 files changed, 75 insertions(+), 36 deletions(-) diff --git a/Changes b/Changes index f513bdd..7f7ddc7 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,15 @@ Revision history for CLI::Graphing::BarChart +## [2.0.0] - 2023-02-4 +ADDED +- Horizontal graphs! 🎉 + +CHANGED +- CLI::Graphing::BarChart is now Terminal::Graphing::BarChart + +Version number bumped to 2.0.0 because the namespace change +is a breaking change. + ## [1.0.0] - 2023-01-04 ADDED - Everything! 🎉 diff --git a/META6.json b/META6.json index 0575456..7155496 100644 --- a/META6.json +++ b/META6.json @@ -7,16 +7,16 @@ "build-depends": [ ], "depends": [ - "Listicles" + "Listicles:ver<1.6.0+>" ], "description": "A library for generating command line bar charts", "license": "AGPL-3.0-or-later", - "name": "CLI::Graphing::BarChart", + "name": "Terminal::Graphing::BarChart", "perl": "6.d", "provides": { - "CLI::Graphing::BarChart::Core": "lib/CLI/Graphing/BarChart/Core.rakumod", - "CLI::Graphing::BarChart::Horizontal": "lib/CLI/Graphing/BarChart/Horizontal.rakumod", - "CLI::Graphing::BarChart::Vertical": "lib/CLI/Graphing/BarChart/Vertical.rakumod" + "CLI::Graphing::BarChart::Core": "lib/Terminal/Graphing/BarChart/Core.rakumod", + "CLI::Graphing::BarChart::Horizontal": "lib/Terminal/Graphing/BarChart/Horizontal.rakumod", + "CLI::Graphing::BarChart::Vertical": "lib/Terminal/Graphing/BarChart/Vertical.rakumod" }, "resources": [ ], @@ -27,5 +27,5 @@ ], "test-depends": [ ], - "version": "1.0.0" + "version": "2.0.0" } diff --git a/README.md b/README.md index db2d0ed..675ba55 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ Terminal::Graphing::BarChart is a simple library to let you produce bar graphs on the command line. It takes special care to give you good looking output. + ![example graph](../readme_images/images/social_media_preview.png) Currently limited to vertical bar charts. See the end of this document for future plans & contribution guidelines. @@ -13,11 +14,12 @@ SYNOPSIS ## Common Usage Example ```raku +# VERTICAL BAR CHART use Terminal::Graphing::BarChart::Vertical; my $x_and_y_axis_graph = Terminal::Graphing::BarChart::Vertical.new( data => [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100], - graph_height => 10, + bar_length => 10, x_axis_labels => , y_axis_labels => <0 1 2 3 4 5 6 7 8 9> ); @@ -29,48 +31,80 @@ $x_and_y_axis_graph.generate(); $x_and_y_axis_graph.print(); ``` -Note that the 0 x 0 point of this graph is the bottom left corner. -Data and labels start from there and move outwards. +Note that for a _vertical_ graph the 0 x 0 point of this graph is the bottom left corner. +Data and labels start from there and move outwards. BUT for a _horizontal_ graph the 0 x 0 point is the top left corner. + +``` raku + +my $horizontal_graph = Terminal::Graphing::BarChart::Horizontal.new( + data => [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100], + bar_length => 20, + x_axis_labels => , + y_axis_labels => +); +# to get the string version of the graph +$horizontal_graph.generate(); + +# to print the graph to Standard Out +$horizontal_graph.print(); +``` + +There are 3 notable restrictions in the horizontal graph + +1. x axis labels can't be longer than 1 character +2. `bar_length` must be evenly divisible by the number of x axis labels. +3. the x axis labels will be spread evenly across `bar_length` characters of width. + Folks using Arabic & other Right-to-Left are encouraged to make a PR to support reversed graphs. ## Required Attributes -When creating a graph there are two required keys. `graph_height` and `data`. +When creating a graph there are two required keys. `bar_length` and `data`. -`graph_height` is how tall you wish the core graph to be in lines. -This does not include the additional lines for the x axis or its dividing line. +`bar_length` is how tall or wide you wish the core graph's bars to be (in characters). +This does not include the additional lines for labels or the lines separating them +from the graph. `data` is an array of numbers. Each is expected to be a percentage from 0 to 100. -100 create a vertical bar `graph_height` lines tall. 0 will create an empty bar. +100 create a vertical bar `bar_length` lines tall. 0 will create an empty bar. -Note, there _will_ be rounding issues if your `graph_height` is anything other than +Note, there _will_ be rounding issues if your `bar_length` is anything other than an even multiple of 100. This is ok. -Just to set expectations, if for example, you specify a `graph_height` -of 10 that means there are only 10 vertical elements to each bar. If +Just to set expectations, if for example, you specify a `bar_length` +of 10 that means there are only 10 vertical/horizontal elements to each bar. If one of your data points is 7 you'll end up with an empty bar because that's less than the number needed to activate the 1st element (10). ## Optional Attributes -`x_axis_labels` This is an array of labels that must be equal in length +`x_axis_labels` This is an array of labels for the x axis. +In the vertical bar chart it must be equal in length to the number of data points. If you want some of your bars to be unlabeled -then specify a space for that "label". +then specify a space for that "label". In the horizontal bar chart it must be +a number that's `bar_length` can be evenly divided by. In the horizontal bar +chart they must also be no longer than 1 character. +For the horizontal graph I recommend just making it the same number of elements +as the `bar_length`. That way you can precisely specify where each label appears. -`y_axis_labels` This is an array of labels that must be equal in length -to the `graph_height` (one label per row). Again, if you want some of -the points to be unlabeled, you should use a space character. -Note that the 0 x 0 point of this graph is the bottom left. So your list +`y_axis_labels` This is an array of labels for the y axis. +In the vertical bar graph it must be equal in length +to the `bar_length` (one label per row). Again, if you want some of +the points to be unlabeled, you should use a space character. In the horizontal graph it can be less. + +Note that the 0 x 0 point of the vertical graph is the bottom left. So its list of `y_axis_labels` will go from bottom up. This corresponds to how the -`data` and `x_axis_labels` go from left to right. +`data` and `x_axis_labels` go from left to right. In the horizontal bar graph it's top left +so data moves from that column out. -`space_between_columns` This is a `Bool` which defaults to `True`. If you -set it to `False` the system will _not_ introduce a space between each column. -This works fine, and may be a good choice if you have a large number of data points, -but for short graphs it's almost always worse looking. +In the Vertical bar graph you can specify `space_between_columns` This is a +`Bool` which defaults to `True`. If you set it to `False` the system will _not_ +introduce a space between each column. This works fine, and may be a good +choice if you have a large number of data points, but for short graphs it's +almost always worse looking. ### Advice From a purely visual perspective it is not recommended that you use @@ -81,9 +115,11 @@ length of the longest label. `y_axis_labels` should be fine regardless of length. They are right-aligned, and just shove the graph farther to the right. -I would not recommend generating a graph that's more than 10 characters high. +I would not recommend generating a vertical graph that's more than 10 characters high. +I would recommend making a horizontal graph that's >=20 characters wide. Otherwise they +look too squished. -See `tester.raku` for examples. +See `vertical-graph-tester.raku` and `horizontal-graph-tester.raku` for examples. ## Legend @@ -95,13 +131,6 @@ to generate a legend that explains your x axis. # Future + Contributing -## Future Plans -This actually starts out by generating a horizontal graph and then rotates it, and adds the X axis and divider lines (see inline comments). - -The plan is to add `Terminal::Graphing::BarChart::Horizontal` to this library, by extracting the initial bit of `Vertical` into a common module and then building `Horizontal` around that. - -This will happen as soon as I need it, or _you_ need it enough to make a Pull Request. - ## Contributing Please do. All I ask is that you include unit tests that cover whatever changes or additions you make, and that you're fine with your contributions being distributed under the AGPL.