1Config::Model::CookbookU:s:eCrreCaotnetMroiCdboeunltfFeirdgo:mP:DeMorocld(e3Dl)o:c:uCmoeonktbaotoiko:n:CreateModelFromDoc(3)
2
6 Config::Model::Cookbook::CreateModelFromDoc - Create a configuration
7 model from application documentation
8
10 version 2.142
11
13 This page shows step by step how was created "Popcon"'s model from
14 "Popcon" documentation provided as comments in "Popcon"'s sample
15 configuration file.
16
18 A quick looks in "/etc" directory shows that "Popcon"'s configuration
19 is stored in "/etc/popularity-contest.conf</t":
20 # Config file for Debian's popularity-contest package.
22 #
23 # To change this file, use:
24 # dpkg-reconfigure popularity-contest
25 #
26 # You can also edit it by hand, if you so choose.
27 #
28 # See /usr/share/popularity-contest/default.conf for more info
29 # on the options.
30 MY_HOSTID="172921501FFFFFAAAA6897etc"
32 PARTICIPATE="yes"
33 USEHTTP="yes"
34 DAY="5"
35 The important part is the mention of "default.conf" which contains all
37 the required information to create "Popcon"'s configuration model.
38
40 Let's start from "default.conf" file. Since this file is loaded by
41 "popcon" before loading "/etc/popularity-contest.conf</t", all values
42 there can be used as application default values (aka upstream_default):
43 # Default config file for Debian's popularity-contest package.
45 #
46 # Local overrides are in /etc/popularity-contest.conf
47 # PARTICIPATE can be one of "yes" or "no".
49 # If you don't want to participate in the contest, say "no"
50 # and we won't send messages.
51 #
52 # If this option is missing, the default is "no".
53 #
54 PARTICIPATE="no"
55 # MAILTO specifies the address to e-mail statistics to each week.
57 #
58 MAILTO="survey@popcon.debian.org"
59 # MAILFROM is the forged sender email address you want to use in
61 # email submitted to the popularity-contest. If this is commented
62 # out, no From: or Sender: lines will be added to the outgoing mail,
63 # and it will be your MTA's job to add them. This is usually what
64 # you want.
65 #
66 # If your MTA is misconfigured or impossible to configure correctly,
67 # and it always generates invalid From: and/or Sender: lines, you
68 # can force different results by setting MAILFROM here. This can
69 # cause problems with spam bouncers, so most people should leave it
70 # commented out.
71 #
72 #MAILFROM="root@example.org"
73 # SUBMITURLS is a space separated list of where to submit
75 # popularity-contest reports using http.
76 SUBMITURLS="http://popcon.debian.org/cgi-bin/popcon.cgi"
77 # USEHTTP enables http reporting. Set this to 'yes' to enable it.
79 USEHTTP="yes"
80 # HTTP_PROXY allows one to specify an HTTP proxy server, the syntax is
82 # HTTP_PROXY="http://proxy:port". This overrides the environment
83 # variable http_proxy.
84 # MY_HOSTID is a secret number that the popularity-contest receiver
86 # uses to keep track of your submissions. Whenever you send in a
87 # new entry, it overwrites the last one that had the same HOSTID.
88 #
89 # This key was generated automatically so you should normally just
90 # leave it alone.
91 #
92 #MY_HOSTID="_ID_"
93 This file contains everything we need:
95 • Parameter names
97 • Documentation
99 • Default values
101 Now, we will use our favorite editor to edit this file and add YAML
103 tags that can be understood by "cme meta edit"
104
106 "cme meta edit" is able to load a model described in YAML. To do this
107 the above file needs to be translated in YAML. That's not as
108 complicated as it may sound.
109 First, a YAML file must begin with ---. Then the class must be
111 declared:
112 ---
114 class:
115 PopCon:
116 Note that, like with Python language, the indentation is important to
118 define the structure of the file. Here, the "PopCon" class is followed
119 by a ':' as it defines a new hierarchical level to describes the
120 configuration elements of this class:
121 element:
123 Now we can deal with the configuration parameters. Let's detail the
125 "PARTICIPATE" element. Here's the spec in from "default.conf":
126 # PARTICIPATE can be one of "yes" or "no".
128 # If you don't want to participate in the contest, say "no"
129 # and we won't send messages.
130 #
131 # If this option is missing, the default is "no".
132 #
133 PARTICIPATE="no"
134 In the YAML file, the comments are moved in the "description" field and
136 the value in the file is used as upstream default:
137 PARTICIPATE:
139 upstream_default: no
140 description: >
141 If you don't want to participate in the contest,
142 say "no" and we won't send messages.
143 Likewise for the remaining parameters:
145 MAILTO:
147 description: >
148 specifies the address to e-mail statistics to each week.
149 default: 'survey@popcon.debian.org'
150 MAILFROM:
151 description: >-
152 MAILFROM is the forged sender email address you want to use
153 in email submitted to the popularity-contest. If this is
154 commented out, no From: or Sender: lines will be added to the
155 outgoing mail, and it will be your MTA's job to add them. This
156 is usually what you want.
157 If your MTA is misconfigured or
160 impossible to configure correctly, and it always generates
161 invalid From: and/or Sender: lines, you can force different
162 results by setting MAILFROM here. This can cause problems with
163 spam bouncers, so most people should leave it commented out.
164 In the description above, the "chimping" marker '-' after '>' is used
166 to keep paragraph formatting in the help.
167 SUBMITURLS:
169 description: >
170 Space separated list of where to submit popularity-contest
171 reports using http.
172 default: >
173 http://popcon.debian.org/cgi-bin/popcon.cgi
174 USEHTTP:
176 description: >
177 enables http reporting. Set this to 'yes' to enable it.
178 default: "yes"
179 HTTP_PROXY:
181 description: >
182 allows one to specify an HTTP proxy server, the syntax is
183 "http://proxy:port". This overrides the environment variable
184 http_proxy.
185 MY_HOSTID:
187 description: >-
188 secret number that the popularity-contest receiver uses to
189 keep track of your submissions. Whenever you send in a new
190 entry, it overwrites the last one that had the same HOSTID.
191 This key was generated automatically so you should normally
193 just leave it alone.
194
196 Now that the YAML file was created, you can turn it into a model and
197 load it in the model editor GUI with the following command:
198 cme meta edit popcon -load-yaml popcon.yml -force
200 Note that the model is incomplete: some mandatory parameters are
202 missing from the YAML file so the -force option must be used. These
203 missing parameters are also flagged with a red cross in the GUI.
204
206 To complete the model, the easiest way is to run the wizard to complete
207 the missing values. In the GUI, you can use the menu "File -> wizard"
208 to launch the wizard. Then click on the 'OK' button in the new window.
209 The wizard will first stop on the parameter list (not because there's
211 an error, but because the parameter list is flagged as important)
212 There, you can re-order the parameters by selecting one and clicking on
214 one of the blue arrows to move it up or down. Once you're satisfied,
215 click on Next.
216 The widget will now stop on the first missing information. Just select
218 the correct type ('leaf' here), click 'store' and 'Next'.
219 You can repeat these steps until the wizard exits.
221
223 Once the model is complete, it's time to specify how to read and write
224 the file. In "Popcon" class specification:
225 • right-click on read_config
227 • click on push new node to create a new read specification
229 • right-click on the created item (shown at index "0")
231 You will get a window showing you the parameters to fill to specify the
233 read backend.
234 Now fill the blank on the right side. The backend to use is "ShellVar"
236 since popularity-contest.conf is made of shell variables.
237 Since the write specification is identical, there's no need to specify
239 it. Config::Model will do the right thing.
240
242 You can test the model by clicking on menu "Test -> Model". You will be
243 shown the "Popcon" configuration editor GUI. The same that your users
244 will get.
245 If everything is fine, you can quit the model editor (menu File->quit)
247
249 The model you have just created is stored in
250 "lib/Config/Model/models/Popcon.pl".
251 You can test directly this model with :
253 cme edit -dev -try Popcon
255
257 Feel free to send comments and suggestion about this page to the
258 author.
259
261 Dominique Dumont <ddumont at cpan.org>
262
264 Dominique Dumont
265
267 This software is Copyright (c) 2005-2021 by Dominique Dumont.
268 This is free software, licensed under:
270 The GNU Lesser General Public License, Version 2.1, February 1999
272perl v5.34.0 Co2n0f2i1g-:0:7M-o2d2el::Cookbook::CreateModelFromDoc(3)