File: controlflow.chapt.txt

package info (click to toggle)
yacas 1.3.6-2
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 7,176 kB
  • ctags: 3,520
  • sloc: cpp: 13,960; java: 12,602; sh: 11,401; makefile: 552; perl: 517; ansic: 381
file content (894 lines) | stat: -rw-r--r-- 23,978 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894

			Control flow functions

*CMD MaxEvalDepth --- set the maximum evaluation depth
*CORE
*CALL
	MaxEvalDepth(n)

*PARMS

{n} -- new maximum evaluation depth

*DESC

Use this command to set the maximum evaluation depth to the integer
"n". The default value is 1000. The function {MaxEvalDepth} returns {True}.

The point of having a maximum evaluation depth is to catch any
infinite recursion. For example, after the definition {f(x) := f(x)}, evaluating the expression {f(x)} would call {f(x)}, which would
call {f(x)}, etc. The interpreter will halt if
the maximum evaluation depth is reached. Also indirect recursion, e.g.
the pair of definitions {f(x) := g(x)} and {g(x) := f(x)}, will be caught.

*E.G. notest

An example of an infinite recursion, caught because the maximum
evaluation depth is reached.

	In> f(x) := f(x)
	Out> True;
	In> f(x)
	Error on line 1 in file [CommandLine]
	Max evaluation stack depth reached.
	Please use MaxEvalDepth to increase the stack
	size as needed.

However, a long calculation may cause the maximum evaluation depth to
be reached without the presence of infinite recursion. The function {MaxEvalDepth} is meant for these cases.

	In> 10 # g(0) <-- 1;
	Out> True;
	In> 20 # g(n_IsPositiveInteger) <-- \
	  2 * g(n-1);
	Out> True;
	In> g(1001);
	Error on line 1 in file [CommandLine]
	Max evaluation stack depth reached.
	Please use MaxEvalDepth to increase the stack
	size as needed.
	
	In> MaxEvalDepth(10000);
	Out> True;
	In> g(1001);
	Out> 21430172143725346418968500981200036211228096234
	1106721488750077674070210224987224498639675763139171
	6255189345835106293650374290571384628087196915514939
	7149607869135549648461970842149210124742283755908364
	3060929499671638825347975351183310878921541258291423
	92955373084335320859663305248773674411336138752;

*CMD Hold --- keep expression unevaluated
*CORE
*CALL
	Hold(expr)

*PARMS

{expr} -- expression to keep unevaluated

*DESC

The expression "expr" is returned unevaluated. This is useful to
prevent the evaluation of a certain expression in a context in which
evaluation normally takes place.

The function {UnList()} also leaves its result unevaluated. Both functions stop the process of evaluation (no more rules will be applied).

*E.G. notest

	In> Echo({ Hold(1+1), "=", 1+1 });
	 1+1 = 2
	Out> True;

*SEE Eval, HoldArg, UnList

*CMD Eval --- force evaluation of expression
*CORE
*CALL
	Eval(expr)

*PARMS

{expr} -- expression to evaluate

*DESC

This function explicitly requests an evaluation of the expression
"expr", and returns the result of this evaluation.

*E.G.

	In> a := x;
	Out> x;
	In> x := 5;
	Out> 5;
	In> a;
	Out> x;
	In> Eval(a);
	Out> 5;

The variable {a} is bound to {x},
and {x} is bound to 5. Hence evaluating {a} will give {x}. Only when an extra
evaluation of {a} is requested, the value 5 is
returned.

Note that the behavior would be different if we had exchanged the
assignments. If the assignment {a := x} were given
while {x} had the value 5, the variable {a} would also get the value 5 because the assignment
operator {:=} evaluates the right-hand side.

*SEE Hold, HoldArg, :=

*CMD While --- loop while a condition is met
*CORE
*CALL
	While(pred) body

*PARMS

{pred} -- predicate deciding whether to keep on looping

{body} -- expression to loop over

*DESC

Keep on evaluating "body" while "pred" evaluates to {True}. More precisely, {While}
evaluates the predicate "pred", which should evaluate to either {True} or {False}. If the result is {True}, the expression "body" is evaluated and then
the predicate "pred" is again evaluated. If it is still {True}, the expressions "body" and "pred" are again
evaluated and so on until "pred" evaluates to {False}. At that point, the loop terminates and {While}
returns {True}.

