NAME

BorderStyle - Border styles

SPECIFICATION VERSION

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

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 border

The 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>.

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.

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 -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, 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 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.