Patterns in static

Apophenia

documentation.h
1 /* Apophenia's narrative documentation
2 Copyright (c) 2005--2013 by Ben Klemens. Licensed under the GPLv2; see COPYING. */
3 
2255 /* optionaldetails Implementation of optional arguments [this section ignored by doxygen]
2256 Optional and named arguments are among the most commonly commented-on features of Apophenia, so this page goes into full detail about the implementation.
2257 
2258 To use these features, see the all-you-really-need summary at the \ref designated
2259 page. For a background and rationale, see the blog entry at http://modelingwithdata.org/arch/00000022.htm .
2260 
2261 I'll assume you've read both links before continuing.
2262 
2263 OK, now that you've read the how-to-use and the discussion of how optional and named arguments can be constructed in C, this page will show how they are done in Apophenia. The level of details should be sufficient to implement them in your own code if you so desire.
2264 
2265 There are three components to the process of generating optional arguments as implemented here:
2266 \li Produce a \c struct whose elements match the arguments to the function.
2267 \li Write a wrapper function that takes in the struct, unpacks it, and calls the original function.
2268 \li Write a macro that makes the user think the wrapper function is the real thing.
2269 
2270 None of these steps are really rocket science, but there is a huge amount of redundancy.
2271 Apophenia includes some macros that reduce the boilerplate redundancy significantly. There are two layers: the C-standard code, and the script that produces the C-standard code.
2272 
2273 We'll begin with the C-standard header file:
2274 \code
2275 #ifdef APOP_NO_VARIADIC
2276  void apop_vector_increment(gsl_vector * v, int i, double amt);
2277 #else
2278  void apop_vector_increment_base(gsl_vector * v, int i, double amt);
2279  apop_varad_declare(void, apop_vector_increment, gsl_vector * v; int i; double amt);
2280 #define apop_vector_increment(...) apop_varad_link(apop_vector_increment, __VA_ARGS__)
2281 #endif
2282 \endcode
2283 
2284 First, there is an if/else that allows the system to degrade gracefully
2285 if you are sending C code to a parser like swig, whose goals differ
2286 too much from straight C compilation for this to work. Set \c
2287 APOP_NO_VARIADIC to produce a plain function with no variadic support.
2288 
2289 Else, we begin the above steps. The \c apop_varad_declare line expands to the following:
2290 
2291 \code
2292 typedef struct {
2293  gsl_vector * v; int i; double amt ;
2294 } variadic_type_apop_vector_increment;
2295 
2296 void variadic_apop_vector_increment(variadic_type_apop_vector_increment varad_in);
2297  \endcode
2298 
2299 So there's the ad-hoc struct and the declaration for the wrapper
2300 function. Notice how the arguments to the macro had semicolons, like a
2301 struct declaration, rather than commas, because the macro does indeed
2302 wrap the arguments into a struct.
2303 
2304  Here is what the \c apop_varad_link would expand to:
2305  \code
2306 #define apop_vector_increment(...) variadic_apop_increment_base((variadic_type_apop_vector_increment) {__VA_ARGS__})
2307  \endcode
2308 That gives us part three: a macro that lets the user think that they are
2309 making a typical function call with a set of arguments, but wraps what
2310 they type into a struct.
2311 
2312 Now for the code file where the function is declared. Again, there is is an \c APOP_NO_VARIADIC wrapper. Inside the interesting part, we find the wrapper function to unpack the struct that comes in.
2313 
2314 \code
2315 \#ifdef APOP_NO_VARIADIC
2316  void apop_vector_increment(gsl_vector * v, int i, double amt){
2317 \#else
2318 apop_varad_head( void , apop_vector_increment){
2319  gsl_vector * apop_varad_var(v, NULL);
2320  Apop_stopif(!v, return, 0, "You sent me a NULL vector.");
2321  int apop_varad_var(i, 0);
2322  double apop_varad_var(amt, 1);
2323  apop_vector_increment_base(v, i, amt);
2324 }
2325 
2326  void apop_vector_increment_base(gsl_vector * v, int i, double amt){
2327 #endif
2328  v->data[i * v->stride] += amt;
2329 }
2330 \endcode
2331 
2332 The
2333 \c apop_varad_head macro reduces redundancy, and will expand to
2334 \code
2335 void variadic_apop_vector_increment (variadic_type_variadic_apop_vector_increment varad_in)
2336 \endcode
2337 
2338 The function with this header thus takes in a single struct, and for every variable, there is a line like
2339 \code
2340  double apop_varad_var(amt, 1);
2341 \endcode
2342 which simply expands to:
2343 \code
2344  double amt = varad_in.amt ? varad_in.amt : 1;
2345 \endcode
2346 Thus, the macro declares each not-in-struct variable, and so there will need to be
2347 one such declaration line for each argument. Apart from requiring declarations, you
2348 can be creative: include sanity checks, post-vary the variables of the inputs, unpack
2349 without the macro, and so on. That is, this parent function does all of the bookkeeping,
2350 checking, and introductory shunting, so the base function can do the math. Finally,
2351 the introductory section will call the base function.
2352 
2353 The setup goes out of its way to leave the \c _base function in the public namespace,
2354 so that those who would prefer speed to bounds-checking can simply call that function
2355 directly, using standard notation. You could eliminate this feature by merging
2356 the two functions.
2357 
2358 
2359 <b>The m4 script</b>
2360 
2361 The above is all you need to make this work: the varad.h file, and the above structures. But there is still a lot of redundancy, which can't be eliminated by the plain C preprocessor.
2362 
2363 Thus, in Apophenia's code base (the one you'll get from checking out the git repository, not the gzipped distribution that has already been post-processed) you will find a pre-preprocessing script that converts a few markers to the above form. Here is the code that will expand to the above C-standard code:
2364 
2365 \code
2366 //header file
2367 APOP_VAR_DECLARE void apop_vector_increment(gsl_vector * v, int i, double amt);
2368 
2369 //code file
2370 APOP_VAR_HEAD void apop_vector_increment(gsl_vector * v, int i, double amt){
2371  gsl_vector * apop_varad_var(v, NULL);
2372  Apop_stopif(!v, return, 0, "You sent me a NULL vector.");
2373  int apop_varad_var(i, 0);
2374  double apop_varad_var(amt, 1);
2375 APOP_VAR_END_HEAD
2376  v->data[i * v->stride] += amt;
2377 }
2378 \endcode
2379 
2380 It is obviously much shorter. The declaration line is actually a C-standard declaration with the \c APOP_VAR_DECLARE preface, so you don't have to remember when to use semicolons. The function itself looks like a single function, but there is again a marker before the declaration line, and the introductory material is separated from the main matter by the \c APOP_VAR_END_HEAD line. Done right, drawing a line between the introductory checks or initializations and the main function can improve readability.
2381 
2382 The m4 script inserts a <tt>return function_base(...)</tt> at the end of the header
2383 function, so you don't have to. If you want to call the function before the last line, you
2384 can do so explicitly, as in the expansion above, and add a bare <tt>return;</tt> to
2385 guarantee that the call to the base function that the m4 script will insert won't ever be
2386 reached.
2387 
2388 One final detail: it is valid to have types with commas in them---function arguments. Because commas get turned to semicolons, and m4 isn't a real parser, there is an exception built in: you will have to replace commas with exclamation marks in the header file (only). E.g.,
2389 
2390 \code
2391 APOP_VAR_DECLARE apop_data * f_of_f(apop_data *in, void *param, int n, double (*fn_d)(double ! void * !int));
2392 \endcode
2393 
2394 m4 is POSIX standard, so even if you can't read the script, you have the program needed to run it. For example, if you name it \c prep_variadics.m4, then run
2395 \code
2396 m4 prep_variadics.m4 myfile.m4.c > myfile.c
2397 \endcode
2398 */
2399 
2400 
Autogenerated by doxygen (Debian ).