SVN::N...y::HTML(3pm)

✨ NAME ✨

SVN::Notify::HTML — Subversion activity HTML notification 💌

okay so real talk: this is the 3pm manpage for SVN::Notify::HTML, and it lives in the User Contributed Perl Documentation section, which is basically the group chat of Perl docs. Anyway. Let's get into it bestie 💅

---

🦋 SYNOPSIS 🦋

Use svnnotify in post-commit, like this:

svnnotify --repos-path "$1" --revision "$2" \
  --to developers@example.com --handler HTML [options]

Or use the class in a custom script, if you're feeling main character energy:

use SVN::Notify::HTML;

my $notifier = SVN::Notify::HTML->new(%params);
$notifier->prepare;
$notifier->execute;

---

🌸 DESCRIPTION 🌸

This subclass of SVN::Notify sends HTML formatted email messages for Subversion activity, instead of the default plain text. Not me making your commit emails actually cute 💖

---

🎀 PREREQUISITES 🎀

On top of the modules that SVN::Notify already needs, this class also requires:

• HTML::Entities

---

🧚 USAGE 🧚

To use SVN::Notify::HTML, literally just follow the instructions in SVN::Notify, but when you're using svnnotify, specify --handler HTML. That's it. That's the whole vibe check 🫶

---

👑 CLASS INTERFACE 👑

🌈 Constructor

new

my $notifier = SVN::Notify::HTML->new(%params);

Constructs and returns a new SVN::Notify object. Every parameter that SVN::Notity supports is supported here too, but SVN::Notify::HTML also supports a few extra parameters:

• linkize

svnnotify --linkize

A boolean attribute that says whether or not to "linkize" the SVN log message — meaning, turn any URLs or email addresses in the log message into links. Iconic, honestly.

• css_url

svnnotify --css-url http://example.com/svnnotify.css

URL for a CSS file that can style the HTML output by SVN::Notify::HTML or its subclasses. Heads up: the URL gets added to the output via a <link rel="stylesheet"> tag after the CSS generated by SVN::Notify::HTML or its subclasses. What that means is that the CSS file specified by css_url doesn't need to completely style the HTML — it just needs to override the default settings. This approach nicely takes advantage of the "cascading" abilities of CSS. She's clever like that 💅

• ticket_map

svnnotify --ticket-map '(BUG-(\d+))=http://bugs.example.com/?show=%s'

This attribute is inherited from SVN::Notify, but its semantics are slightly different: the regular expression passed as the regular expression used for the key should return two matches instead of one — the text to link and the ticket ID itself. For example, '(BUG-(\d+))' will match "BUG-1234567", and "BUG-1234567" will be used for the link text, while "1234567" will be used to fill in the ticket_url format string. The first set of parentheses captures the whole string, while the parentheses around \d+ match the number only. Also note that it is wise to use \b on either side of the regular expression to ensure you don't get spurious matches. So a better version would be '\b(BUG-(\d+))\b'.

As a fallback, if your regular expression returns only a single match string, it will be used both for the link text and for the ticket URL generated from ticket_url. For example, '\bBUG-(\d+)\b' would make a link only of the number in 'BUG-1234567', since only the number has been captured by the regular expression. But two matches are of course recommended (and likely to work better, as well).

You can use more complicated regular expressions if commit messages are likely to format ticket numbers in various ways. For example, this regular expression:

