- Finalizing the documentation before tagging 1.0 release

docs/02-control-structure-comparisons.md

@@ -0,0 +1,86 @@
+# Control structure - Comparisons
+
+Most control structures used within PHP view templates are supported natively in Picea.
+
+The goal for this project always has been to not loose original feature while removing some limitations with PHP's original templating syntax.
+
+## Comparison using `if` / `then` / `else` / `elseif` / `endif` 
+
+Comparisons works the same way as using PHP's alternative syntax.
+
+This is also how they are rendered in the compilation process. 
+
+**[PICEA]** So, using this code:
+
+```html
+{% php $search = 'Pack my box with five dozen liquor jugs' %}
+
+{% if strpos($search, 'beer') !== false %}
+    <span>Found 'beer' into {{ $search }} !</span>
+{% elseif strpos($search, 'liquor') !== false %}
+    <span>Found 'liquor' into {{ $search }} !</span>
+{% else %}
+    <b>Neither 'beer' or 'liquor' were found in {{ $search }}</b>
+{% endif %}
+```
+
+**[PHP]** Would yield:
+
+```php
+<?php $search = 'Pack my box with five dozen liquor jugs'; ?>
+
+<?php if (strpos($search, 'beer') !== false): ?>
+    <span>Found 'beer' into <?php echo htmlspecialchars((string) $search, 3, 'UTF-8', true) ?> !</span>
+<?php elseif (strpos($search, 'beer') !== false): ?>
+    <span>Found 'liquor' into <?php echo htmlspecialchars((string) $search, 3, 'UTF-8', true) ?> !</span>
+<?php else: ?>
+    <b>Neither 'beer' or 'liquor' were found in <?php echo htmlspecialchars((string) $search, 3, 'UTF-8', true) ?></b>
+<?php endif ?>
+```
+
+And then, the code would be runned through PHP's native `include` mechanic.
+
+## Comparison using `switch` / `case` / `break` / `endswitch`
+
+Using switches within HTML in plain PHP can be quite cumbersome because of it's limitation
+disallowing any output (including whitespace) between it's statement.
+
+Picea will allow some more complex (and readable) switches within your views.
+
+**[PICEA]** So, using this code:
+
+```php
+{% php $selected = random_int(0,5) %}
+
+{% switch $selected %}
+
+{% case 1 %}
+    {{ "One person selected" }}
+{% break %}
+
+{% case 2 %}
+{% default %}
+    {{ "Multiple person ($selected) selected" }}
+{% break %}
+
+{% endswitch %}
+```
+
+**[PHP]** Would render as such:
+
+```php
+<?php $selected = random_int(0,5) ?>
+
+<?php switch($selected):
+
+case 1: ?>
+    <?php echo htmlspecialchars((string) "One person selected", 3, 'UTF-8', true) ?>
+<?php break; ?>
+
+<?php case 2: ?>
+<?php default: ?>
+    <?php echo htmlspecialchars((string) "Multiple person ($selected) selected", 3, 'UTF-8', true) ?>
+<?php break; ?>
+
+<?php endswitch; ?>
+```