1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html><head>
3  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
4  <title>GNU Make Standard Library</title></head>
5
6<body>
7<h1>GNU Make Standard Library</h1>
8The GNU Make Standard Library (GMSL) is a collection of functions
9implemented using native GNU Make functionality that provide list and
10string manipulation, integer arithmetic, associative arrays, stacks,
11and debugging facilities.&nbsp; The GMSL is released under the BSD License.<br>
12<br>
13<a href="http://sourceforge.net/projects/gmsl/">[Project Page]</a> <a href="http://sourceforge.net/project/showfiles.php?group_id=129887">[Download]</a>
14<a href="http://sourceforge.net/forum/forum.php?forum_id=443916">[Discussion
15Forum]</a><br>
16<h2>Using GMSL</h2>
17The two files needed are <span style="font-family: monospace;">gmsl</span>
18and <span style="font-family: monospace;">__gmsl</span>.&nbsp; To
19include the GMSL in your Makefile do<br>
20<pre style="margin-left: 40px;">include gmsl</pre>
21<span style="font-family: monospace;">gmsl</span> automatically includes<span style="font-family: monospace;"> __gmsl</span>.&nbsp; To check that
22you have the right version of <span style="font-family: monospace;">gmsl</span>
23use the <span style="font-family: monospace;">gmsl_compatible</span>
24function (see
25below). The current version is <span style="font-family: monospace;">1
260 11</span>.<br>
27<br>
28The GMSL package also includes a test suite for GMSL.&nbsp; Just run <span style="font-family: monospace;">make -f gmsl-tests</span>.<br>
29<h2>Logical Operators</h2>GMSL has boolean $(true) (a non-empty string)
30and $(false) (an empty string).&nbsp; The following operators can be
31used with those variables.<br>
32<br>
33<hr style="width: 100%; height: 2px;"><span style="font-weight: bold;">not</span><br>
34
35<br>
36
37<span style="font-family: monospace;">Arguments: A boolean value</span><br style="font-family: monospace;">
38
39<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns $(true) if the boolean is $(false) and vice versa</span><br style="font-family: monospace;">
40
41<hr style="width: 100%; height: 2px; font-family: monospace;"><span style="font-weight: bold;"></span><span style="font-weight: bold;">and</span><br>
42<br>
43<span style="font-family: monospace;">Arguments: Two boolean values</span><br style="font-family: monospace;">
44<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns $(true) if both of the booleans are true</span><br style="font-family: monospace;">
45<hr style="width: 100%; height: 2px; font-family: monospace;"><span style="font-weight: bold;">or</span><br>
46<br>
47<span style="font-family: monospace;">Arguments: Two boolean values</span><br style="font-family: monospace;">
48<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns $(true) if either of the booleans is true</span><br style="font-family: monospace;">
49<hr style="width: 100%; height: 2px; font-family: monospace;"><span style="font-weight: bold;">xor</span><br style="font-weight: bold;">
50<br>
51<span style="font-family: monospace;">Arguments: Two boolean values</span><br style="font-family: monospace;">
52<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns $(true) if exactly one of the booleans is true</span><br style="font-family: monospace;">
53<hr style="width: 100%; height: 2px; font-family: monospace;"><span style="font-weight: bold;">nand</span><br>
54<br>
55<span style="font-family: monospace;">Arguments: Two boolean values</span><br style="font-family: monospace;">
56<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns value of 'not and'</span><br style="font-family: monospace;">
57<hr style="width: 100%; height: 2px; font-family: monospace;"><span style="font-weight: bold;">nor</span><br>
58<br>
59<span style="font-family: monospace;">Arguments: Two boolean values</span><br style="font-family: monospace;">
60<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns value of 'not or'</span><br style="font-family: monospace;">
61<hr style="width: 100%; height: 2px; font-family: monospace;"><span style="font-weight: bold;">xnor</span><br>
62<br>
63<span style="font-family: monospace;">Arguments: Two boolean values</span><br style="font-family: monospace;">
64<span style="font-family: monospace;">Returns:&nbsp;&nbsp; Returns value of 'not xor'</span><br style="font-family: monospace;">
65<hr style="width: 100%; height: 2px; font-family: monospace;">
66<h2>List Manipulation Functions</h2>
67&nbsp;A list is a string of characters; the list separator is a space.<br>
68
69<br>
70<hr style="width: 100%; height: 2px;"><b>first</b><br>
71<br>
72<span style="font-family: monospace;">Arguments: 1: A list<br>
73Returns:&nbsp;&nbsp;&nbsp;Returns the first element of a list<br>
74</span>
75<hr><b>last</b><br>
76<br>
77<span style="font-family: monospace;">Arguments: 1: A list<br>
78Returns:&nbsp;&nbsp;&nbsp;Returns the last element of a list<br>
79</span>
80<hr><b>rest</b><br>
81<br>
82<span style="font-family: monospace;">Arguments: 1: A list<br>
83Returns:&nbsp;&nbsp;&nbsp;Returns the list with the first element
84removed<br>
85</span>
86<hr><b>chop</b><br>
87<br>
88<span style="font-family: monospace;">Arguments: 1: A list<br>
89Returns:&nbsp;&nbsp;&nbsp;Returns the list with the last element removed<br>
90</span>
91<hr><b>map</b><br>
92<br>
93<span style="font-family: monospace;">Arguments: 1: Name of function to
94$(call) for each element of list<br>
95&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: List to
96iterate over calling the function in 1<br>
97Returns:&nbsp;&nbsp;&nbsp;The list after calling the function on each
98element<br>
99</span>
100<hr><b>pairmap</b><br>
101<br>
102<span style="font-family: monospace;">Arguments: 1: Name of function to
103$(call) for each pair of elements<br>
104&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: List to
105iterate over calling the function in 1<br>
106&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3: Second
107list to iterate over calling the function in 1<br>
108Returns:&nbsp;&nbsp;&nbsp;The list after calling the function on each
109pair of elements<br>
110</span>
111<hr><b>leq</b><br>
112<br>
113<span style="font-family: monospace;">Arguments: 1: A list to compare
114against...<br>
115&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: ...this
116list<br>
117Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the two lists are identical<br>
118</span>
119<hr><b>lne</b><br>
120<br>
121<span style="font-family: monospace;">Arguments: 1: A list to compare
122against...<br>
123&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: ...this
124list<br>
125Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the two lists are different<br>
126</span>
127<hr><b>reverse</b><br>
128<br>
129<span style="font-family: monospace;">Arguments: 1: A list to reverse<br>
130Returns:&nbsp;&nbsp;&nbsp;The list with its elements in reverse order<br>
131</span>
132<hr><b>uniq</b><br>
133<br>
134<span style="font-family: monospace;">Arguments: 1: A list to deduplicate<br>
135Returns:&nbsp;&nbsp;&nbsp;The list with elements in order without duplicates<br>
136</span>
137<hr><b>length</b><br>
138<br>
139<span style="font-family: monospace;">Arguments: 1: A list<br>
140Returns:&nbsp;&nbsp;&nbsp;The number of elements in the list<br>
141</span>
142<hr style="width: 100%; height: 2px;"><span style="font-family: monospace;"></span>
143<h2>String Manipulation Functions</h2>
144A string is any sequence of characters.<br>
145<br>
146<hr style="width: 100%; height: 2px;"><b>seq</b><br>
147<br>
148<span style="font-family: monospace;">Arguments: 1: A string to compare
149against...<br>
150&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: ...this
151string<br>
152Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the two strings are
153identical<br>
154</span>
155<hr><b>sne</b><br>
156<br>
157<span style="font-family: monospace;">Arguments: 1: A string to compare
158against...<br>
159&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: ...this
160string<br>
161Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the two strings are not
162the same<br>
163</span>
164<hr><b>strlen</b><br>
165<br>
166<span style="font-family: monospace;">Arguments: 1: A string<br>
167Returns:&nbsp;&nbsp;&nbsp;Returns the length of the string<br>
168</span>
169<hr><b>substr</b><br>
170<br>
171<span style="font-family: monospace;">Arguments: 1: A string<br>
172&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Start offset (first character is 1)<br>
173&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3: Ending offset (inclusive)<br>Returns:&nbsp;&nbsp;&nbsp;Returns a substring<br>
174</span>
175<hr><b>split</b><br>
176<br>
177<span style="font-family: monospace;">Arguments: 1: The character to
178split on<br>
179&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: A
180string to split<br>
181Returns:&nbsp;&nbsp;&nbsp;Splits a string into a list separated by
182spaces at the split<br>
183&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; character
184in the first argument<br>
185</span>
186<hr><b>merge</b><br>
187<br>
188<span style="font-family: monospace;">Arguments: 1: The character to
189put between fields<br>
190&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: A list
191to merge into a string<br>
192Returns:&nbsp;&nbsp;&nbsp;Merges a list into a single string, list
193elements are separated<br>
194&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; by the
195character in the first argument<br>
196</span>
197<hr><b>tr</b><br>
198<br>
199<span style="font-family: monospace;">Arguments: 1: The list of
200characters to translate from <br>
201&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: The
202list of characters to translate to<br>
203&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3: The
204text to translate<br>
205Returns:&nbsp;&nbsp;&nbsp;Returns the text after translating characters<br>
206</span>
207<hr><b>uc</b><br>
208<br>
209<span style="font-family: monospace;">Arguments: 1: Text to upper case<br>
210Returns:&nbsp;&nbsp;&nbsp;Returns the text in upper case<br>
211</span>
212<hr><b>lc</b><br>
213<br>
214<span style="font-family: monospace;">Arguments: 1: Text to lower case<br>
215Returns:&nbsp;&nbsp;&nbsp;Returns the text in lower case<br>
216</span>
217<hr style="width: 100%; height: 2px;"><span style="font-family: monospace;"></span>
218<h2>Set Manipulation Functions</h2>
219Sets are represented by sorted, deduplicated lists.  To create a set
220from a list use <span style="font-family:
221monospace;">set_create</span>, or start with the <span
222style="font-family: monospace;">empty_set</span> and <span
223style="font-family: monospace;">set_insert</span> individual elements.
224The empty set is defined as <span style="font-family:
225monospace;">empty_set</span>.<p>
226
227<hr><b>set_create</b><br>
228<br>
229<span style="font-family: monospace;">Arguments: 1: A list of set elements<br>
230Returns:&nbsp;&nbsp;&nbsp;Returns the newly created set<br>
231</span>
232
233<hr><b>set_insert</b><br>
234<br>
235<span style="font-family: monospace;">Arguments: 1: A single element to add to a set<br>
236&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: A set<br>
237Returns:&nbsp;&nbsp;&nbsp;Returns the set with the element added<br>
238</span>
239
240<hr><b>set_remove</b><br>
241<br>
242<span style="font-family: monospace;">Arguments: 1: A single element to remove from a set<br>
243&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: A set<br>
244Returns:&nbsp;&nbsp;&nbsp;Returns the set with the element removed<br>
245</span>
246
247<hr><b>set_is_member</b><br>
248<br>
249<span style="font-family: monospace;">Arguments: 1: A single element<br>
250&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: A set<br>
251Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the element is in the set<br>
252</span>
253
254<hr><b>set_union</b><br>
255<br>
256<span style="font-family: monospace;">Arguments: 1: A set<br>
257&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: Another set<br>
258Returns:&nbsp;&nbsp;&nbsp;Returns the union of the two sets<br>
259</span>
260
261<hr><b>set_intersection</b><br>
262<br>
263<span style="font-family: monospace;">Arguments: 1: A set<br>
264&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: Another set<br>
265Returns:&nbsp;&nbsp;&nbsp;Returns the intersection of the two sets<br>
266</span>
267
268<hr><b>set_is_subset</b><br>
269<br>
270<span style="font-family: monospace;">Arguments: 1: A set<br>
271&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: Another set<br>
272Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the first set is a subset of the second<br>
273</span>
274
275<hr><b>set_equal</b><br>
276<br>
277<span style="font-family: monospace;">Arguments: 1: A set<br>
278&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2: Another set<br>
279Returns:&nbsp;&nbsp;&nbsp;Returns $(true) if the two sets are identical<br>
280</span>
281
282<hr style="width: 100%; height: 2px;"><span style="font-family: monospace;"></span>
283<h2>Integer Arithmetic Functions</h2>
284Integers are represented by lists with the equivalent number of
285x's.&nbsp; For example the number 4 is x x x x.&nbsp; The maximum
286integer that the library can handle as <span style="font-style: italic;">input</span> (i.e. as the argument to a
287call to <span style="font-family: monospace;">int_encode</span>) is
28865536. There is no limit on integer size for internal computations or
289output.<br>
290<br>
291The arithmetic library functions come in two forms: one form of each
292function takes integers as arguments and the other form takes the
293encoded form (x's created by a call to <span style="font-family: monospace;">int_encode</span>).&nbsp; For example,
294there are two plus functions: <span style="font-family: monospace;">plus</span>
295(called with integer arguments and returns an integer) and <span style="font-family: monospace;">int_plus</span> (called with encoded
296arguments and returns an encoded result).<br>
297<br>
298<span style="font-family: monospace;">plus</span> will be slower than <span style="font-family: monospace;">int_plus</span> because its arguments
299and result have to be translated between the x's format and
300integers.&nbsp; If doing a complex calculation use the <span style="font-family: monospace;">int_*</span> forms with a single
301encoding of inputs and single decoding of the output.&nbsp; For simple
302calculations the direct forms can be used.<br>
303<br>
304<hr style="width: 100%; height: 2px;"><b>int_decode</b><br>
305<br>
306<span style="font-family: monospace;">Arguments: 1: A number of x's
307representation<br>
308Returns:&nbsp;&nbsp;&nbsp;Returns the integer for human consumption
309that is represented<br>
310&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; by the
311string of x's<br>
312</span>
313<hr><b>int_encode</b><br>
314<br>
315<span style="font-family: monospace;">Arguments: 1: A number in
316human-readable integer form<br>
317Returns:&nbsp;&nbsp;&nbsp;Returns the integer encoded as a string of x's<br>
318</span>
319<hr><b>int_plus</b><br>
320<br>
321<span style="font-family: monospace;">Arguments: 1: A number in x's
322representation<br>
323&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
324number in x's represntation<br>
325Returns:&nbsp;&nbsp;&nbsp;Returns the sum of the two numbers in x's
326representation<br>
327</span>
328<hr><b>plus (wrapped version of int_plus)</b><br>
329<br>
330<span style="font-family: monospace;">Arguments: 1: An integer<br>
331&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
332integer<br>
333Returns:&nbsp;&nbsp;&nbsp;Returns the sum of the two integers<br>
334</span>
335<hr><b>int_subtract</b><br>
336<br>
337<span style="font-family: monospace;">Arguments: 1: A number in x's
338representation<br>
339&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
340number in x's represntation<br>
341Returns:&nbsp;&nbsp;&nbsp;Returns the difference of the two numbers in
342x's representation,<br>
343&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; or outputs
344an error on a numeric underflow<br>
345</span>
346<hr><b>subtract (wrapped version of int_subtract)</b><br>
347<br>
348<span style="font-family: monospace;">Arguments: 1: An integer<br>
349&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
350integer<br>
351Returns:&nbsp;&nbsp;&nbsp;Returns the difference of the two integers,<br>
352&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; or outputs
353an error on a numeric underflow<br>
354</span>
355<hr><b>int_multiply</b><br>
356<br>
357<span style="font-family: monospace;">Arguments: 1: A number in x's
358representation<br>
359&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
360number in x's represntation<br>
361Returns:&nbsp;&nbsp;&nbsp;Returns the product of the two numbers in x's
362representation<br>
363</span>
364<hr><b>multiply (wrapped version of int_multiply)</b><br>
365<br>
366<span style="font-family: monospace;">Arguments: 1: An integer<br>
367&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
368integer<br>
369Returns:&nbsp;&nbsp;&nbsp;Returns the product of the two integers<br>
370</span>
371<hr><b>int_divide</b><br>
372<br>
373<span style="font-family: monospace;">Arguments: 1: A number in x's
374representation<br>
375&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
376number in x's represntation<br>
377Returns:&nbsp;&nbsp;&nbsp;Returns the result of integer division of
378argument 1 divided<br>
379&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; by
380argument 2 in x's representation<br>
381</span>
382<hr><b>divide (wrapped version of int_divide)</b><br>
383<br>
384<span style="font-family: monospace;">Arguments: 1: An integer<br>
385&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
386integer<br>
387Returns:&nbsp;&nbsp;&nbsp;Returns the integer division of the first
388argument by the second<br>
389</span>
390<hr><b>int_max, int_min</b><br>
391<br>
392<span style="font-family: monospace;">Arguments: 1: A number in x's
393representation<br>
394&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
395number in x's represntation<br>
396Returns:&nbsp;&nbsp;&nbsp;Returns the maximum or minimum of its
397arguments in x's<br>
398&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
399representation<br>
400</span>
401<hr><b>max, min</b><br>
402<br>
403<span style="font-family: monospace;">Arguments: 1: An integer<br>
404&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Another
405integer<br>
406Returns:&nbsp;&nbsp;&nbsp;Returns the maximum or minimum of its integer
407arguments<br>
408</span>
409<hr><b>int_gt, int_gte, int_lt, int_lte, int_eq, int_ne</b><br>
410<br>
411<span style="font-family: monospace;">Arguments: Two x's representation
412numbers to be compared<br>
413Returns:&nbsp;&nbsp;&nbsp;$(true) or $(false)<br>
414<br>
415int_gt First argument greater than second argument<br>
416int_gte First argument greater than or equal to second argument<br>
417int_lt First argument less than second argument <br>
418int_lte First argument less than or equal to second argument<br>
419int_eq First argument is numerically equal to the second argument<br>
420int_ne First argument is not numerically equal to the second argument<br>
421</span>
422<hr><b>gt, gte, lt, lte, eq, ne</b><br>
423<br>
424<span style="font-family: monospace;">Arguments: Two integers to be
425compared<br>
426Returns:&nbsp;&nbsp;&nbsp;$(true) or $(false)<br>
427<br>
428gt First argument greater than second argument<br>
429gte First argument greater than or equal to second argument<br>
430lt First argument less than second argument <br>
431lte First argument less than or equal to second argument<br>
432eq First argument is numerically equal to the second argument<br>
433ne First argument is not numerically equal to the second argument<br>
434</span>
435increment adds 1 to its argument, decrement subtracts 1. Note that<br>
436decrement does not range check and hence will not underflow, but<br>
437will incorrectly say that 0 - 1 = 0<br>
438<hr><b>int_inc</b><br>
439<br>
440<span style="font-family: monospace;">Arguments: 1: A number in x's
441representation<br>
442Returns:&nbsp;&nbsp;&nbsp;The number incremented by 1 in x's
443representation<br>
444</span>
445<hr><b>inc</b><br>
446<br>
447<span style="font-family: monospace;">Arguments: 1: An integer<br>
448Returns:&nbsp;&nbsp;&nbsp;The argument incremented by 1<br>
449</span>
450<hr><b>int_dec</b><br>
451<br>
452<span style="font-family: monospace;">Arguments: 1: A number in x's
453representation<br>
454Returns:&nbsp;&nbsp;&nbsp;The number decremented by 1 in x's
455representation<br>
456</span>
457<hr><b>dec</b><br>
458<br>
459<span style="font-family: monospace;">Arguments: 1: An integer<br>
460Returns:&nbsp;&nbsp;&nbsp;The argument decremented by 1<br>
461</span>
462<hr><b>int_double</b><br>
463<br>
464<span style="font-family: monospace;">Arguments: 1: A number in x's
465representation<br>
466Returns:&nbsp;&nbsp;&nbsp;The number doubled (i.e. * 2) and returned in
467x's representation<br>
468</span>
469<hr><b>double</b><br>
470<br>
471<span style="font-family: monospace;">Arguments: 1: An integer<br>
472Returns:&nbsp;&nbsp;&nbsp;The integer times 2<br>
473</span>
474<hr><b>int_halve</b><br>
475<br>
476<span style="font-family: monospace;">Arguments: 1: A number in x's
477representation<br>
478Returns:&nbsp;&nbsp;&nbsp;The number halved (i.e. / 2) and returned in
479x's representation<br>
480</span>
481<hr><b>halve</b><br>
482<br>
483<span style="font-family: monospace;">Arguments: 1: An integer<br>
484Returns:&nbsp;&nbsp;&nbsp;The integer divided by 2<br>
485</span>
486<hr style="width: 100%; height: 2px;"><span style="font-family: monospace;"></span>
487<h2>Associative Arrays</h2>
488An associate array maps a key value (a string with no spaces in it) to
489a single value (any string).&nbsp;&nbsp;&nbsp; <br>
490<b><br>
491</b>
492<hr style="width: 100%; height: 2px;"><b>set</b><br>
493<br>
494<span style="font-family: monospace;">Arguments: 1: Name of associative
495array<br>
496&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: The key
497value to associate<br>
498&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3: The
499value associated with the key<br>
500Returns:&nbsp;&nbsp;&nbsp;None<br>
501</span>
502<hr><b>get</b><br>
503<br>
504<span style="font-family: monospace;">Arguments: 1: Name of associative
505array<br>
506&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: The key
507to retrieve<br>
508Returns:&nbsp;&nbsp;&nbsp;The value stored in the array for that key<br>
509</span>
510<hr><b>keys</b><br>
511<br>
512<span style="font-family: monospace;">Arguments: 1: Name of associative
513array<br>
514Returns:&nbsp;&nbsp;&nbsp;Returns a list of all defined keys in the
515array<br>
516</span>
517<hr><b>defined</b><br>
518<br>
519<span style="font-family: monospace;">Arguments: 1: Name of associative
520array<br>
521&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: The key
522to test<br>
523Returns:&nbsp;&nbsp;&nbsp;Returns true if the key is defined (i.e. not
524empty)<br>
525</span>
526<hr style="width: 100%; height: 2px;"><span style="font-family: monospace;"></span>
527<h2>Named Stacks</h2>
528A stack is an ordered list of strings (with no spaces in them).<br>
529<br>
530<hr style="width: 100%; height: 2px;"><b>push</b><br>
531<br>
532<span style="font-family: monospace;">Arguments: 1: Name of stack<br>
533&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: Value
534to push onto the top of the stack (must not contain<br>
535&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; a space)<br>
536Returns:&nbsp;&nbsp;&nbsp;None<br>
537</span>
538<hr><b>pop</b><br>
539<br>
540<span style="font-family: monospace;">Arguments: 1: Name of stack<br>
541Returns:&nbsp;&nbsp;&nbsp;Top element from the stack after removing it<br>
542</span>
543<hr><b>peek</b><br>
544<br>
545<span style="font-family: monospace;">Arguments: 1: Name of stack<br>
546Returns:&nbsp;&nbsp;&nbsp;Top element from the stack without removing it<br>
547</span>
548<hr><b>depth</b><br>
549<br>
550<span style="font-family: monospace;">Arguments: 1: Name of stack<br>
551Returns:&nbsp;&nbsp;&nbsp;Number of items on the stack<br>
552</span>
553<hr style="width: 100%; height: 2px;"><span style="font-family: monospace;"></span>
554<h2>Miscellaneous and Debugging Facilities</h2>
555GMSL defines the following constants; all are accessed as normal GNU
556Make variables by wrapping them in <span style="font-family: monospace;">$()</span> or <span style="font-family: monospace;">${}</span>.<br>
557<br>
558<table style="text-align: left;" border="1" cellpadding="2" cellspacing="2">
559  <tbody>
560    <tr>
561      <td><span style="font-style: italic;">Constant</span><br>
562      </td>
563      <td><span style="font-style: italic;">Value</span><br>
564      </td>
565      <td><span style="font-style: italic;">Purpose</span><br>
566      </td>
567    </tr>
568    <tr>
569      <td><span style="font-family: monospace;">true</span><br>
570      </td>
571      <td><span style="font-family: monospace;">T</span><br>
572      </td>
573      <td>Boolean for <span style="font-family: monospace;">$(if)</span>
574and return from&nbsp; GMSL functions<br>
575      </td>
576    </tr>
577    <tr>
578      <td><span style="font-family: monospace;">false</span><br>
579      </td>
580      <td><br>
581      </td>
582      <td>Boolean for <span style="font-family: monospace;">$(if)</span>
583and return from GMSL functions<br>
584      </td>
585    </tr>
586    <tr>
587      <td><span style="font-family: monospace;">gmsl_version</span><br>
588      </td>
589      <td><span style="font-family: monospace;">1 0 0</span><br>
590      </td>
591      <td>GMSL version number as list: major minor revision<br>
592      </td>
593    </tr>
594  </tbody>
595</table>
596<span style="font-weight: bold;"><br>
597gmsl_compatible</span><span style="font-family: monospace;"><br>
598<br>
599Arguments: List containing the desired library version number (maj min
600rev)<br>
601</span><span style="font-family: monospace;">Returns:&nbsp;&nbsp;
602$(true) if this version of the library is compatible<br>
603</span><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
604with the requested version number, otherwise $(false)</span>
605<hr><b>gmsl-print-% (target not a function)</b><br>
606<br>
607<span style="font-family: monospace;">Arguments: The % should be
608replaced by the name of a variable that you<br>
609&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; wish to
610print out.<br>
611Action:&nbsp;&nbsp;&nbsp; Echos the name of the variable that matches
612the % and its value.<br>
613&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; For
614example, 'make gmsl-print-SHELL' will output the value of<br>
615&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; the SHELL
616variable<br>
617</span>
618<hr><b>assert</b><br>
619<br>
620<span style="font-family: monospace;">Arguments: 1: A boolean that must
621be true or the assertion will fail<br>
622&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2: The
623message to print with the assertion<br>
624Returns:&nbsp;&nbsp;&nbsp;None<br>
625</span>
626<hr><b>assert_exists</b><br>
627<br>
628<span style="font-family: monospace;">Arguments: 1: Name of file that
629must exist, if it is missing an assertion<br>
630&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; will be
631generated<br>
632Returns:&nbsp;&nbsp;&nbsp;None<br>
633</span>
634<hr style="width: 100%; height: 2px;"><br>
635GMSL has a number of environment variables (or command-line overrides)
636that control various bits of functionality:<br>
637<br>
638<table style="text-align: left;" border="1" cellpadding="2" cellspacing="2">
639  <tbody>
640    <tr>
641      <td><span style="font-style: italic;">Variable</span><br>
642      </td>
643      <td><span style="font-style: italic;">Purpose</span><br>
644      </td>
645    </tr>
646    <tr>
647      <td><span style="font-family: monospace;">GMSL_NO_WARNINGS</span><br>
648      </td>
649      <td>If set prevents GMSL from outputting warning messages:
650artithmetic functions generate underflow warnings.<br>
651      </td>
652    </tr>
653    <tr>
654      <td><span style="font-family: monospace;">GMSL_NO_ERRORS</span><br>
655      </td>
656      <td>If set prevents GMSL from generating fatal errors: division
657by zero or failed assertions are fatal.<br>
658      </td>
659    </tr>
660    <tr>
661      <td><span style="font-family: monospace;">GMSL_TRACE</span><br>
662      </td>
663      <td>Enables function tracing.&nbsp; Calls to GMSL functions will
664result in name and arguments being traced.<br>
665      </td>
666    </tr>
667  </tbody>
668</table>
669<span style="font-family: monospace;"></span><br>
670<hr>
671Copyright (c) 2005-2006 <a href="http://www.jgc.org/">John Graham-Cumming</a>.<br>
672<hr style="width: 100%; height: 2px;">
673<table style="width: 100%; text-align: left;" border="0" cellpadding="2" cellspacing="2">
674  <tbody>
675    <tr>
676      <td style="width: 50%;">John Graham-Cumming's work on this
677project was sponsored by <a href="http://www.electric-cloud.com/">Electric
678Cloud, Inc</a>.<br>
679      <a href="http://www.electric-cloud.com/"><img alt="" src="http://gmsl.sf.net/ec_logo.gif" style="border: 0px solid ; width: 223px; height: 47px;"></a><br>
680      </td>
681      <td align="right">
682      <p><a href="http://sourceforge.net/"><img src="http://sourceforge.net/sflogo.php?group_id=129887&amp;type=1" alt="SourceForge.net Logo" border="0" height="31" width="88"></a></p>
683      </td>
684    </tr>
685  </tbody>
686</table>
687</body></html>
688