m4r extends the basic GNU m4 macro processor by allowing you to specify multiple alternative definitions for any given macro. For example: 
	define(`A',`B',`C',`D')
Here, B, C, and D are all alternative definitions of the macro A.

Given such a definition, each time the macro A is expanded, m4r will randomly select one of these alternative definitions as the one to use for that particular expansion of A.

This new feature allows for the generation of randomized text subject to syntactic constraints. For example, the input file: 
	define(`noun',`cats',`dogs',`people')
	define(`verb',`love',`hate',`ignore')
	noun verb noun
when given to m4r, would yield a potentially infinite number of randomized (but syntactically valid) sentences such as cats hate dogs, people ignore cats, and so on. All of the generated sentences will have the general form noun verb noun as called for by the m4r script shown above.

Within m4r, the random number sequence used as a basis for making the random selections (of competing macro definitions) is obtained from the random(3) system library function (available, at least, on BSD-ish and Linux systems). The random(3) system library function provides a single consistent and repeatable random number sequence unless its behavior is modified by changing its seed. Within C language programs, changing the seed used by random(3) is performed via a call to the srandom(3) system library function. Unfortunately, the seed-changing functionality of srandom(3) is not available within standard GNU m4.

To allow for alternative seeding of the random(3) random number generator, m4r also extends the basic GNU m4 macro processor by adding a new built-in macro named srandom. This macro may be called with either zero or one arguments. If called with one argument, that argument must be a number (according to the pre-existing lexical rules for numbers implemented within GNU m4). If present, the number supplied in the call to the m4r srandom built-in macro is converted to binary form and supplied (by m4r) in a call to the system library's srandom(3) function, thus seeding the random number generator. On the other hand, if m4r's srandom built-in macro is called with zero arguments, then the srandom macro will obtain a pseudo-random number on its own, and will supply that in a call to the system library's srandom(3) function to seed the random number generator.

In addition to macro multi-definitions and the new srandom built-in macro, m4r also adds another new built-in macro called randnum. This macro takes zero arguments and it expands to a single 32-bit pseudo-random number. The pseudo-random number generated by a call to this macro is obtained either (a) by reading 4 bytes of data from /dev/urandom (on systems where such a device file exists, e.g. BSD-ish and Linux systems) or else by repeatedly calling gettimeofday(2) and shifting the lowest-order bit of the tv_usec (microseconds) field of the result into an accumulator until a full 32-bit random number is produced. Note that: 
	srandom
is exactly equivalent to: 
	srandom(randnum())

Due to the common occurrence of self-recursive syntax rules within the context-free descriptions of many languages (including the subset of the bc(1) input language used on the m4r examples page) a special mechanism has been implemented within m4r which has the effect of helping to suppress runaway recursion during the expansion of macros having multiple alternative definitions. Quite simply, whenever a given alternative definition of a given macro is selected (quasi-randomly) as the expansion text to be used for a given call of the macro in question, internal logic within m4r slightly reduces the probability of that specific alternative definition being selected, again, as the operative expansion text for a subsequent call to the same macro, at least while the first-order expansion text of the given macro is still being processed/rescanned by m4r. This automatic and temporary depreciation of selected alternatives effectively prevents runaway recursive macro expansions when using m4r, at least in cases where each macro definition provides one (or more) alternative definitions that are non-recursive.