/ 
BorderStyle-2.0.4
River stage three • 3 direct dependents • 329 total dependents
/ BorderStyle

NAME

BorderStyle - Border styles

SPECIFICATION VERSION

2

VERSION

This document describes version 2.0.4 of BorderStyle (from Perl distribution BorderStyle), released on 2021-01-23.

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( [ %args ] );

    Arguments will depend on the border style class (see "args").

  • 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 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, \%args);

    Get border character at a particular $y and $x position, duplicated $n times (defaults to 1). Arguments can be passed to border character that is a coderef.

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

  • 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
  [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
]

    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
HIIIJIIIK        #2 Separator between 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
STTTUTTTV        #5 Bottom border characters

    In table with column and row spans (demonstrates characters a, b, e, f, g, h):

    ABBBCBBBCBBBCBBBD
E       F   F   G
HIIIaIIIJIIIbIIIK         # 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
L       M       N
L       gPPPPPPPR         # g=no left line
L       M       N
OPPPPPPPh       N         # h=on right line
L       M       N
STTTTTTTUTTTTTTTV

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

HISTORY

Border::Style is an older specification, superseded by this document.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/BorderStyle.

SOURCE

Source repository is at https://github.com/perlancar/perl-BorderStyle.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-BorderStyle/issues

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021, 2020 by 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.