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

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