The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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.