/ 
Slack-BlockKit-0.002
River stage zero No dependents
/ Slack::BlockKit::Sugar

NAME

Slack::BlockKit::Sugar - sugar for building Block Kit structures easily (start here!)

VERSION

version 0.002

OVERVIEW

This module exports a bunch of functions that can be composed to build Block Kit block collections, which can then be easily turned into a data structure that can be serialized.

If you learn to use this library, you can generally ignore the other dozen (more!) modules in this distribution. On the other hand, you must more or less understand how Block Kit works, which means reading the BlockKit documentation at Slack's API site.

The key is to have a decent idea of the Block Kit structure you want. Knowing that, you can look at the list of functions provided by this library and compose them together. Start with a call to blocks, passing the result of calling other generators to it. In the end, you'll have an object on which you can call ->as_struct.

For example, to produce something basically equivalent to this Markdown (well, mrkdwn):

Here is a *safe* link: **[click me](https://rjbs.cloud/)**
* it will be fun
* it will be cool 🙂
* it will be enough

You can use this set of calls to the sugar functions:

blocks(
  richblock(
    richsection(
      "Here is a ", italic("safe"), " link: ",
      link("https://fastmail.com/", "click me", { style => { bold => 1 } }),
    ),
    ulist(
      "it will be fun",
      richsection("it will be cool", emoji('smile')),
      "it will be enough",
    ),
  )
);

Importing the functions

This library uses Sub::Exporter for exporting its functions. That means that they can be renamed during import. Since the names of these functions are fairly generic, you might prefer to write this:

use Slack::BlockKit::Sugar -all => { -prefix => 'bk_' };

This will import all the sugar functions with their names prefixed by bk_. So, for example, italic will be bk_italic.

PERL VERSION

This module should work on any version of perl still receiving updates from the Perl 5 Porters. This means it should work on any version of perl released in the last two to three years. (That is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.)

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

FUNCTIONS

blocks

my $block_col = blocks( @blocks );

This returns a Slack::BlockKit::BlockCollection, which just collects blocks and will return their serializable structure form in an arrayref when ->as_struct is called on it.

If any argument is a non-reference, it will be upgraded to a "section" block containing a single "mrkdwn" text object.

This means the simplest non-trivial message you could send is something like:

blocks("This is a *formatted* message.")->as_struct;

richblocks

my $rich_text_block = richblocks( @rich_elements );

This returns a Slack::BlockKit::Block::RichText, representing a rich_text-type block. It's a bit annoying that you need it, but you do. You'll also need to pass one or more rich text elements as arguments, something like this:

blocks(
  richblocks(
    section("This is ", italic("very"), " important."),
  ),
);

Each non-reference passed in the list of rich text elements will be turned into a rich text objects inside its own section object.

richsection

$rich_text_section = richsection( @elements );

This returns a single rich text section object containing the passed elements as its elements attribute value.

Non-reference values in @elements be converted to rich text objects.

list

my $rich_text_list = list(\%arg, @sections);

This returns a rich text list object. @sections must be a list of rich text sections or plain scalars. Plain scalars will each be converted to a rich text object contained in a rich text section.

The %arg hash is more arguments to the List object constructor. It must contain a style key. For shorthand, see "olist" and "ulist" below.

olist

my $rich_text_list = olist(@sections);
# or
my $rich_text_list = olist(\%arg, @sections);

This is just shorthand for "list", but with a style of ordered. Because that's the only required option for a list, you can omit the leading hashref in calls to olist.

ulist

my $rich_text_list = ulist(@sections);
# or
my $rich_text_list = ulist(\%arg, @sections);

This is just shorthand for "list", but with a style of bullet. Because that's the only required option for a list, you can omit the leading hashref in calls to olist.

preformatted

my $rich_text_pre = preformatted(@elements);
# or
my $rich_text_pre = preformatted(\%arg, @elements);

This returns a new preformatted rich text block object, with the given elements as its elements. Any non-references in the list will be turned into text objects.

The leading hashref, if given, will be used as extra arguments to the block object's constructor.

Beware: The Slack documentation suggests that emoji objects can be present in the list of elements, but in practice, this always seems to get rejected by Slack.

quote

my $rich_text_quote = quote(@elements);
# or
my $rich_text_quote = quote(\%arg, @elements);

This returns a new quoted rich text block object, with the given elements as its elements. Any non-references in the list will be turned into text objects.

The leading hashref, if given, will be used as extra arguments to the block object's constructor.

channel

my $rich_text_channel = channel($channel_id);
# or
my $rich_text_channel = channel(\%arg, $channel_id);

This function returns a channel mention object, which can be used among other rich text elements to "mention" a channel. The $channel_id should be the alphanumeric Slack channel id, not a channel name.

If given, the %arg hash is extra parameters to pass to the Channel constructor.

date

my $rich_text_date = date($timestamp, \%arg);

This returns a rich text date object for the given time (a unix timestamp). If given, the referenced %arg can contain additional arguments to the Date constructor.

Date formatting objects have a mandatory format property. If none is given in %arg, the default is:

\x{200b}{date_short_pretty} at {time}

Why that weird first character? It's a zero-width space, and suppresses the capitalization of "yesterday" (or other words) at the start. This capitalization seems like a bug (or bad design) in Slack.

emoji

my $rich_text_emoji = emoji($emoji_name);

This function returns an emoji object for the named emoji.

my $rich_text_link = link($url);
# or
my $rich_text_link = link($url, \%arg);
# or
my $rich_text_link = link($url, $text_string);
# or
my $rich_text_link = link($url, $text_string, \%arg);

This function returns a rich text link object for the given URL.

If given, the $text_string string will be used as the display text for the link. If not, URL itself will be displayed.

The optional \%arg parameter contains additional attributes to be passed to the Link object constructor.

richtext

my $rich_text = richtext($text_string);
# or
my $rich_text = richtext(\@styles, $text_string);

This function returns a new rich text text object for the given text string. If a an arrayref is passed as the first argument, it is taken as a list of styles to apply to the string. So,

richtext(['bold','italic'], "Hi");

...will produce an object that has this structure form:

{
  type   => 'text',
  styles => { bold => true(), italic => true() },
  text   => "Hi",
}

bold

code

italic

strike

These functions are all called the same way:

my $rich_text = bold($text_string);

They are shortcuts for calling richtext with one style applied: the style of their function name.

user

my $rich_text_user = user($user_id);
# or
my $rich_text_user = user(\%arg, $user_id);

This function returns a user mention object, which can be used among other rich text elements to "mention" a user. The $user_id should be the alphanumeric Slack user id, not a user name.

If given, the %arg hash is extra parameters to pass to the User constructor.

usergroup

my $rich_text_usergroup = usergroup($usergroup_id);
# or
my $rich_text_usergroup = usergroup(\%arg, $usergroup_id);

This function returns a usergroup mention object, which can be used among other rich text elements to "mention" a user group. The $usergroup_id should be the alphanumeric Slack usergroup id, not a group name.

If given, the %arg hash is extra parameters to pass to the UserGroup constructor.

divider

my $divider = divider();

This function returns a divider black object. It takes no parameters, because there is nothing simpler than a divider block.

my $header = header($text_string);
# or
my $header = header($text_obj);
# or
my $header = header(\%arg);

This function returns a header object, which generally has only one property: a text object with type plain_text. To make that easy to build, you can just pass a text string to header and the text object will be created for you.

Alternatively, you can pass in a text object (like you'd get from the text) function or a reference to an hash of arguments. That last form is mostly useful if you need to give the header a block_id.

section

my $section = section($text_obj);
# or
my $section = section($text_string);
# or
my $section = section(\%arg);

This function returns a section object. You can pass it a text object, which will be used as the text property of the section. You can pass it a string string, which will be promoted the a text object and then used the same way.

Otherwise, you'll have to pass a reference to a hash of argument that will be passed to the section constructor. If this function feels weird, it might just be because the section element in Block Kit is a bit weird. Sorry!

mrkdwn

my $text_obj = mrkdown($text_string, \%arg);

This returns a text composition object with a type of mrkdwn and the given string string as its text. The \%arg option is optional. If given, it's extra parameters to pass to the text object constructor.

For plain_text text composition objects, see the text function.

text

my $text_obj = text($text_string, \%arg);

This returns a text composition object with a type of plain_text and the given string string as its text. The \%arg option is optional. If given, it's extra parameters to pass to the text object constructor.

For mrkdwn text composition objects, see the mrkdwn function.

ACHTUNG

This library seems pretty good to me, its author, but it hasn't seen much use yet. As it gets used, it may change in somewhat backward-incompatible ways. Upgrade carefully until this warning goes away!

AUTHOR

Ricardo SIGNES <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.