In particular, if "pred" immediately evaluates to {False}, the body is never executed. {While} is the fundamental looping construct on which
all other loop commands are based. It is equivalent to the {while} command in the programming language C.

*E.G. notest

	In> x := 0;
	Out> 0;
	In> While (x! < 10^6) \
	  [ Echo({x, x!}); x++; ];
	 0  1
	 1  1
	 2  2
	 3  6
	 4  24
	 5  120
	 6  720
	 7  5040
	 8  40320
	 9  362880
	Out> True;

*SEE Until, For

*CMD Until --- loop until a condition is met
*STD
*CALL
	Until(pred) body

*PARMS

{pred} -- predicate deciding whether to stop

{body} -- expression to loop over

*DESC

Keep on evaluating "body" until "pred" becomes {True}. More precisely, {Until} first
evaluates the expression "body". Then the predicate "pred" is
evaluated, which should yield either {True} or {False}. In the latter case, the expressions "body"
and "pred" are again evaluated and this continues as long as
"pred" is {False}. As soon as "pred" yields {True}, the loop terminates and {Until} returns {True}.

The main difference with {While} is that {Until} always evaluates the body at least once, but {While} may not evaluate the body at all. Besides, the
meaning of the predicate is reversed: {While} stops
if "pred" is {False} while {Until} stops if "pred" is {True}.
The command
{Until(pred) body;} is equivalent to {pred; While(Not pred) body;}. In fact, the
implementation of {Until} is based on the internal
command {While}. The {Until}
command can be compared to the {do ... while}
construct in the programming language C.

*E.G. notest

	In> x := 0;
	Out> 0;
	In> Until (x! > 10^6) \
	  [ Echo({x, x!}); x++; ];
	 0  1
	 1  1
	 2  2
	 3  6
	 4  24
	 5  120
	 6  720
	 7  5040
	 8  40320
	 9  362880
	Out> True;

*SEE While, For

*CMD If --- branch point
*CORE
*CALL
	If(pred, then)
	If(pred, then, else)

*PARMS

{pred} -- predicate to test

{then} -- expression to evaluate if "pred" is {True}

{else} -- expression to evaluate if "pred" is {False}

*DESC

This command implements a branch point. The predicate "pred" is
evaluated, which should result in either {True} or {False}. In the first case, the expression "then" is
evaluated and returned. If the predicate yields {False}, the expression "else" (if present) is evaluated and
returned. If there is no "else" branch (i.e. if the first calling
sequence is used), the {If} expression returns {False}.

*E.G.

The sign function is defined to be 1 if its argument is positive and
-1 if its argument is negative. A possible implementation is
	In> mysign(x) := If (IsPositiveReal(x), 1, -1);
	Out> True;
	In> mysign(Pi);
	Out> 1;
	In> mysign(-2.5);
	Out> -1;
Note that this will give incorrect results, if "x" cannot be
numerically approximated.
	In> mysign(a);
	Out> -1;
Hence a better implementation would be
	In> mysign(_x)_IsNumber(N(x)) <-- If \
	  (IsPositiveReal(x), 1, -1);
	Out> True;

*CMD SystemCall --- pass a command to the shell
*CORE
*CALL
	SystemCall(str)

*PARMS

{str} -- string containing the command to call

*DESC

The command contained in the string "str" is executed by the
underlying operating system (OS).
The return value of {SystemCall} is {True} or {False} according to the exit code of the command.

The {SystemCall} function is not allowed in the body of the {Secure} command and will lead to an error.

*E.G. notest

In a UNIX environment, the command {SystemCall("ls")} would print the contents of the current directory.

	In> SystemCall("ls")
	AUTHORS
	COPYING
	ChangeLog
... (truncated to save space)
	Out> True;

The standard UNIX command {test} returns success or failure depending on conditions.
For example, the following command will check if a directory exists:

	In> SystemCall("test -d scripts/")
	Out> True;

Check that a file exists:
	In> SystemCall("test -f COPYING")
	Out> True;
	In> SystemCall("test -f nosuchfile.txt")
	Out> False;

*SEE Secure

*CMD Function --- declare or define a function
*STD
*CALL
	Function() func(arglist)
	Function() func(arglist, ...)
	Function("op", {arglist}) body
	Function("op", {arglist, ...}) body

*PARMS

{func(args)} -- function declaration, e.g. {f(x,y)}

