The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
BorderStyle-2.0.8
River stage three • 3 direct dependents • 300 total dependents
++
/ BorderStyle

NAME

BorderStyle - Border styles

SPECIFICATION VERSION

2

VERSION

This document describes version 2.0.8 of BorderStyle (from Perl distribution BorderStyle), released on 2022-01-26.

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( [ %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($y, $x, $n, \%char_args);

    Get border character at a particular $y and $x position, duplicated $n times (defaults to 1). Per-character arguments can also be passed. Known per-character arguments: rownum (uint, row number, starts from 0), colnum (uint, column number, starts from 0).

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.

  • 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 (if drawing header rows)
   [E, F, G],                # 1 Vertical separators for header row
   [H, I, J, K, a, b, c, d], # 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

   [Ȧ, Ḃ, Ċ, Ḋ],             # 6 Top border characters (if not drawing header rows)
   [Ṣ, Ṭ, Ụ, Ṿ],             # 7 Bottom border characters (if drawing header rows but there are no data rows)

   [Ȯ, Ṗ, Ꝙ, Ṙ, ė, ḟ, ġ, ḣ], # 8 Separator between header rows
 ]

    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
 ȮṖṖṖꝘṖṖṖṘ        #8 Separator between header rows (if there are multiple header rows)
 E   F   G        #1 (another header row, if there are multiple header rows)
 HIIIJIIIK        #2 Separator between last 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 (another data row)
 STTTUTTTV        #5 Bottom border characters

    When not drawing header rows, these characters will be used instead:

     ȦḂḂḂĊḂḂḂḊ        #6 Top border characters (when not drawing header rows)
 L   M   N        #3 Vertical separators for data row
 OPPPQPPPR        #4 Separator between data rows
 L   M   N        #3 (another data row)
 OPPPQPPPR        #4 (another separator between data rows)
 L   M   N        #3 (another data row)
 STTTUTTTV        #5 Bottom border characters

    When drawing header rows and there are no data rows, these characters will be used:

     ABBBCBBBD        #0 Top border characters
 E   F   G        #1 Vertical separators for header row
 ȮṖṖṖꝘṖṖṖṘ        #8 Separator between header rows (if there are multiple header rows)
 E   F   G        #1 (another header row, if there are multiple header rows)
 ṢṬṬṬỤṬṬṬṾ        #7 Bottom border characters (when there are header rows but no data row)

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

     ABBBCBBBCBBBCBBBD  ^
 E       F   F   G  |
 ȮṖṖṖḟṖṖṖꝘṖṖṖėṖṖṖṘ  |      # ė=no top line, ḟ=no bottom line
 E       F   F   G  |
 ȮṖṖṖṖṖṖṖꝘṖṖṖeṖṖṖṘ  +------> header area
 E       F       G  |
 E       ġṖṖṖṖṖṖṖṘ  |      # ġ=no left line
 E       F       G  |
 ȮṖṖṖṖṖṖṖḣ       G  |      # h=on right line
 E       F       G  |
 HIIIaIIIJIIIbIIIK  v ^    # 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    +----> data area
 L       M       N    |
 L       gPPPPPPPR    |    # g=no left line
 L       M       N    |
 OPPPPPPPh       N    |    # h=on right line
 L       M       N    |
 STTTTTTTUTTTTTTTV    v

    In the case of a header-data separator line also having been cut by a multirow cell (note the c and d border character):

     ABBBBBBBBBCBBBBBBBBBBBBBBBBBBBBBCBBBBBBBBBD
 F header1 F       header2       F header3 G
 H         cIIIIIIIIIIaIIIIIIIIIId         J
 L         M header2a M header2b F         N
 OPPPPPPPPPQPPPPPPPPPPQPPPPPPPPPPQPPPPPPPPPR
 M data1a  M data1b   M data1c   M data1d  N
 STTTTTTTTTUTTTTTTTTTTUTTTTTTTTTTUTTTTTTTTTV

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

HOMEPAGE

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

SOURCE

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

HISTORY

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

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, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

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