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.