Commits

Jason McKesson committed 6fd125f

Small update to context implementation.

Comments (0)

Files changed (4)

docs/Structure_Reference.xml

                         <itemizedlist>
                             <listitem>
                                 <para><literal>key</literal>: The string name of the new context
-                                    variable. Required.</para>
+                                    variable. Required. Must end in the
+                                        <quote><literal>_</literal></quote> character, to ensure
+                                    that it doesn't conflict with other variables.</para>
                             </listitem>
                             <listitem>
                                 <para><literal>data</literal>: A Lua value that represents the new
                         </itemizedlist>
                         <para>Either <literal>name</literal> or <literal>data</literal> must be
                             defined. <literal>data</literal> takes priority.</para>
-                        <para>The actual context variable created by this will be suffixed with the
-                                <literal>_</literal> character, to ensure that it does not conflict
-                            with system-defined context variables. Just as with other context
-                            variables, attempting to define the same one twice will result in an
-                            error.</para>
+                        <para>Provides access to the parameter named by <literal>key</literal>. Note
+                            that this means you can't nest <literal>context</literal>'s that provide
+                            the same variable.</para>
                     </glossdef>
                 </glossentry>
                 <glossentry>
                                 <literal>enumSeen</literal> will be updated. It doesn't matter if
                             nothing was written; the enumerator being iterated over is
                             enough.</para>
+                        <para>If that's not good enough, if you need the filter mechanism to be
+                            respected, you can use <literal>context</literal> and
+                                <literal>call</literal> actions to create the equivalent. The
+                                <literal>context</literal> would create some key as a new table, and
+                            the <literal>call</literal> would be used to update the table with an
+                            enumerator.</para>
                     </glossdef>
                 </glossentry>
                 <glossentry>
                             children are processed as though the function had been called normally,
                                 <emphasis>UNLESS</emphasis> it is a filter action. In that case, the
                             filter will be assumed to have returned false, meaning that children
-                            will not be processed (unless <literal>neg</literal> is set, in which
-                            case it will flip that into <literal>true</literal>, thus always
-                            processing children if the function isn't present).</para>
+                            will not be processed (unless <literal>neg</literal> is
+                                <emphasis>also</emphasis> set, in which case it will flip that into
+                                <literal>true</literal>, thus always processing children if the
+                            function isn't present).</para>
                     </glossdef>
                 </glossentry>
                 <glossentry>
         <title>Function Parameters</title>
         <para>Here are a list of the various function parameters, with references to the actions
             that provide them.</para>
-        <para>Again, <emphasis>DO NOT MODIFY THEM!</emphasis></para>
+        <para>Again, <emphasis>DO NOT MODIFY THEM!</emphasis> You can call member functions on them
+            and inspect them. But unless they're user-defined parameters, do not change their
+            tables.</para>
         <glosslist>
             <glossentry>
                 <glossterm>specData</glossterm>

docs/Style_No_Load_CPP.xml

                 xlink:href="Style_Pointer_CPP">pointer_cpp</literal></link> style. Everything is
         scoped into namespaces. The enumerators don't have the <literal>GL_</literal> prefix on
         them, and so forth.</para>
-    <para>The main difference is this. <literal>noload_cpp</literal> does have a system function
-        called <literal>sys::CheckExtensions</literal>. This function walks through the list of
-        advertised extensions and sets up the extension variables. It does not load anything, so
-        there is no way to tell if all of the function pointers that are advertised are actually
-        available.</para>
+    <para>The system is designed to be automatic, responding to your application's needs. However,
+        calling a function that the implementation does not provide will result in a crash, just as
+        it would for the previous system.</para>
+    <para>To help alleviate this, the system does have variables to tell you which extensions are
+        available (at least, according to the extension strings). They are located in the
+            <literal>exts</literal> namespace, using the <literal>var_&lt;extension name></literal>
+        syntax, and they are C++ <literal>bool</literal> types. However, unlike the magic function
+        pointers, you have to actually initialize them. You can call
+            <literal>sys::CheckExtensions</literal> to initialize them. This function only
+        initializes the extension variables, so it cannot report on the number of functions that
+        failed to load.</para>
 </article>

modules/StructGLLoad.lua

 local decl_header_struct =
 { type="group",
 -- Internal header files.
-{ type="context", key="enumSeen", name="EnumSeen",
+{ type="context", key="enumSeen_", name="EnumSeen",
 { type="func-seen",
 	--Write the type header file.
 	{ type="file", style="type_hdr", name="GetFilename(basename, spec, options)",

modules/Structure.lua

 end
 
 MakeActionType("context", contextAction, function(self, data)
-	assert(data.key, "Context actions must have a `key`")
-	self.key = data.key .. "_"
+	assert(data.key, "Context actions must have a `key`.")
+	assert(data.key:match("%_$"), "Context action keys must end in `_`.")
+	self.key = data.key
 	self.data = data.data
 	if(self.name) then
 		self.name = "State" .. self.name