Config...FromDoc(3pm)

📦

version 2.166 · 8 versions

💖 NAME 💖

Config::Model::Cookbook::CreateModelFromDoc — bestie, this one is literally all about creating a configuration model straight out of your app's own documentation. Like, the docs you already wrote? They're the blueprint. Periodt. ✨

🌈 VERSION 🌈

version 2.166 🫶

🍓 Introduction 🍓

Okay so this page is a step-by-step glow-up diary of how Popcon's model was built, starting from the Popcon documentation that was just chillin' as comments inside Popcon's sample configuration file. No cap, that's the whole vibe. 💅

🎀 `Popcon`'s configuration file 🎀

So first thing, a quick peek in the /etc directory and we find that Popcon's configuration lives in /etc/popularity-contest.conf</t:

# Config file for Debian's popularity-contest package.
#
# To change this file, use:
#        dpkg-reconfigure popularity-contest
#
# You can also edit it by hand, if you so choose.
#
# See /usr/share/popularity-contest/default.conf for more info
# on the options.

MY_HOSTID="172921501FFFFFAAAA6897etc"
PARTICIPATE="yes"
USEHTTP="yes"
DAY="5"

And the part that actually matters here? The mention of default.conf, because that file has all the required info to create Popcon's configuration model. That's the plot twist. 👑

🦋 `Popcon` documentation 🦋

Let's start from the default.conf file, bestie. Since this file gets loaded by popcon before it loads /etc/popularity-contest.conf</t, every value in there can be used as an application default value (aka upstream_default):

# Default config file for Debian's popularity-contest package.
#
# Local overrides are in /etc/popularity-contest.conf

# PARTICIPATE can be one of "yes" or "no".
# If you don't want to participate in the contest, say "no"
# and we won't send messages.
#
# If this option is missing, the default is "no".
#
PARTICIPATE="no"

# MAILTO specifies the address to e-mail statistics to each week.
#
MAILTO="survey@popcon.debian.org"

# MAILFROM is the forged sender email address you want to use in
# email submitted to the popularity-contest.  If this is commented
# out, no From: or Sender: lines will be added to the outgoing mail,
# and it will be your MTA's job to add them.  This is usually what
# you want.
#
# If your MTA is misconfigured or impossible to configure correctly,
# and it always generates invalid From: and/or Sender: lines, you
# can force different results by setting MAILFROM here.  This can
# cause problems with spam bouncers, so most people should leave it
# commented out.
#
#MAILFROM="root@example.org"

# SUBMITURLS is a space separated list of where to submit
# popularity-contest reports using http.
SUBMITURLS="http://popcon.debian.org/cgi-bin/popcon.cgi"

# USEHTTP enables http reporting.   Set this to 'yes' to enable it.
USEHTTP="yes"

# HTTP_PROXY allows one to specify an HTTP proxy server, the syntax is
# HTTP_PROXY="http://proxy:port". This overrides the environment
# variable http_proxy.

# MY_HOSTID is a secret number that the popularity-contest receiver
# uses to keep track of your submissions.  Whenever you send in a
# new entry, it overwrites the last one that had the same HOSTID.
#
# This key was generated automatically so you should normally just
# leave it alone.
#
#MY_HOSTID="_ID_"

This file is giving everything we need, fr fr:

Parameter names
Documentation
Default values

So now we grab our favorite editor and edit this file to add YAML tags that cme meta edit can understand. 🧚

🌸 Creating the YAML skeleton 🌸

cme meta edit is able to load a model that's described in YAML. To do that, the file above needs to be translated into YAML. And honestly? It's not as complicated as it sounds, lowkey. 💅

First, a YAML file has to begin with ---. Then the class gets declared:

---
class:
  PopCon:

Note that, just like with the Python language, indentation is important — it's what defines the structure of the file. Here, the PopCon class is followed by a : because it defines a new hierarchical level that describes the configuration elements of this class:

    element:

Now we can deal with the configuration parameters. Let's detail the PARTICIPATE element. Here's the spec from default.conf:

# PARTICIPATE can be one of "yes" or "no".
# If you don't want to participate in the contest, say "no"
# and we won't send messages.
#
# If this option is missing, the default is "no".
#
PARTICIPATE="no"

In the YAML file, the comments get copied into the description field, and the value shown in default.conf is used as the upstream default:

