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 . 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 . SOURCE Source repository is at . HISTORY Border::Style is an older specification, superseded by this document. AUTHOR perlancar 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 . 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 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.