{"op"} -- string, name of the function

{{arglist}} -- list of atoms, formal arguments to the function

{...} -- literal ellipsis symbol "{...}" used to denote a variable number of arguments

{body} -- expression comprising the body of the function

*DESC

This command can be used to define a new function with named arguments.


The number of arguments of the new function and their names are determined by the list {arglist}. If the ellipsis "{...}" follows the last atom in {arglist}, a function with a variable number of arguments is declared (using {RuleBaseListed}). Note that the ellipsis cannot be the only element of {arglist} and <i>must</i> be preceded by an atom.

A function with variable number of arguments can take more arguments than elements in {arglist}; in this case, it obtains its last argument as a list containing all extra arguments.

The short form of the {Function} call merely declares a {RuleBase} for the new function but does not define any function body. This is a convenient shorthand for {RuleBase} and {RuleBaseListed}, when definitions of the function are to be supplied by rules. If the new function has been already declared with the same number of arguments (with or without variable arguments), {Function} returns false and does nothing.

The second, longer form of the {Function} call declares a function and also defines a function body. It is equivalent to a
single rule such as {op(_arg1, _arg2) <-- body}. The rule will be declared at
precedence 1025. Any previous rules associated with {"op"} (with the same
arity) will be discarded. More complicated functions (with more than one body)
can be defined by adding more rules.

*E.G. notest

This will declare a new function with two or more arguments, but define no rules for it. This is equivalent to {RuleBase ("f1", {x, y, ...})}.
	In> Function() f1(x,y,...);
	Out> True;
	In> Function() f1(x,y);
	Out> False;

This defines a function {FirstOf} which returns the
first element of a list. Equivalent definitions would be
{FirstOf(_list) <-- list[1]} or {FirstOf(list) := list[1]}.
	In> Function("FirstOf", {list})  list[1];
	Out> True;
	In> FirstOf({a,b,c});
	Out> a;

The following function will print all arguments to a string:
	In> Function("PrintAll",{x, ...}) If(IsList(x),
	  PrintList(x), ToString()Write(x));
	Out> True;
	In> PrintAll(1):
	Out> " 1";
	In> PrintAll(1,2,3);
	Out> " 1 2 3";

*SEE TemplateFunction, Rule, RuleBase,  RuleBaseListed, :=, Retract


*CMD Macro --- declare or define a macro
*STD
*CALL
	Macro() func(arglist)
	Macro() func(arglist, ...)
	Macro("op", {arglist}) body
	Macro("op", {arglist, ...}) body

*PARMS

{func(args)} -- function declaration, e.g. {f(x,y)}

{"op"} -- string, name of the function

{{arglist}} -- list of atoms, formal arguments to the function

{...} -- literal ellipsis symbol "{...}" used to denote a variable number of arguments

{body} -- expression comprising the body of the function

*DESC

This does the same as {Function}, but for macros. One can define a macro
easily with this function, in stead of having to use {DefMacroRuleBase}.

*E.G. notest

the following example defines a looping function.

	In> Macro("myfor",{init,pred,inc,body}) [@init;While(@pred)[@body;@inc;];True;];
	Out> True;
	In> a:=10
	Out> 10;

Here this new macro {myfor} is used to loop, using a variable {a} from the
calling environment.

	In> myfor(i:=1,i<10,i++,Echo(a*i))
	10 
	20 
	30 
	40 
	50 
	60 
	70 
	80 
	90 
	Out> True;
	In> i
	Out> 10;

*SEE Function, DefMacroRuleBase




*CMD Use --- load a file, but not twice
*CORE
*CALL
	Use(name)

*PARMS

{name} -- name of the file to load

*DESC

If the file "name" has been loaded before, either by an earlier call
to {Use} or via the {DefLoad}
mechanism, nothing happens. Otherwise all expressions in the file are
read and evaluated. {Use} always returns {True}.

The purpose of this function is to make sure that the file will at
least have been loaded, but is not loaded twice.

*SEE Load, DefLoad, DefaultDirectory

*CMD For --- C-style {for} loop
*STD
*CALL
	For(init, pred, incr) body

*PARMS

{init} -- expression for performing the initialization

{pred} -- predicate deciding whether to continue the loop

{incr} -- expression to increment the counter

{body} -- expression to loop over

*DESC

