NAME
    BorderStyle - Border styles

SPECIFICATION VERSION
    2

VERSION
    This document describes version 2.0.1 of BorderStyle (from Perl
    distribution BorderStyle), released on 2020-06-11.

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::*" or, in the case of
    application-specific border styles, "APP::NAME::BorderStyle::*" where
    "APP::NAME" is an application's namespace.

    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". 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
           [A, b, C, D],  # 0
           [E, F, G],     # 1
           [H, i, J, K],  # 2
           [L, M, N],     # 3
           [O, p, Q, R],  # 4
           [S, t, U, V],  # 5
         ]

        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

        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://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.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 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.