blib/lib/SPVM/Document/Language/Statements.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 =head1 Name
2  
3 SPVM::Document::Language::Statements - Statements in the SPVM Language
4  
5 =head1 Description
6  
7 This document describes statements in the SPVM language.
8  
9 =head1 Statements
10  
11 A statement is a basic instruction that tells the program what to do.
12  
13 Statements can be written direct under L<scope block|SPVM::Document::Language::Class/"Scope Block">.
14  
15 # Scope block
16 {
17 # Statements
18 STATEMENT1
19 STATEMENT2
20 STATEMENT3
21 }
22  
23 =head2 Conditional Statements
24  
25 =head3 if Statement
26  
27 C<if> statement is a conditional statement with the following syntax.
28  
29 if (CONDITION1) {
30
31 }
32 elsif (CONDITION2) {
33
34 }
35 elsif (CONDITIONn) {
36
37 }
38 else {
39
40 }
41  
42 C<elsif> statement and the C<else> statement are optional.
43  
44 At first, all C<elsif> statements are expanded to the following code using C<if> - C<else> statements.
45  
46 if (CONDITION1) {
47
48 }
49 else {
50 if (CONDITION2) {
51
52 }
53 else {
54 if (CONDITIONn) {
55
56 }
57 else {
58
59 }
60 }
61 }
62  
63 C<if> statement is converted to simple C<if> - C<else> statements, so see a simple C<if> - C<else> statement.
64  
65 if (CONDITION) {
66
67 }
68 else {
69
70 }
71  
72 The L<condition evaluation|SPVM::Document::Language::Operators/"Condition Evaluation"> is performed on the condition I<CONDITION>.
73  
74 If the evaluated value is not 0, the program jumps to the beginning of the C<if> block.
75  
76 If the evaluated value is 0 and there is the C<else> block, the program jumps to the beginning of the C<else> block.
77  
78 If the evaluated value is 0 and there is no C<else> block, the program jumps to the end of the C<if> block.
79  
80 A C<if> - C<else> statement is enclosed by an invisible simple block.
81  
82 {
83 if (CONDITION) {
84
85 }
86 else {
87
88 }
89 }
90  
91 Examples:
92  
93 # if statement.
94 my $flag = 1;
95
96 if ($flag == 1) {
97 say "One";
98 }
99
100 # if statement with elsif and else
101 my $flag = 2;
102
103 if ($flag == 1) {
104 say "One";
105 }
106 elsif ($flag == 2) {
107 say "Two";
108 }
109 elsif ($flag == 3) {
110 say "Three";
111 }
112 else {
113 say "Other";
114 }
115  
116 =head3 else Statement
117  
118 C<else> statement is a conditional statement used in L<if statement|/"if Statement">.
119  
120 if (CONDITION) {
121
122 }
123 else {
124
125 }
126  
127 =head3 elsif Statement
128  
129 C<elsif> statement is a conditional statement used in L<if statement|/"if Statement">.
130  
131 if (CONDITION1) {
132
133 }
134 elsif (CONDITION2) {
135
136 }
137  
138 =head3 unless Statement
139  
140 C<unless> statement is a conditional statement with the following syntax.
141  
142 unless (CONDITION) {
143
144 }
145  
146 C<unless> statement is expanded to the following code.
147  
148 if (!CONDITION) {
149
150 }
151  
152 Examples:
153  
154 # unless statement.
155 my $flag = 1;
156
157 unless ($flag == 0) {
158 say "Not Zero";
159 }
160  
161 =head3 switch Statement
162  
163 C<switch> statement is a conditional statement with the following syntax.
164
165 # switch statement
166 switch (CONDITION) {
167 case CASE1: {
168 # ...
169 }
170 case CASE2: {
171 # ...
172 }
173 case CASEn: {
174 # ...
175 }
176 default: {
177 # ...
178 }
179 }
180  
181 The L<integer promotional conversion|SPVM::Document::Language::Operators/"Integer Promotional Conversion"> is performed on the condition I<CONDITION>.
182  
183 The operand of case statement I<CASEn> must be a L<character literal|SPVM::Document::Language::Tokenization/"Character Literal">, an L<integer literal|SPVM::Document::Language::Tokenization/"Integer Literals"> and an L<inline-expaned class method call to get an enumeration value|SPVM::Document::Language::Class/"Inline Expansion of Method Call to Get an Enuemration Value">.
184  
185 If I<CASEn> is a L<character literal|SPVM::Document::Language::Tokenization/"Character Literal">, the value is converted to int type at compile-time.
186  
187 C<case> statements and the C<default> statement are optional.
188  
189 If I<CONDITION> matches I<CASEn>, the program jumps to the beginning of the case block of I<CASEn>.
190  
191 If there are no case statements and no default statement, the program jumps to the end of the C<switch> block.
192  
193 If there is the C<default> statement and I<CONDITION> dose not matches I<CASEn>, the program jumps to the beginning of the C<default> block.
194  
195 If there is no C<default> statement and I<CONDITION> dose not matches I<CASEn>, the program jumps to the end of the C<switch> block.
196  
197 A L<break|/"break Statement"> statement is implicitly added to the end of the statements in every C<case> block.
198  
199 case CASEn: {
200 # A break statement is added implicitly to the end of the statements
201 break;
202 }
203  
204 It is allowed to jump multiple case statements into a single block.
205  
206 switch (CONDITION) {
207 case CASE1:
208 case CASE2:
209 {
210 # ...
211 }
212 }
213  
214 C<CONDITION> in C<switch statement> has own scope.
215  
216 {
217 switch (CONDITION) {
218 case CASE1: {
219 # ...
220 }
221 case CASE2: {
222 # ...
223 }
224 case CASEn: {
225 # ...
226 }
227 default: {
228 # ...
229 }
230 }
231 }
232  
233 Compilation Errors:
234  
235 I<CONDITION> must be an integer type within int. Otherwise, a compilation error occurs.
236  
237 The values of the case statements must not be duplicated. Otherwise, a compilation error occurs.
238  
239 Examples:
240  
241 # switch statement
242 my $code = 2;
243 my $flag = 1;
244 switch ($code) {
245 case 1: {
246 say "1";
247 }
248 case 2: {
249 say "2";
250 }
251 case 3: {
252 if ($flag) {
253 break;
254 }
255 say "3";
256 }
257 case 4:
258 case 5:
259 {
260 say "4 or 5";
261 }
262 default: {
263 say "Other";
264 }
265 }
266
267 # switch statement with enumeration
268 class Foo {
269 enum {
270 ID1,
271 ID2,
272 ID3,
273 }
274
275 static method main : int () {
276 my $value = 1;
277 switch ($value) {
278 case Foo->ID1: {
279 say "1";
280 }
281 case Foo->ID2: {
282 say "2";
283 }
284 case Foo->ID3: {
285 if ($flag) {
286 break;
287 }
288 say "3";
289 }
290 default: {
291 say "Other";
292 }
293 }
294 }
295 }
296  
297 =head4 case Statement
298  
299 C<case> statement specifies a case in L<switch statement|/"switch Statement">.
300  
301 # case statement
302 switch (CONDITION) {
303 case CASEn: {
304 # ...
305 }
306 }
307  
308 =head4 default Statement
309  
310 C<default> statement specifies a default case in L<switch statement|/"switch Statement">.
311  
312 # default statement
313 switch (CONDITION) {
314 default: {
315 # ...
316 }
317 }
318  
319 =head4 break Statement
320  
321 C<break> statement makes the program jump to the end of L<switch|/"switch Statement"> block.
322  
323 # break statement
324 break;
325  
326 Examples:
327  
328 my $code = 2;
329 my $flag = 1;
330 switch ($code) {
331 case 3: {
332 if ($flag) {
333 # break statement makes the program jump to the end of the switch block
334 break;
335 }
336 say "3";
337 }
338 default: {
339 say "Other";
340 }
341 }
342 # end of the switch block
343  
344 =head2 Loop Statements
345  
346 =head3 while Statement
347  
348 C<while> statement is a loop statement with the following syntax.
349  
350 # while statement
351 while (CONDITION) {
352
353 }
354  
355 The L<condition evaluation|SPVM::Document::Language::Operators/"Condition Evaluation"> is performed on the condition I<CONDITION>.
356  
357 If the evaluated value is 0, the program jumps to the end of the C<while> block. Otherwise, the program jumps to the beginning of the C<while> block.
358  
359 When the program reaches the end of the C<while> block, it jumps to the beginning of the C<while> statement.
360  
361 Examples:
362  
363 # while statement
364 my $i = 0;
365 while ($i < 5) {
366
367 say "$i";
368
369 $i++;
370 }
371  
372 C<while> statement is enclosed by an invisible simple block.
373
374 {
375 while (CONDITION) {
376
377 }
378 }
379  
380 =head3 next Statement
381  
382 C<next> statement makes the program jump to the beginning of the current L<while statement|/"while Statement">.
383  
384 # next statement
385 next;
386  
387 Examples:
388  
389 my $i = 0;
390
391 # beginning of while statement
392 while ($i < 5) {
393
394 if ($i == 3) {
395 $i++;
396
397 # next statement makes the program jump to the beginning of the current while statement.
398 next;
399 }
400
401 say "$i";
402 $i++;
403 }
404  
405 =head3 last Statement
406  
407 C<last> statement makes the program jump to the end of the current L<while statement|/"while Statement">.
408  
409 # last statement
410 last;
411  
412 Examples:
413  
414 while (1) {
415 # last statement makes the program jump to the end fo the current while statement.
416 last;
417 }
418 # end fo while statement
419  
420 =head3 for Statement
421  
422 C<for> statement is a loop statement with the following syntax.
423  
424 # for statement
425 for (INIT; CONDITION; INCREMENT) {
426
427 }
428  
429 A C<for> statement is expanded to the following code using a L<while statement|/"while Statement">.
430
431 {
432 INIT;
433 while (CONDITION) {
434
435 # ...
436
437 INCREMENT;
438 }
439 }
440  
441 If I<CONDITION> is not specified, it is set to 1.
442  
443 Exampels:
444  
445 # for statement
446 for (my $i = 0; $i < 5; $i++) {
447 say "$i";
448 }
449  
450 =head3 for-each Statement
451  
452 The for-each statement is a loop statement with the following syntax.
453
454 # for-each statemenet
455 for my VAR (@ARRAY) {
456
457 }
458
459 for my VAR (@{ARRAY}) {
460
461 }
462  
463 A for-each statement is expanded to the following code using a L<for statement|/"for Statement">.
464  
465 for (my $i = 0; $i < @{ARRAY}; $i++) {
466 my VAR = ARRAY->[$i];
467
468 }
469  
470 Example:
471  
472 # for-each statemenet
473 my $array = [1, 2, 3];
474 for my $element (@$array) {
475 say "$elemenet";
476 }
477  
478 =head2 return Statement
479  
480 The return statement causes the program to return to its caller. And it set the return value.
481  
482 // void
483 return;
484
485 // non-void
486 return OPERAND;
487  
488 This statement causes the program to return to its caller.
489  
490 If I<OPERAND> is specified, the return vlaue is set to I<OPERAND>.
491  
492 I<OPERAND> is an an L<operator|SPVM::Document::Language::Operators/"Operators">.
493  
494 This is because leave scope operations must not destroy I<OPERAND>.
495  
496 Compilation Errors:
497  
498 If the return type of the current method is the void type, I<OPERAND> must not exist. Otherwise, a compilation error occurs.
499  
500 If the return type of the current method is the non-void type, I<OPERAND> must exist. Otherwise, a compilation error occurs.
501  
502 The type of I<OPERAND> must satisfy L<assignment requirement|SPVM::Document::Language::Types/"Assignment Requirement"> to the return type of the current method. Otherwise, a compilation error occurs.
503  
504 =head2 die Statement
505  
506 C<die> statement throws an L<exception|SPVM::Document::Language::ExceptionHandling/"Throwing Exception">.
507
508 # die statement
509 die
510 die OPERAND_MESSAGE
511
512 # die statement with an error class
513 die ERROR_CLASS
514 die ERROR_CLASS OPERAND_MESSAGE
515
516 # die statement with the basic type ID of an error class
517 die OPERAND_ERROR_ID, OPERAND_MESSAGE
518 die $@
519  
520 I<OPERAND_MESSAGE> is a string of string type for an error message. If the exception thrown by the C<die> statement is catched, L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable"> C<$@> is set to I<OPERAND_MESSAGE> with stack traces added.
521  
522 If the exception is not catched, the program prints it to L<SPVM's standard error|SPVM::Document::Language::System/"Standard Streams">, and finishes the program with an error ID.
523  
524 The following is an example of stack traces of an exception message.
525  
526 Error
527 TestCase::Minimal->sum2 at SPVM/TestCase/Minimal.spvm line 1640
528 TestCase->main at SPVM/TestCase.spvm line 1198
529  
530 If I<OPERAND_MESSAGE> is not given or C<undef>, I<OPERAND_MESSAGE> is set to C<"Error">.
531  
532 I<ERROR_CLASS> is a class name, normally of L<Error|SPVM::Error> class, or its child class. If the exception thrown by the C<die> statement is catched, L<eval_error_id|SPVM::Document::Language::Operators/"eval_error_id Operator"> is set to the basic type ID of I<ERROR_CLASS>.
533  
534 The L<integer promotional conversion|SPVM::Document::Language::Operators/"Integer Promotional Conversion"> is performed on I<OPERAND_ERROR_ID>.
535  
536 I<OPERAND_ERROR_ID> is an integer value within int type. If it is given and the exception thrown by the C<die> statement is catched, L<eval_error_id|SPVM::Document::Language::Operators/"eval_error_id Operator"> is set to I<OPERAND_ERROR_ID>.
537  
538 See also L<Exception Handling|SPVM::Document::Language::ExceptionHandling> for exception handling using the C<die> statement.
539  
540 If the operand is $@ and I<OPERAND_ERROR_ID> is not specified, a special interpretation is applied.
541  
542 die $@
543  
544 is replaced with
545  
546 die eval_error_id, $@
547
548 See also L<eval_error_id operator|SPVM::Document::Language::Operators/"eval_error_id Operator">.
549  
550 Comlication Errors:
551  
552 I<OPERAND_MESSAGE> must be string type or the undef type. Otherwise, a compilation error occurs.
553  
554 I<ERROR_CLASS> must be a class type. Otherwise, a compilation error occurs.
555  
556 I<OPERAND_ERROR_ID> must be an integer type within int. Otherwise, a compilation error occurs.
557  
558 Examples:
559
560 # die statement with exception handling
561 eval {
562 die "Error";
563 }
564
565 if ($@) {
566 # ...
567 }
568
569 # die statement with an error class
570 eval {
571 die Error::System "System Error";
572 }
573
574 # Check error class
575 if ($@) {
576 if ($@ isa Error::System) {
577 # Do something for a system error.
578 }
579 else {
580 die $@;
581 }
582 }
583
584 # die statement with the basic type ID of an error class
585 my $error_id = Fn->get_basic_type_id("Error::System");
586 die $error_id, "System Error";
587
588 =head2 Operator Statement
589  
590 The operator statement operates an L<operator|SPVM::Document::Language::Operators/"Operators">.
591  
592 # operator statemenet
593 OPERATOR;
594  
595 Examples:
596  
597 1;
598 $var;
599 1 + 2;
600 &foo();
601 my $num = 1 + 2;
602  
603 =head2 Empty Statement
604  
605 The empty statement operates nothing.
606  
607 # empty statemenet
608 ;
609  
610 =head2 require Statement
611  
612 C<require> statement loads a class only if it is found.
613  
614 if (require BASIC_TYPE) {
615
616 }
617
618 if (require BASIC_TYPE) {
619
620 }
621 else {
622
623 }
624  
625 This statement searches for the type I<BASIC_TYPE> in L<class search directories|SPVM::Document::Language::Class/"Class Search Directories"> from the beginning, and if found, it loads I<BASIC_TYPE> at compilation time.
626  
627 If I<BASIC_TYPE> is found, the C<if> block is converted to a L<simple block|SPVM::Document::Language::Class/"Simple Block"> and the C<else> block(if it eixsts) is removed at compilation time.
628  
629 If I<BASIC_TYPE> is not found, a compilation error does not occur.
630  
631 If I<BASIC_TYPE> is not found, the C<else> block (if it eixstgs) is converted to a L<simple block|SPVM::Document::Language::Class/"Simple Block"> and the C<if> block is removed at compilation time.
632  
633 Examples:
634  
635 my $foo : object;
636 if (require MyClass) {
637 $foo = new MyClass;
638 }
639 else {
640 warn "Warning: Can't load MyClass";
641 }
642  
643 =head1 See Also
644  
645 =over 2
646  
647 =item * L<SPVM::Document::Language::Class>
648  
649 =item * L<SPVM::Document::Language::Operators>
650  
651 =item * L<SPVM::Document::Language>
652  
653 =item * L<SPVM::Document>
654  
655 =back
656  
657 =head1 Copyright & License
658  
659 Copyright (c) 2023 Yuki Kimoto
660  
661 MIT License