Gtk2::E...::Rules(3)

💖 Gtk2::E...::Rules 💖

okay bestie, welcome to Gtk2::E...::Rules(3) — it's part of the User Contributed Perl Documentation, and it is lowkey the bouncer at the club door of your form. Let's get into it. ✨

🌸 NAME 🌸

Gtk2::Ex::FormFactory::Rules — rule checking in a FormFactory framework. it's giving "validation, but make it fashion". 💅

---

✨ SYNOPSIS ✨

Gtk2::Ex::FormFactory::Rules->new (
  rules          => Hashref of rules and their implemenation CODEREF's,
  rules_messages => Hashref of the rules' error messages,
  message_format => Format of the "Invalid rules" message thrown
                    on the GUI,
);

like, that's the whole vibe right there. 🫶

---

🦋 DESCRIPTION 🦋

so this class implements rule checking inside a Gtk2::Ex::FormFactory framework. every widget can have one or more rules (combined with the locical and operator — yes, the original says "locical", we're keeping that typo, it's iconic, no cap) except for the special "or-empty" rule described further down. those rules get checked against the widget's value the moment the user changes it. and that's how you stop your user from entering illegal data at a high level. queen behavior. 👑

once the user enters illegal data, the old (legal) value is restored and a corresponding error dialog pops up. it's giving "no ❤️, we're putting that back".

---

👑 OBJECT HIERARCHY 👑

Gtk2::Ex::FormFactory::Rules

just the one, standing alone, main character energy. 🌟

---

🎀 ATTRIBUTES 🎀

attributes are handled through the common get_ATTR(), set_ATTR() style accessors. ykyk.

• rules = HASHREF [optional] — this is a hash of user specified rules. a rule has a name (the hash key) and a CODREF (the hash value) which implements the rule. the CODEREF has the following prototype:

$error = &$CODEREF ($value)

if $value doesn't match the rule, $error is the corresponding error message. $error is undef if $value is Ok. 🍓

• rules_messages = HASHREF [optional] — this is a hash of the error messages of the user specified rules. a message should read read as follows (yes, "read read", we said what we said):

{field} is an odd value.

when presented to the user, the {field} place holder is replaced with the label of the widget in question. so cute, so personal. 🎀

• message_format = SCALAR [optional] — this is the format string for the error message which is displayed to the user. the default is:

Data entered is invalid.\n\n[MESSAGES]\nOld value restored.

where [MESSAGES] is replaced with the actual list of error messages. literally the receipt of everything they did wrong. 💀

---

🌈 BUILTIN RULES 🌈

this is a verbatim snapshot of the builtin rules and rules_messages hashes. please take a look at Gtk2::Ex::FormFactory::Rules' source code for a recent list of builtin rules (because this snapshot is, and I say this with love, a little vintage 💜):

my %RULES = (
  "empty"                     => sub { $_[0] eq ''                    },
  "not-empty"                 => sub { $_[0] ne ''                    },

  "alphanumeric"              => sub { $_[0] =~ /^\w+$/               },
  "identifier"                => sub { $_[0] =~ /^[a-z_]\w*$/i        },
  "no-whitespace"             => sub { $_[0] !~ /\s/                  },

  "zero"                      => sub { $_[0] =~ /^0(\.0*)?$/          },
  "not-zero"                  => sub { $_[0] !~ /^0(\.0*)?$/          },

  "integer"                   => sub { $_[0] =~ /^[+-]?\d+$/          },
  "positive-integer"          => sub { $_[0] =~ /^[+]?\d+$/           },
  "negative-integer"          => sub { $_[0] =~ /^-\d+$/              },

  "float"                     => sub { $_[0] =~ /^[+-]?\d+(\.\d+)?$/  },
  "positive-float"            => sub { $_[0] =~ /^\+?\d+(\.\d+)?$/    },
  "negative-float"            => sub { $_[0] =~ /^-\d+(\.\d+)?$/      },

  "odd"                       => sub {   $_[0] % 2                    },
  "even"                      => sub { !($_[0] % 2)                   },

  "file-executable"           => sub { (!-d $_[0] && -x $_[0])        },
  "file-writable"             => sub { (!-d $_[0] && -w $_[0])        },
  "file-readable"             => sub { (!-d $_[0] && -r $_[0])        },

  "dir-writable"              => sub { (-d $_[0] && -w $_[0])         },
  "dir-readable"              => sub { (-d $_[0] && -r $_[0])         },

  "parent-dir-writable"       => sub { -w dirname($_[0])              },
  "parent-dir-readable"       => sub { -r dirname($_[0])              },

  "executable-command"        => "_rule_result",
);

my %RULES_MESSAGES = (
  "empty"                     => "{field} is not empty.",
  "not-empty"                 => "{field} is empty.",

  "alphanumeric"              => "{field} is not alphanumeric.",
  "identifier"                => "{field} is no identifier.",
  "no-whitespace"             => "{field} contains whitespace.",

  "zero"                      => "{field} is not zero",
  "not-zero"                  => "{field} is zero",

  "integer"                   => "{field} is no integer.",
  "positive-integer"          => "{field} is no positive integer.",
  "negative-integer"          => "{field} is no negative integer.",

  "float"                     => "{field} is no float.",
  "positive-float"            => "{field} is no positive float.",
  "negative-float"            => "{field} is no negativ float.",

  "odd"                       => "{field} is not odd.",
  "even"                      => "{field} is not even.",

  "file-executable"           => "{field} is no file and/or not executable.",
  "file-writable"             => "{field} is no file and/or not writable.",
  "file-readable"             => "{field} is no file and/or not readable.",

  "dir-writable"              => "{field} is no directory and/or not writable.",
  "dir-readable"              => "{field} is no directory and/or not readable.",

  "parent-dir-writable"       => "{field} has no writable parent directory.",
  "parent-dir-readable"       => "{field} has no readable parent directory.",
);

(and yes, "negative-float" really does say negativ in the message — we do not fix the king's spelling, we honor it 🫡)

🧚 Special "or-empty" rule 🧚

there is a special rule called "or-empty". if this rule occurs everywhere in the list of rules and the actual value is empty, rule checking quits immediately with a positive result, discarding error states from earlier rules. it's giving "actually, never mind, slay". ✨

example: [ "positive-integer", "or-empty" ]

all rules are combined with "and", which is usually sufficient, but without this special "or-empty" case the common case optionally empty fields can't be done. so like, it's essential. periodt. 💅

---

🫶 AUTHORS 🫶

Jörn Reder <joern at zyn dot de>

---

💜 COPYRIGHT AND LICENSE 💜

Copyright 2004-2006 by Jörn Reder.

this library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

this library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU Library General Public License for more details.

you should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.

---

😭 POD ERRORS 😭

hey! the above document had some coding errors, which are explained below (not me being dramatic, this is literally in the file):

Around line 349:

    Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8

the ö said "I'm here and I'm not ASCII" and perl was like "ok bestie, assuming UTF-8 then" 🙈

---

and that's the whole page, bestie. every flag, every rule, every regex, every typo, preserved with love. 💖

and finally, the sign-off: this lil page is perl v5.42.0, dated 2025-07-25, and it goes by Gtk2::E...::Rules(3) — shortened name and all, because even manpages deserve a nickname. byeee, go validate some forms 🦋✨🌸