This commands implements a C style {for} loop. First
of all, the expression "init" is evaluated. Then the predicate
"pred" is evaluated, which should return {True} or
{False}. Next the loop is executed as long as the
predicate yields {True}. One traversal of the loop
consists of the subsequent evaluations of "body", "incr", and
"pred". Finally, the value {True} is returned.

This command is most often used in a form such as {For(i=1, i<=10, i++) body}, which evaluates {body} with
{i} subsequently set to 1, 2, 3, 4, 5, 6, 7, 8, 9,
and 10.

The expression {For(init, pred, incr) body} is
equivalent to {init; While(pred) [body; incr;]}.

*E.G. notest

	In> For (i:=1, i<=10, i++) Echo({i, i!});
	 1  1
	 2  2
	 3  6
	 4  24
	 5  120
	 6  720
	 7  5040
	 8  40320
	 9  362880
	 10  3628800
	Out> True;

*SEE While, Until, ForEach

*CMD ForEach --- loop over all entries in list
*STD
*CALL
	ForEach(var, list) body

*PARMS

{var} -- looping variable

{list} -- list of values to assign to "var"

{body} -- expression to evaluate with different values of "var"

*DESC

The expression "body" is evaluated multiple times. The first time,
"var" has the value of the first element of "list", then it gets
the value of the second element and so on. {ForEach}
returns {True}.

*E.G. notest

	 In> ForEach(i,{2,3,5,7,11}) Echo({i, i!});
	 2  2
	 3  6
	 5  120
	 7  5040
	 11  39916800
	Out> True;

*SEE For

*CMD Apply --- apply a function to arguments
*STD
*CALL
	Apply(fn, arglist)

*PARMS

{fn} -- function to apply

{arglist} -- list of arguments

*DESC

This function applies the function "fn" to the arguments in
"arglist" and returns the result. The first parameter "fn" can
either be a string containing the name of a function  or a pure
function. Pure functions, modeled after lambda-expressions, have the
form "{varlist,body}", where "varlist" is the list of formal
parameters. Upon application, the formal parameters are assigned the
values in "arglist" (the second parameter of {Apply}) and the "body" is evaluated.

Another way to define a pure function is with the Lambda construct.
Here, in stead of passing in "{varlist,body}", one can pass in
"Lambda(varlist,body)". Lambda has the advantage that its arguments
are not evaluated (using lists can have undesirable effects because
lists are evaluated). Lambda can be used everywhere a pure function
is expected, in principle, because the function Apply is the only function
dealing with pure functions. So all places where a pure function can
be passed in will also accept Lambda.

An shorthand for {Apply} is provided by the {@} operator.

*E.G.

	In> Apply("+", {5,9});
	Out> 14;
	In> Apply({{x,y}, x-y^2}, {Cos(a), Sin(a)});
	Out> Cos(a)-Sin(a)^2;
	In>  Apply(Lambda({x,y}, x-y^2), {Cos(a), Sin(a)});
	Out> Cos(a)-Sin(a)^2
	In>  Lambda({x,y}, x-y^2) @ {Cos(a), Sin(a)}
	Out> Cos(a)-Sin(a)^2

*SEE Map, MapSingle, @

*CMD MapArgs --- apply a function to all top-level arguments
*STD
*CALL
	MapArgs(expr, fn)

*PARMS

{expr} -- an expression to work on

{fn} -- an operation to perform on each argument

*DESC

Every top-level argument in "expr" is substituted by the result of
applying "fn" to this argument. Here "fn" can be either the name
of a function or a pure function (see Apply for more information on 
pure functions).

*E.G.

	In> MapArgs(f(x,y,z),"Sin");
	Out> f(Sin(x),Sin(y),Sin(z));
	In> MapArgs({3,4,5,6}, {{x},x^2});
	Out> {9,16,25,36};

*SEE MapSingle, Map, Apply

*CMD Subst --- perform a substitution
*STD
*CALL
	Subst(from, to) expr

*PARMS

{from} -- expression to be substituted

{to} -- expression to substitute for "from"

{expr} -- expression in which the substitution takes place

*DESC

This function substitutes every occurrence of "from" in "expr" by
"to". This is a syntactical substitution: only places where "from"
occurs as a subexpression are affected.

*E.G.

	In> Subst(x, Sin(y)) x^2+x+1;
	Out> Sin(y)^2+Sin(y)+1;
	In> Subst(a+b, x) a+b+c;
	Out> x+c;
	In> Subst(b+c, x) a+b+c;
	Out> a+b+c;