\b\[?\s*(Ticket\s*#\s*(\d+))\s*\]?\b'

Will match:

 String Matched           Link Text        Ticket Number
--------------------|--------------------|---------------
 [Ticket#1234]         [Ticket#1234]       1234
 [ Ticket # 1234 ]     [ Ticket # 1234 ]   1234
 Ticket #1234          Ticket #1234        1234
 Ticket # 1234         Ticket  #1234       1234

In any of these cases, you can see that the match is successful, properly creates the link text (simply using the text as typed in by the committer), and correctly extracts the ticket number for use in the URL.

To learn more about the power of Regular expressions, I highly recommend Mastering Regular Expressions, Second Edition, by Jeffrey Friedl. 📚

• wrap_log

svnnotify --wrap-log

A boolean attribute that says whether or not to wrap the log message in the output HTML. By default, log messages are not wrapped, on the assumption that they should appear exactly as typed. But if that's not the case for you, specify this option to wrap the log message.

💫 Class Methods

content_type

Returns the content type of the notification message, text/html. Used to set the Content-Type header for the message. Simple, clean, slays.

---

🦄 INSTANCE INTERFACE 🦄

🌟 Instance Methods

start_html

$notifier->start_html($file_handle);

This method starts the HTML of the notification message. It outputs the opening <html>, <head>, and <body> tags. Note that if the language attribute is set to a value, it will be specified in the <html> tag.

All of the HTML will be passed to any start_html output filters. See Writing Output Filters for details on filters.

start_body

This method starts the body of the HTML notification message. It first calls start_html(), and then outputs the <style> tag, calling output_css() between them. It then outputs an opening <div> tag.

If the header attribute is set, start_body() outputs it between <div> tags with the ID "header". Furthermore, if the header happens to start with the character <, start_body() assumes that it contains valid HTML and therefore will not escape it.

If a start_body output filter has been specified, it will be passed the lines with the <div> tag and the header. To filter the CSS, use a css filter, and to filter the declaration of the HTML document and its <head> section, use a start_html filter. See Writing Output Filters for details on filters.

output_css

$notifier->output_css($file_handle);

This method starts outputs the CSS for the HTML message. It is called by start_body(), and which wraps the output of output_css() in the appropriate <style> tags.

An output filter named css may be added to modify the output of CSS. The filter subroutine name should be css and expect an array reference of lines of CSS. See Writing Output Filters for details on filters.

output_metadata

$notifier->output_metadata($file_handle);

This method outputs a definition list containing the meta data of the commit, including the revision number, author (user), and date of the revision. If the revision_url attribute has been set, then the appropriate URL for the revision will be used to turn the revision number into a link.

If there are any log_message filters, this method will do no HTML formatting, but redispatch to SVN::Notify::output_metadata. See Writing Output Filters for details on filters.

output_log_message

$notifier->output_log_message($file_handle);

Outputs the commit log message in <pre> tags, and the label "Log Message" in <h3> tags. If the bugzilla_url attribute is set, then any strings like "Bug 2" or "bug # 567" will be turned into links.

If there are any log_message filters, the filters will be assumed to escape the HTML, create inline links, and link ticket URLs. Otherwise, this method will do those things. See Writing Output Filters for details on filters.

output_file_lists

$notifier->output_log_message($file_handle);

Outputs the lists of modified, added, deleted, files, as well as the list of files for which properties were changed as unordered lists. The labels used for each group are pulled in from the file_label_map() class method and output in <h3> tags.

If there are any file_lists filters, this method will do no HTML formatting, but redispatch to SVN::Notify::output_file_lists. See Writing Output Filters for details on filters.

end_body

$notifier->end_body($file_handle);

Closes out the body of the email by outputting the closing </body> and </html> tags. Designed to be called when the body of the message is complete, and before any call to output_attached_diff().

If the footer attribute is set, end_body() outputs it between <div> tags with the ID "footer". Furthermore, if the footer happens to end with the character <, end_body() assumes that it contains valid HTML and therefore will not escape it.

All of the HTML will be passed to any end_body output filters. See Writing Output Filters for details on filters.

output_diff

$notifier->output_diff($out_file_handle, $diff_file_handle);

Sends the output of svnlook diff to the specified file handle for inclusion in the notification message. The diff is output between <pre> tags, and each line of the diff file is escaped by HTML::Entities::encode_entities(). The diff data will be read from $diff_file_handle and printed to $out_file_handle.

If there are any diff filters, this method will do no HTML formatting, but redispatch to SVN::Notify::output_diff. See Writing Output Filters for details on filters.

💜 Accessors

In addition to those supported by SVN::Notify, SVN::Notify::HTML supports the following accessors:

linkize

my $linkize = $notifier->linkize;
$notifier = $notifier->linkize($linkize);

Gets or sets the value of the linkize attribute.

css_url

my $css_url = $notifier->css_url;
$notifier = $notifier->css_url($css_url);

Gets or sets the value of the css_url attribute.

---

🔥 SEE ALSO 🔥

• SVN::Notify

---

🌈 AUTHOR 🌈

David E. Wheeler <david@justatheory.com>

---

📜 COPYRIGHT AND LICENSE 📜

Copyright (c) 2004-2018 David E. Wheeler. Some Rights Reserved.

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

---

and that's the whole page bestie, no cap 🫶 This one came from the User Contributed Perl Documentation collection and was generated by perl v5.36.0 on 2022-11-20. Go forth and send pretty HTML commit emails, you absolute icon 👑💖✨