NAME
BorderStyle - Border styles
SPECIFICATION VERSION
2
VERSION
This document describes version 2.0.7 of BorderStyle (from Perl
distribution BorderStyle), released on 2022-01-24.
DESCRIPTION
This document specifies a way to create and use border styles
GLOSSARY
border style class
border style structure
SPECIFICATION
Border style class
Border style class must be put under "BorderStyle::*".
Application-specific border styles should be put under
"BorderStyle::MODULE::NAME::*" or "BorderStyle::APP::NAME::*".
Border style structure must be put in the %BORDER package variable.
Border style class must also provide these methods:
* new
Usage:
my $bs_obj = BorderStyle::NAME->new( [ %style_args ] );
Arguments will depend on the border style class; each border style
class can define what arguments they want to accept.
* get_struct
Usage:
my $bs_struct = BorderStyle::NAME->get_struct;
my $bs_struct = $bs_obj->get_struct;
Provide a method way of getting the "border style structure". Must
also work as a static method. A client can also access the %BORDER
package variable directly.
* get_args
Usage:
my $args = $bs_obj->get_args;
Provide a method way of getting the arguments to the constructor
(the style arguments). The official implementation
BorderStyleBase::Constructor stores this in the 'args' key of the
hash object, but the proper way to access the arguments should be
via this method.
* get_border_char
Usage:
my $str = $bs->get_border_char($y, $x, $n, \%char_args);
Get border character at a particular $y and $x position, duplicated
$n times (defaults to 1). Per-character arguments can also be
passed. Known per-character arguments: "rownum" (uint, row number,
starts from 0), "colnum" (uint, column number, starts from 0).
Border style structure
Border style structure is a DefHash containing these keys:
* v
Float, from DefHash, must be set to 2 (this specification version)
* name
From DefHash.
* summary
From DefHash.
* utf8
Bool, must be set to true if the style uses non-ASCII UTF8 border
character(s).
Cannot be mixed with "box_chars".
* box_chars
Bool, must be set to true if the style uses box-drawing character.
When using box-drawing character, the characters in "chars" property
must be specified using the VT100-style escape sequence without the
prefix. For example, the top-left single border character must be
specified as "l". For more details on box-drawing character,
including the list of escape sequneces, see
<https://en.wikipedia.org/wiki/Box-drawing_character>.
Box-drawing characters must not be mixed with other characters
(ASCII or UTF8).
* args
A hash of argument names and specifications (each specification a
DefHash) to specify which arguments a border style accept. This is
similar to how Rinci::function specifies function arguments. An
argument specification can contain these properties: "summary",
"description", "schema", "req", "default".
* chars
An array. Required. Format for the characters in "chars":
[ # y
#x 0 1 2 3 4 5 6 7
[A, B, C, D], # 0 Top border characters (if drawing header rows)
[E, F, G], # 1 Vertical separators for header row
[H, I, J, K, a, b], # 2 Separator between header row and first data row
[L, M, N], # 3 Vertical separators for data row
[O, P, Q, R, e, f, g, h], # 4 Separator between data rows
[S, T, U, V], # 5 Bottom border characters
[Ȧ, Ḃ, Ċ, Ḋ], # 6 Top border characters (if not drawing header rows)
[Ṣ, Ṭ, Ụ, Ṿ], # 7 Bottom border characters (if drawing header rows but there are no data rows)
[Ȯ, Ṗ, Ꝙ, Ṙ, ė, ḟ, ġ, ḣ], # 8 Separator between header rows
]
When drawing border, below is how the border characters will be
used:
ABBBCBBBD #0 Top border characters
E F G #1 Vertical separators for header row
ȮṖṖṖꝘṖṖṖṘ #8 Separator between header rows (if there are multiple header rows)
E F G #1 (another header row, if there are multiple header rows)
HIIIJIIIK #2 Separator between last header row and first data row
L M N #3 Vertical separators for data row
OPPPQPPPR #4 Separator between data rows
L M N #3 (another data row)
STTTUTTTV #5 Bottom border characters
When not drawing header rows, these characters will be used instead:
ȦḂḂḂĊḂḂḂḊ #6 Top border characters (when not drawing header rows)
L M N #3 Vertical separators for data row
OPPPQPPPR #4 Separator between data rows
L M N #3 (another data row)
OPPPQPPPR #4 (another separator between data rows)
L M N #3 (another data row)
STTTUTTTV #5 Bottom border characters
When drawing header rows and there are no data rows, these
characters will be used:
ABBBCBBBD #0 Top border characters
E F G #1 Vertical separators for header row
ȮṖṖṖꝘṖṖṖṘ #8 Separator between header rows (if there are multiple header rows)
E F G #1 (another header row, if there are multiple header rows)
ṢṬṬṬỤṬṬṬṾ #7 Bottom border characters (when there are header rows but no data row)
In table with column and row spans (demonstrates characters "a",
"b", "e", "f", "g", "h"):
ABBBCBBBCBBBCBBBD ^
E F F G |
ȮṖṖṖḟṖṖṖꝘṖṖṖėṖṖṖṘ | # ė=no top line, ḟ=no bottom line
E F F G |
ȮṖṖṖṖṖṖṖꝘṖṖṖeṖṖṖṘ +------> header area
E F G |
E ġṖṖṖṖṖṖṖṘ | # ġ=no left line
E F G |
ȮṖṖṖṖṖṖṖḣ G | # h=on right line
E F G |
HIIIaIIIJIIIbIIIK v ^ # a=no top line, b=no bottom line
L M M N |
OPPPfPPPQPPPePPPR | # e=no top line, f=no bottom line
L M M N |
OPPPPPPPQPPPePPPR +----> data area
L M N |
L gPPPPPPPR | # g=no left line
L M N |
OPPPPPPPh N | # h=on right line
L M N |
STTTTTTTUTTTTTTTV v
A character can also be a coderef that will be called with "($self,
$y, $x, $n, \%args)". See "Border style character".
Border style character
A border style character can be a single-character string, or a coderef
to allow border style that is context-sensitive.
If border style character is a coderef, it must return a
single-character string and not another coderef. The coderef will be
called with the same arguments passed to "get_border_char".
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/BorderStyle>.
SOURCE
Source repository is at <https://github.com/perlancar/perl-BorderStyle>.
HISTORY
Border::Style is an older specification, superseded by this document.
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull
requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You
can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally
on your system), you can install Dist::Zilla,
Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two
other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
steps required beyond that are considered a bug and can be reported to
me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2022, 2021, 2020 by perlancar
<perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://rt.cpan.org/Public/Dist/Display.html?Name=BorderStyle>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.