The explanation for the last result is that the expression {a+b+c} is internally stored as {(a+b)+c}. Hence {a+b} is a subexpression, but {b+c} is not.

*SEE WithValue, /:

*CMD WithValue --- temporary assignment during an evaluation
*STD
*CALL
	WithValue(var, val, expr)
	WithValue({var,...}, {val,...}, expr)

*PARMS

{var} -- variable to assign to

{val} -- value to be assigned to "var"

{expr} -- expression to evaluate with "var" equal to "val"

*DESC

First, the expression "val" is assigned to the variable
"var". Then, the expression "expr" is evaluated and
returned. Finally, the assignment is reversed so that the variable
"var" has the same value as it had before {WithValue} was evaluated.

The second calling sequence assigns the first element in the list of
values to the first element in the list of variables, the second value
to the second variable, etc.

*E.G.

	In> WithValue(x, 3, x^2+y^2+1);
	Out> y^2+10;
	In> WithValue({x,y}, {3,2}, x^2+y^2+1);
	Out> 14;

*SEE Subst, /:

*CMD /: --- local simplification rules
*CMD /:: --- local simplification rules
*STD
*CALL
	expression /: patterns
	expressions /:: patterns
Precedence:
*EVAL OpPrecedence("/:")


*PARMS

{expression} -- an expression

{patterns} -- a list of patterns

*DESC

Sometimes you have an expression, and you want to use specific
simplification rules on it that are not done by default. This
can be done with the {/:} and the {/::} operators. Suppose we have the
expression containing things such as {Ln(a*b)}, and we want
to change these into {Ln(a)+Ln(b)}, the easiest way
to do this is using the {/:} operator, as follows:

	In> Sin(x)*Ln(a*b)
	Out> Sin(x)*Ln(a*b);
	In> % /: { Ln(_x*_y) <- Ln(x)+Ln(y) }
	Out> Sin(x)*(Ln(a)+Ln(b));

A whole list of simplification rules can be built up in the list,
and they will be applied to the expression on the left hand side
of {/:} .

The forms the patterns can have are one of:

	pattern <- replacement
	{pattern,replacement}
	{pattern,postpredicate,replacement}

Note that for these local rules, {<-} should be used instead of
{<--} which would be used in a global rule.

The {/:} operator traverses an expression much as {Subst} does, that is, top
down, trying to apply the rules from the beginning of the list of
rules to the end of the list of rules. If the rules cannot be applied
to an expression, it will try subexpressions of that
expression and so on.

It might be necessary sometimes to use the {/::} operator, which
repeatedly applies the {/:} operator until the result doesn't change
any more. Caution is required, since rules can contradict each other,
which could result in an infinite loop. To detect this situation,
just use /: repeatedly on the expression. The repetitive nature
should become apparent.

*E.G.

	In> Sin(u)*Ln(a*b) /: {Ln(_x*_y) <- Ln(x)+Ln(y)}
	Out> Sin(u)*(Ln(a)+Ln(b));
	In> Sin(u)*Ln(a*b) /:: { a <- 2, b <- 3 }
	Out> Sin(u)*Ln(6);

*SEE Subst


*CMD TraceStack --- show calling stack after an error occurs
*CORE
*CALL
	TraceStack(expression)

*PARMS

{expression} -- an expression to evaluate

*DESC

TraceStack shows the calling stack after an error occurred.
It shows the last few items on the stack, not to flood the screen.
These are usually the only items of interest on the stack.
This is probably by far the most useful debugging function in
Yacas. It shows the last few things it did just after an error
was generated somewhere.

For each stack frame, it shows if the function evaluated was a
built-in function or a user-defined function, and for the user-defined
function, the number of the rule it is trying whether it was evaluating
the pattern matcher of the rule, or the body code of the rule.

This functionality is not offered by default because it slows
down the evaluation code.

*E.G. notest

