/ 
BorderStyle-2.0.1
River stage three • 3 direct dependents • 329 total dependents
/ BorderStyle

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.