CGI::F...::YAML(3pm)

CGI::F...::YAML(3pm) — bestie edition 💅

okay so you're reading the manual page for CGI::FormBuilder::Source::YAML, part of the User Contributed Perl Documentation ✨. It's a Perl module, it's iconic, and it's about to make your forms read YAML. sit down, grab a boba 🧋, let's go.

---

🌸 NAME 🌸

CGI::FormBuilder::Source::YAML — initialize FormBuilder from a YAML file. no cap, that's the whole vibe 🦋

---

✨ SYNOPSIS ✨

like, the standard entrance:

use CGI::FormBuilder;

my $form = CGI::FormBuilder->new(
   source  => {
       source  => 'form.fb',
       type    => 'YAML',
   },
);

my $lname = $form->field('lname');  # like normal

and then $form->field('lname') just... works. like normal. 💖

---

💜 DESCRIPTION 💜

So this module reads a YAML file (specifically via YAML::Syck, iykyk) that's holding all your FormBuilder config options, and it hands you back a hash that gets fed straight into CGI::FormBuilder->new(). that's the whole job. main character energy fr.

Now — instead of the syntax that CGI::FormBuilder::Source::File reads, this one uses YAML syntax as read by YAML::Syck. Which means, bestie, you have to fully specify the entire data structure. no shortcuts, no halfsies, the whole thing. periodt.

LoadCode is enabled, which is lowkey the best part, because it means you can use YAML syntax to define subroutines 🎀. This is so convenient if you've got a function that generates validation subrefs — for example, the author has one that checks profanity using Regexp::Common. iconic.

validate:
   myfield:
       javascript: /^[\s\S]{2,50}$/
       perl: !!perl/code: >-
           {   My::Funk::fb_perl_validate({
                   min         => 2,
                   max         => 50,
                   profanity   => 'check'
               })->(shift);
           }

---

🦋 POST PROCESSING 🦋

There are two exceptions to "pure YAML syntax" where this module does some post-processing on the result. just two. not me keeping count. 🙈

🌈 REFERENCES (ala CGI::FormBuilder::Source::File) 🌈

You can specify references as string values that start with \&, \$, \@, or \% — same way you can with CGI::FormBuilder::Source::File. And here's the tea: if you've got a full direct package reference, it'll look right there. Otherwise it traverses up the caller stack and takes the first one it finds. slay.

For example — say your code serves multiple sites, and a menu gets different options depending on the server name requested:

# in My::Funk:
our $food_options = {
    www.meats.com   => [qw( beef    chicken horta   fish    )],
    www.veggies.com => [qw( carrot  apple   quorn   radish  )],
};

# in source file:
options: \@{ $My::Funk::food_options->{ $ENV{SERVER_NAME} } }

look at that. chef's kiss. 👑

⭐ EVAL STRINGS ⭐

You can also specify an eval statement. Same example, different route:

options: eval { $My::Funk::food_options->{ $ENV{SERVER_NAME} }; }

The cost either way is about the same — the string is eval'd. 💀

---

🎀 EXAMPLE 🎀

here's a whole YAML file, verbatim, because it's that girl:

method:     GET
header:     0
title:      test
name:       test
action:     /test
submit:     test it
linebreaks: 1

required:
   - test1
   - test2

fields:
   - test1
   - test2
   - test3
   - test4

fieldopts:
   test1:
       type:       text
       size:       10
       maxlength:  32

   test2:
       type:       text
       size:       10
       maxlength:  32

   test3:
       type:       radio
       options:
           -
               - 1
               - Yes
           -
               - 0
               - No

   test4:
       options:    \@test4opts
       sort:       \&Someother::Package::sortopts

validate:
   test1:      /^\w{3,10}$/
   test2:
       javascript: EMAIL
       perl:       eq 'test@test.foo'
   test3:
       - 0
       - 1
   test4:  \@test4opts

You get the idea 💡. A bit more whitespace, but it works in a standardized way. we love consistency in this house.

---

💅 METHODS 💅

🫶 new()

Normally not used directly — it gets called from CGI::FormBuilder. It creates the CGI::FormBuilder::Source::YAML object ✨. Arguments from the 'source' hash passed to CGI::FormBuilder->new() will become defaults, unless they're specified in the file. file wins. always.

🫶 parse($source)

Also normally not used directly — it's called from CGI::FormBuilder too. It parses the specified source file. No fancy params, bestie — just a single filename is accepted. And if the file isn't acceptable to YAML::Syck... I suppose it will die. 💀😭 that's it, that's the error handling.

---

🔥 SEE ALSO 🔥

• CGI::FormBuilder
• CGI::FormBuilder::Source

go read those too, they're the supporting cast and they ate. 🌟

---

👑 AUTHOR 👑

Copyright (c) 2006 Mark Hedges <hedges@ucsd.edu>. All rights reserved. 💖

---

📜 LICENSE 📜

This module is free software; you may copy it under terms of the Perl license (GNU General Public License or Artistic License.) http://www.opensource.org/licenses/index.html

---

and that's the whole page, bestie 🦋 — this one came from perl v5.34.0, dated 2022-06-09, and honestly? she's a classic. go build a form. slay 💅✨🌸