Here is an example of a function calling itself recursively,
causing Yacas to flood its stack:

	In> f(x):=f(Sin(x))
	Out> True;
	In> TraceStack(f(2))
	Debug> 982 :  f (Rule # 0 in body)
	Debug> 983 :  f (Rule # 0 in body)
	Debug> 984 :  f (Rule # 0 in body)
	Debug> 985 :  f (Rule # 0 in body)
	Debug> 986 :  f (Rule # 0 in body)
	Debug> 987 :  f (Rule # 0 in body)
	Debug> 988 :  f (Rule # 0 in body)
	Debug> 989 :  f (Rule # 0 in body)
	Debug> 990 :  f (Rule # 0 in body)
	Debug> 991 :  f (Rule # 0 in body)
	Debug> 992 :  f (Rule # 0 in body)
	Debug> 993 :  f (Rule # 0 in body)
	Debug> 994 :  f (Rule # 0 in body)
	Debug> 995 :  f (User function)
	Debug> 996 :  Sin (Rule # 0 in pattern)
	Debug> 997 :  IsList (Internal function)
	Error on line 1 in file [CommandLine]
	Max evaluation stack depth reached.
	Please use MaxEvalDepth to increase the stack
	size as needed.

*SEE TraceExp, TraceRule

*CMD TraceExp --- evaluate with tracing enabled
*CORE
*CALL
	TraceExp(expr)

*PARMS

{expr} -- expression to trace

*DESC

The expression "expr" is evaluated with the tracing facility turned
on. This means that every subexpression, which is evaluated, is shown
before and after evaluation. Before evaluation, it is shown in the
form {TrEnter(x)}, where {x}
denotes the subexpression being evaluated. After the evaluation the
line {TrLeave(x,y)} is printed, where {y} is the result of the evaluation. The indentation
shows the nesting level.

Note that this command usually generates huge amounts of output. A
more specific form of tracing (eg. {TraceRule}) is
probably more useful  for all but very simple expressions.

*E.G. notest

	In> TraceExp(2+3);
	  TrEnter(2+3);
	    TrEnter(2);
	    TrLeave(2, 2);
	    TrEnter(3);
	    TrLeave(3, 3);
	    TrEnter(IsNumber(x));
	      TrEnter(x);
	      TrLeave(x, 2);
	    TrLeave(IsNumber(x),True);
	    TrEnter(IsNumber(y));
	      TrEnter(y);
	      TrLeave(y, 3);
	    TrLeave(IsNumber(y),True);
	    TrEnter(True);
	    TrLeave(True, True);
	    TrEnter(MathAdd(x,y));
	      TrEnter(x);
	      TrLeave(x, 2);
	      TrEnter(y);
	      TrLeave(y, 3);
	    TrLeave(MathAdd(x,y),5);
	  TrLeave(2+3, 5);
	Out> 5;

*SEE TraceStack, TraceRule

*CMD TraceRule --- turn on tracing for a particular function
*CORE
*CALL
	TraceRule(template) expr

*PARMS

{template} -- template showing the operator to trace

{expr} -- expression to evaluate with tracing on

*DESC

The tracing facility is turned on for subexpressions of the form
"template", and the expression "expr" is evaluated. The template
"template" is an example of the function to trace on. Specifically, all
subexpressions with the same top-level operator and arity as "template"
are shown. The subexpressions are displayed before (indicated with {TrEnter}) and after ({TrLeave})
evaluation. In between, the arguments are shown before and after
evaluation ({TrArg}). Only functions defined in
scripts can be traced.

This is useful for tracing a function that is called from within
another function. This way you can see how your function behaves
in the environment it is used in.

*E.G. notest

	In> TraceRule(x+y) 2+3*5+4;
	    TrEnter(2+3*5+4);
	      TrEnter(2+3*5);
	          TrArg(2, 2);
	          TrArg(3*5, 15);
	      TrLeave(2+3*5, 17);
	        TrArg(2+3*5, 17);
	        TrArg(4, 4);
	    TrLeave(2+3*5+4, 21);
	Out> 21;

*SEE TraceStack, TraceExp

*CMD Time --- measure the time taken by a function
*STD
*CALL
	Time(expr)
*PARMS
{expr} -- any expression
*DESC

The function {Time(expr)} evaluates the expression {expr} and prints the time in seconds needed for the evaluation.
The time is printed to the current output stream.
The built-in function {GetTime} is used for timing.

The result is the "user time" as reported by the OS, not the real ("wall clock") time.
Therefore, any CPU-intensive processes running alongside Yacas will not significantly affect the result of {Time}.

*EG notest
	In> Time(N(MathLog(1000),40))
	0.34 seconds taken
	Out> 6.9077552789821370520539743640530926228033;

*SEE GetTime