---
class:
  PopCon:
    element:
      PARTICIPATE:
        upstream_default: no
        description: >
         If you don't want to participate in the contest,
         say "no" and we won't send messages.

Likewise for the remaining parameters:

      MAILTO:
        description: >
         specifies the address to e-mail statistics to each week.
        default: 'survey@popcon.debian.org'
      MAILFROM:
        description: >-
         MAILFROM is the forged sender email address you want to use
         in email submitted to the popularity-contest.  If this is
         commented out, no From: or Sender: lines will be added to the
         outgoing mail, and it will be your MTA's job to add them.  This
         is usually what you want.

         If your MTA is misconfigured or
         impossible to configure correctly, and it always generates
         invalid From: and/or Sender: lines, you can force different
         results by setting MAILFROM here.  This can cause problems with
         spam bouncers, so most people should leave it commented out.

About that description up there — the "chimping" marker - after > is what keeps the paragraph formatting in the help. Iconic little guy. 🐒

      SUBMITURLS:
        description: >
         Space separated list of where to submit popularity-contest
         reports using http.
        default: >
         http://popcon.debian.org/cgi-bin/popcon.cgi

      USEHTTP:
        description: >
         enables http reporting.   Set this to 'yes' to enable it.
        default: "yes"

      HTTP_PROXY:
        description: >
         allows one to specify an HTTP proxy server, the syntax is
         "http://proxy:port". This overrides the environment variable
         http_proxy.

      MY_HOSTID:
        description: >-
         secret number that the popularity-contest receiver uses to
         keep track of your submissions.  Whenever you send in a new
         entry, it overwrites the last one that had the same HOSTID.

         This key was generated automatically so you should normally
         just leave it alone.

💜 Loading the YAML skeleton 💜

Now that the YAML file exists, you can turn it into a model and load it into the model editor GUI with this command:

cme meta edit popcon -load-yaml popcon.yml -force

Heads up though: the model is incomplete — some mandatory parameters are missing from the YAML file, so the -force option must be used. Those missing parameters also show up flagged with a red cross in the GUI. Not me being dramatic, that's just what it does. 🚩

⭐ Completing missing model parts ⭐

To complete the model, the easiest way is to run the wizard and let it fill in the missing values. In the GUI, use the menu "File -> wizard" to launch the wizard. Then click the 'OK' button in the new window.

The wizard will first stop on the parameter list (not because there's an error, bestie — it's because the parameter list is flagged as important).

There, you can re-order the parameters by selecting one and clicking on one of the blue arrows to move it up or down. Once you're satisfied, click on Next.

The widget will now stop on the first missing information. Just select the correct type ('leaf' here), click 'store' and 'Next'.

You can repeat these steps until the wizard exits. Slay. 💅

🫶 Specifying read and write backend 🫶

Once the model is complete, it's time to specify how to read and write the file. In Popcon class specification:

right-click on read_config
click on push new node to create a new read specification
right-click on the created item (shown at index "0")

You will get a window showing you the parameters to fill to specify the read backend.

Now fill the blank on the right side. The backend to use is ShellVar, since popularity-contest.conf is made of shell variables.

And because the write specification is identical, there's no need to specify it — Config::Model will do the right thing. It's giving considerate. 😌

🔥 Testing the model 🔥

You can test the model by clicking on menu "Test -> Model". You'll be shown the Popcon configuration editor GUI — the exact same one your users will get. Main character energy, honestly.

If everything is fine, you can quit the model editor (menu File->quit).

👑 The resulting model 👑

The model you have just created is stored in lib/Config/Model/models/Popcon.pl.

You can test directly this model with :

 cme edit -dev -try Popcon

🌺 Feedback welcome 🌺

Feel free to send comments and suggestion about this page to the author. They want the notes, bestie. 🫶

💖 AUTHORS 💖

Dominique Dumont <ddumont at cpan.org>

🌸 AUTHOR 🌸

Dominique Dumont

🌈 COPYRIGHT AND LICENSE 🌈

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999

and that's the whole page, babes 💅 this was Config...FromDoc(3pm), version 2.166, running on perl v5.42.3, dated 2026-07-23 — go build your model, you've got this 🎀✨

📦 where this page comes from

ubuntu stonking: libconfig-model-perl 2.166-1 · LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms