diff options
Diffstat (limited to 'js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-00_Introduction.html')
| -rw-r--r-- | js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-00_Introduction.html | 387 |
1 files changed, 387 insertions, 0 deletions
diff --git a/js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-00_Introduction.html b/js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-00_Introduction.html new file mode 100644 index 0000000..a0dcea1 --- /dev/null +++ b/js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-00_Introduction.html @@ -0,0 +1,387 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width,initial-scale=1"> + <title>00_Introduction - Documentation</title> + + <script src="scripts/prettify/prettify.js"></script> + <script src="scripts/prettify/lang-css.js"></script> + <!--[if lt IE 9]> + <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script> + <![endif]--> + <link type="text/css" rel="stylesheet" href="https://code.ionicframework.com/ionicons/2.0.1/css/ionicons.min.css"> + <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> + <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> +</head> +<body> + +<input type="checkbox" id="nav-trigger" class="nav-trigger" /> +<label for="nav-trigger" class="navicon-button x"> + <div class="navicon"></div> +</label> + +<label for="nav-trigger" class="overlay"></label> + +<nav> + <li class="nav-link nav-home-link"><a href="index.html">Home</a></li><li class="nav-heading">Tutorials</li><li class="nav-item"><a href="tutorial-00_Introduction.html">00_Introduction</a></li><li class="nav-item"><a href="tutorial-01_Function_Calls.html">01_Function_Calls</a></li><li class="nav-item"><a href="tutorial-02_Function_Composition.html">02_Function_Composition</a></li><li class="nav-item"><a href="tutorial-03_Table_Operations.html">03_Table_Operations</a></li><li class="nav-item"><a href="tutorial-04_Currying.html">04_Currying</a></li><li class="nav-item"><a href="tutorial-05_Pattern_Matching.html">05_Pattern_Matching</a></li><li class="nav-item"><a href="tutorial-06_Immutable_Tables.html">06_Immutable_Tables</a></li><li class="nav-item"><a href="tutorial-07_Function_References.html">07_Function_References</a></li><li class="nav-item"><a href="tutorial-08_Combinators.html">08_Combinators</a></li><li class="nav-item"><a href="tutorial-09_Expression_Based.html">09_Expression_Based</a></li><li class="nav-item"><a href="tutorial-10_Tables_Deep_Dive.html">10_Tables_Deep_Dive</a></li><li class="nav-item"><a href="tutorial-11_Standard_Library.html">11_Standard_Library</a></li><li class="nav-item"><a href="tutorial-12_IO_Operations.html">12_IO_Operations</a></li><li class="nav-item"><a href="tutorial-13_Error_Handling.html">13_Error_Handling</a></li><li class="nav-item"><a href="tutorial-14_Advanced_Combinators.html">14_Advanced_Combinators</a></li><li class="nav-item"><a href="tutorial-15_Integration_Patterns.html">15_Integration_Patterns</a></li><li class="nav-item"><a href="tutorial-16_Best_Practices.html">16_Best_Practices</a></li><li class="nav-item"><a href="tutorial-README.html">README</a></li><li class="nav-heading"><a href="global.html">Globals</a></li><li class="nav-item"><span class="nav-item-type type-member">M</span><span class="nav-item-name"><a href="global.html#callStackTracker">callStackTracker</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#debugError">debugError</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#debugLog">debugLog</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#executeFile">executeFile</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#initializeStandardLibrary">initializeStandardLibrary</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#interpreter">interpreter</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#lexer">lexer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#main">main</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#parser">parser</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#readFile">readFile</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#run">run</a></span></li> +</nav> + +<div id="main"> + + <h1 class="page-title">00_Introduction</h1> + + + <section> + +<header> + +</header> + +<article> + <h1>Tutorial: Learning the Scripting Language</h1> +<p>This guide will teach you how to use this functional programming language, assuming you have basic programming knowledge and a passing familiarity with functional programming concepts.</p> +<h2>What You'll Learn</h2> +<p>By the end of this tutorial, you'll be able to:</p> +<ul> +<li>Write basic programs with functions and data</li> +<li>Use pattern matching for conditional logic (our only control flow)</li> +<li>Work with tables (our only data structures)</li> +<li>Apply functional programming patterns</li> +<li>Use the standard library's combinators</li> +</ul> +<h2>Getting Started</h2> +<h3>Running Your First Program</h3> +<p>Create a file called <code>hello.txt</code> with this content:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Your first program */ +..out "Hello, World!"; +</code></pre> +<p>Run it with:</p> +<pre class="prettyprint source lang-bash"><code>node lang.js hello.txt +</code></pre> +<p>You should see: <code>Hello, World!</code></p> +<h3>Basic Values and Variables</h3> +<p>The language supports numbers, strings, and booleans:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Basic values */ +name : "Lucy Snowe"; +age : 18; +is_student : true; + +/* Output values */ +..out name; +..out age; +..out is_student; +</code></pre> +<p><strong>Key Point</strong>: Variables are immutable - once assigned, they cannot be changed.</p> +<h2>Functions: The Building Blocks</h2> +<h3>Defining Functions</h3> +<p>Functions are defined using arrow syntax:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Simple function */ +double : x -> x * 2; + +/* Function with multiple parameters */ +add : x y -> x + y; + +/* Using functions */ +result : double 5; +sum : add 3 4; +..out result; /* Output: 10 */ +..out sum; /* Output: 7 */ +</code></pre> +<h3>Function Application</h3> +<p>Functions are applied by putting the function name followed by arguments:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Function application */ +square : x -> x * x; +result : square 5; +..out result; /* Output: 25 */ + +/* Multiple applications */ +double : x -> x * 2; +increment : x -> x + 1; +result : increment (double 5); +..out result; /* Output: 11 */ +</code></pre> +<p><strong>Key Point</strong>: Unary minus works without parentheses: <code>f -5</code> applies <code>f</code> to <code>negate(5)</code>. Use spaces around binary operators for clarity: <code>5 - 3</code> for subtraction. See the <a href="01_Juxtaposition_Function_Application.md#negative-numbers-and-spacing">Juxtaposition tutorial</a> for detailed information about operator spacing.</p> +<h2>Pattern Matching with <code>when</code></h2> +<p>Instead of if/else statements, we use pattern matching:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Basic pattern matching */ +classify : x -> + when x is + 0 then "zero" + 1 then "one" + _ then "other"; + +/* Using the function */ +..out (classify 0); /* Output: "zero" */ +..out (classify 1); /* Output: "one" */ +..out (classify 5); /* Output: "other" */ +</code></pre> +<p>The <code>_</code> is a wildcard that matches anything.</p> +<h3>Multiple Value Patterns</h3> +<p>You can match on multiple values:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Multiple value patterns */ +compare : x y -> + when x y is + 0 0 then "both zero" + 0 _ then "x is zero" + _ 0 then "y is zero" + _ _ then "neither zero"; + +/* Using the function */ +..out (compare 0 0); /* Output: "both zero" */ +..out (compare 0 5); /* Output: "x is zero" */ +..out (compare 3 0); /* Output: "y is zero" */ +..out (compare 3 5); /* Output: "neither zero" */ +</code></pre> +<h2>Tables: Our Data Structures</h2> +<p>Tables are like objects or dictionaries in other languages:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Creating tables */ +person : {name: "Alice", age: 30, city: "NYC"}; +numbers : {1, 2, 3, 4, 5}; + +/* Accessing values */ +..out person.name; +..out person["age"]; +..out numbers[1]; /* Note: indexing starts at 1 */ +</code></pre> +<h3>Table Operations</h3> +<p>Tables support element-wise operations:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Transform every value in a table */ +double : x -> x * 2; +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; +..out doubled[1]; /* Output: 2 */ +..out doubled[2]; /* Output: 4 */ + +/* Filter values in a table */ +is_even : x -> x % 2 = 0; +evens : filter @is_even numbers; +..out evens[2]; /* Output: 2 */ +..out evens[4]; /* Output: 4 */ +</code></pre> +<p><strong>Key Point</strong>: The <code>@</code> symbol creates a function reference, which is needed for higher-order functions.</p> +<h2>Function Composition</h2> +<h3>Combining Functions</h3> +<p>You can combine functions to create new ones:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Function composition */ +double : x -> x * 2; +increment : x -> x + 1; + +/* Right-to-left composition (like the (mostly) regular mathematical style) */ +double_then_increment : compose @increment @double; +result : double_then_increment 5; +..out result; /* Output: 11 (5*2=10, then 10+1=11) */ + +/* Left-to-right composition (pipeline style) */ +increment_then_double : pipe @increment @double; +result : increment_then_double 5; +..out result; /* Output: 12 (5+1=6, then 6*2=12) */ +</code></pre> +<h3>The <code>via</code> Operator</h3> +<p>The language has a special <code>via</code> operator for composition:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Using the via operator */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* This is equivalent to compose */ +result : double via increment via square 3; +..out result; /* Output: 20 (3^2=9, 9+1=10, 10*2=20) */ +</code></pre> +<h2>Working with Multiple Tables</h2> +<h3>Element-wise Operations</h3> +<p>The <code>each</code> combinator lets you combine multiple tables:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Element-wise addition */ +table1 : {a: 1, b: 2, c: 3}; +table2 : {a: 10, b: 20, c: 30}; +sum : each @add table1 table2; +..out sum.a; /* Output: 11 */ +..out sum.b; /* Output: 22 */ +..out sum.c; /* Output: 33 */ + +/* Adding a scalar to every element */ +numbers : {1, 2, 3, 4, 5}; +incremented : each @add numbers 10; +..out incremented[1]; /* Output: 11 */ +..out incremented[2]; /* Output: 12 */ +</code></pre> +<h2>Immutable Table Operations</h2> +<p>The <code>t.</code> namespace provides immutable table operations:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Creating and modifying tables */ +person : {name: "Alice", age: 30}; + +/* Immutable update */ +updated : t.set person "age" 31; +..out updated.age; /* Output: 31 */ +..out person.age; /* Output: 30 (original unchanged) */ + +/* Immutable merge */ +updates : {age: 32, city: "NYC"}; +merged : t.merge person updates; +..out merged.age; /* Output: 32 */ +..out merged.city; /* Output: "NYC" */ +..out merged.name; /* Output: "Alice" */ + +/* Safe access with defaults */ +name : t.get person "name" "Unknown"; +city : t.get person "city" "Unknown"; +..out name; /* Output: "Alice" */ +..out city; /* Output: "Unknown" */ +</code></pre> +<h2>Recursive Functions</h2> +<p>Functions can call themselves:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Factorial function */ +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); + +/* Using factorial */ +..out factorial 5; /* Output: 120 */ +..out factorial 0; /* Output: 1 */ +</code></pre> +<h2>Practical Examples</h2> +<h3>Data Processing Pipeline</h3> +<pre class="prettyprint source lang-plaintext"><code>/* Processing a list of numbers */ +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Filter even numbers, double them, then sum */ +is_even : x -> x % 2 = 0; +double : x -> x * 2; + +/* Pipeline: filter -> map -> reduce */ +evens : filter @is_even numbers; +doubled : map @double evens; +total : reduce @add 0 doubled; + +..out total; /* Output: 60 (2+4+6+8+10)*2 = 60 */ +</code></pre> +<h3>Table Transformation</h3> +<pre class="prettyprint source lang-plaintext"><code>/* Working with structured data */ +people : { + alice: {name: "Alice", age: 30, city: "NYC"}, + bob: {name: "Bob", age: 25, city: "LA"}, + charlie: {name: "Charlie", age: 35, city: "Chicago"} +}; + +/* Extract all ages */ +get_age : person -> person.age; +ages : map @get_age people; +..out ages.alice; /* Output: 30 */ +..out ages.bob; /* Output: 25 */ + +/* Find people over 30 */ +is_over_30 : person -> person.age > 30; +seniors : filter @is_over_30 people; +..out seniors.charlie.name; /* Output: "Charlie" */ +</code></pre> +<h2>Common Patterns</h2> +<h3>Partial Application</h3> +<p>Functions can be partially applied:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Creating specialized functions */ +add : x y -> x + y; +add_ten : add 10; + +/* Using the specialized function */ +..out (add_ten 5); /* Output: 15 */ +..out (add_ten 20); /* Output: 30 */ +</code></pre> +<h3>Function References</h3> +<p>Use <code>@</code> to pass functions as arguments:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Higher-order functions */ +apply_twice : f x -> f (f x); +double : x -> x * 2; + +/* Using apply_twice */ +result : apply_twice @double 3; +..out result; /* Output: 12 (3*2=6, 6*2=12) */ +</code></pre> +<h2>Debugging and Testing</h2> +<h3>Assertions</h3> +<p>Use assertions to test your code:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Testing your functions */ +double : x -> x * 2; +..assert (double 5) = 10; +..assert (double 0) = 0; +..assert (double (-3)) = -6; + +..out "All tests passed!"; +</code></pre> +<h3>Debug Output</h3> +<p>Add debug output to understand what's happening:</p> +<pre class="prettyprint source lang-plaintext"><code>/* Debugging a function */ +process_data : x -> { + ..out "Processing:"; + ..out x; + result : x * 2; + ..out "Result:"; + ..out result; + result +}; + +final : process_data 5; +..out "Final result:"; +..out final; +</code></pre> +<h2>Best Practices</h2> +<h3>Break Down Complex Operations</h3> +<pre class="prettyprint source lang-plaintext"><code>/* Complex operation broken down */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Step 1: Filter */ +is_even : x -> x % 2 = 0; +evens : filter @is_even data; + +/* Step 2: Transform */ +square : x -> x * x; +squared : map @square evens; + +/* Step 3: Aggregate */ +total : reduce @add 0 squared; +..out total; +</code></pre> +<h3>Use Pattern Matching for Conditionals</h3> +<pre class="prettyprint source lang-plaintext"><code>/* Good: Pattern matching */ +classify : x -> + when x is + 0 then "zero" + 1 then "one" + _ then "other"; +</code></pre> +<h3>Embrace Immutability</h3> +<pre class="prettyprint source lang-plaintext"><code>/* Good: Immutable operations */ +person : {name: "Alice", age: 30}; +updated : t.set person "age" 31; +/* person remains unchanged */ + +/* Avoid: Trying to modify existing data, + this language doesn't support mutation */ +</code></pre> +<h2>Next Steps</h2> +<p>You now have a solid foundation in the scripting language! Here are some areas to explore:</p> +<ol> +<li><strong>Advanced Pattern Matching</strong>: Complex patterns and nested matching</li> +<li><strong>Table Comprehensions</strong>: Building tables from other data</li> +<li><strong>Function Composition</strong>: Building complex transformations</li> +<li><strong>Error Handling</strong>: Working with edge cases and invalid data</li> +<li><strong>Performance</strong>: Understanding how the language executes your code</li> +</ol> +<p>For a deep dive into combinators and advanced problem-solving patterns, check out the <strong><a href="Combinators_Deep_Dive.md">Combinators Deep Dive tutorial</a></strong>.</p> +<p>The language is designed to be functional and expressive. As you practice, you'll find that many operations become more natural when you think in terms of data transformations rather than step-by-step instructions.</p> +<p>Happy coding!</p> +</article> + +</section> + +</div> + +<br class="clear"> + +<footer> + Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a> on Tue Jul 29 2025 23:15:00 GMT-0400 (Eastern Daylight Time) using the Minami theme. +</footer> + +<script>prettyPrint();</script> +<script src="scripts/linenumber.js"></script> +</body> +</html> \ No newline at end of file |