NAME
BorderStyle - Border styles
SPECIFICATION VERSION
3
VERSION
This document describes version 3.0.3 of BorderStyle (from Perl distribution BorderStyle), released on 2023-07-14.
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 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(%args);Get border character. Arguments include:
char
String. Required. Character name (see below).
repeat
Uint. Optional, defaults to 1.
rownum
Uint, row number of the table cell, starts from 0.
colnum
Uint, column number of the table cell, starts from 0.
for_header_row
Bool. True if drawing a header row, or a separator line between header rows, or a separator between header row and data row.
for_header_header_separator
Bool. True if drawing a separator line between header rows/columns.
for_header_column
Bool. True if drawing a header column.
for_header_data_separator
Bool. True if drawing a separator line between the last header row/column and the first data row/column.
for_data_row
Bool. True if drawing a data row, or a separator line between data rows, or a separator between header row and data row.
for_data_data_separator
Bool. True if drawing a separator line between data rows/columns.
for_data_column
Bool. True if drawing a data column.
for_data_footer_separator
Bool. True if drawing a separator line between the last data row/column and the first footer row/column.
for_footer_row
Bool. True if drawing a footer row, or separator between footer rows, or separator between data row and footer row.
for_footer_column
Bool. True if drawing a footer column.
for_footer_footer_separator
Bool. True if drawing a separator line between footer rows/columns.
Character names. Names of known border characters are given below:
rd_t h_t hd_t ld_t | ____| | | vv v v ┏━━━━━━━━━━━┳━━━━━┳━━━━━┓ v_l -->┃ v_i -->┃ hv_i┃ ┃<-- v_r ┃ ┃ \┃ ┃ ┃ rv_i -->┣━━━━━╋━━━━━┫<-- lv_r ┃ ┃ ┃ ┃ ┃ ┣━━━━━┻━━━━━┫ ┃h_i hd_i ┃ ^ ┃ ┃| | ┃ | ┃ ┃v v ┃ hu_i ┃ rv_l -->┣━━━━━┳━━━━━┫<-- lv_i ┃ ┃ ┃ ┃ ┃ ru_l -->┗━━━━━┻━━━━━┻━━━━━━━━━━━┛ ^ ^ ^ | | | h_b hu_b lu_b no border character name description -- --------------------- ----------- 1 h_b horizontal for top border 2 h_i horizontal for top border 3 h_t horizontal line, for top border 4 hd_t horizontal down line, for top border 5 hd_i horizontal down line, for inside border 6 hu_b horizontal up line, for bottom border 7 hu_i horizontal up line, for inside border 8 hv_i horizontal vertical line, for inside border 9 ld_t left down line, for top border 10 lu_b left up line, for bottom border 11 lv_i left vertical, for inside border 12 lv_r left vertical, for right border 13 rd_t right down line, for top border 14 ru_b right up line, for bottom border 15 rv_i right vertical line, for inside border 16 rv_l right vertical line, for left border 17 v_i vertical line, for inside border 18 v_l vertical line, for left border 19 v_r vertical line, for right borderThe arguments to
get_border_char()will also be passed to border character that is coderef, or to be interpreted by the class'get_border_char()to vary the character.
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.
Border style structure must be put in the %BORDER package variable.
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.
SEE ALSO
Somewhat related: ColorTheme specification, because they are often used together in an application.
HISTORY
v3
Incompatible change.
Remove chars in border style structure and abstract it through get_border_char() to be more flexible, e.g. to allow for footer area, vertical header (header columns), and so on.
Replace the positional arguments in get_border_char() with named arguments to be more flexible. Replace the x and y arguments that refer to character with character name, to be more readable.
v2
The first version of BorderStyle.
Border::Style
Border::Style is an older specification, superseded by this document. The older specification defines border style as just the border style structure, not the class and thus lacks methods like get_struct(), get_args(), and get_border_char().
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 -lIf 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, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2023, 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.