index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <title>DM Script (DMS)</title>
    <script 
     src='https://www.w3.org/Tools/respec/respec-w3c-common' 
     class='remove'></script>
    <script class='remove'>
      var respecConfig = {
        wg: "Conversational Interfaces Working Group",
        wgURI: "https://www.w3.org/community/conv/",
        wgPublicList: "public-conv",
        specStatus: "CG-FINAL",
        editors: [{
          name: "Nishant Shukla",
          url: "https://shukla.io",
          w3cid: 112944
        }],
        authors: [
          {
            name: "Nelson Solano",
            url: "https://www.linkedin.com/in/nelson-solano-24a935126",
            w3cid: 113168
          },
          {
            name: "Victor Zhang",
            url: "https://www.linkedin.com/in/victor-zhang-a8b303108",
	          w3cid: 113469
          },
          {
            name: "James Long",
            url: "https://jlongster.com/"
          }
        ],
        edDraftURI: "https://github.com/w3c/dms",
        shortName: "dms",
        addSectionLinks: true,
        isPreview: false,
        link: {
          "check-punctuation": true
        },
        localBiblio: {	
          "dms-compiler": {	
            "authors": [	
              "Nishant Shukla",	
              "James Long"	
            ],	
            "href": "https://github.com/conversational-interfaces/dms-compiler",	
            "title": "Dialogue Manager Script Compiler"
          }	
        }
      };
    </script>
    <script src="main.js"></script>
    <script src="dm.js"></script>
    <script src="dms-compiler.js"></script>
  </head>
  <body>
    <section id='abstract'>
      <p>
        This is the first version of the Dialogue Manager Script (DMS) documentation,
        which will demonstrate the current state and capabilities of DMS 
        through a <a>tutorial</a>, outline the <a>syntax and semantics</a>,
        and discuss how to write <a>effective DMS</a>. 
        DMS is a high-level language that compiles down to [[DMPL]] compliant JSON.
      </p>
    </section>

    <section id='sotd'>
    </section>

    <section>
      <h2>Getting Started</h2>
      <p>
        The code snippets presented in this page can be evaluated by hitting the "Run" button,
        which compiles DM Script into [[DMPL]] JSON, and then processes that JSON on a JavaScript runtime.
        The compiler can be found on GitHub [[dms-compiler]].
      </p>
    </section>

    <section>
      <h2><dfn>Tutorial</dfn>: Guessing Game</h2>
      <p>
        This guessing game chat-bot will help us better understand DMS.
        Let's build a simple prompt that asks the user for some <a>input</a>.
        We start by printing out messages using <code>act</code>, and 
        then awaiting the user's input.
      </p>
      <div>
        <pre class="example">
          act "Guess the number!"
          act "Please input your guess."
          input -> guess {
              _ {
                  act "You guessed " + guess
              }
          }
        </pre>
        <blockquote>
          <button onclick="return runClicked(this);">Run</button>
          <pre></pre>
          <input style="display: none;" type="number" placeholder="type input here" />
          <button style="display: none;" onclick="return handleIntent(this);">Send</button>
        </blockquote>
      </div>

      <p>
        The <code>input -></code> statement awaits for user input, and feeds it to a <a>variable</a> of our choosing.
        In this case, the variable <code>guess</code> is populated with the user's input.
      </p>

      <div>
        <pre class="example">
          once {
            act "Guess the number!"
            secret_number = pick(range(1, 101))
          }

          act "Please input your guess."
          input -> guess {
              to_num(guess) > secret_number {
                  act "Too big!"
              }
              to_num(guess) < secret_number {
                  act "Too small!"
              }
              _ {
                  act "You win!"
                  pop true
              }
          }
        </pre>
        <blockquote>
          <button onclick="return runClicked(this);">Run</button>
          <pre></pre>
          <input style="display: none;" type="number" placeholder="type input here" />
          <button style="display: none;" onclick="return handleIntent(this);">Send</button>
        </blockquote>
      </div>

      Once the user guesses the correct number, the system will output "You win!",
      and finallly the script will end, as indicated by <code>pop true</code>, which 
      pops the current script from the runtime stack. 

    </section>

    <section>
      <h2><dfn>Syntax and Semantics</dfn></h2>
      <p>
        The DMS syntax is loosely based off Rust.
        Curly-brackets <code>{ }</code> establish a block of code, 
        statements do not need a trailing semi-colon <code>;</code>,
        and labels before the curly-brackets annotate the behavior of the block.
        Similar to ECMAScript, DMS is not a strongly typed language.
      </p>
      <p>
        Scripts written in DM Script are also called <dfn>components</dfn>.
        The runtime shall evaluate the component in an infinite loop, 
        similar to game-loops inherent in most game engines.
        Components may call other components through <a>run</a> or <a>use</a> statements.
      </p>

      <section>
        <h3><dfn>Comments</dfn></h3>
        <p>
          Programmers may leave notes, or comments, in their code. 
          These comments are ignored by the compiler, 
          but are useful for other programmers reading the code.
        </p>
        <pre class="example">
          // Write your comments here.
        </pre>
      </section>

      <section>
        <h3><dfn>Variables</dfn></h3>
        <p>
          In programming, a variable is nothing more than a placeholder for some value. 
          The <a>strings</a> <code>“Chai”</code>, and <code>“Moo”</code> are simply values that a 
          placeholder <code>dog_name</code> could take on, 
          as can be seen in the following example.
        </p>
        <div>
          <pre class="example">
            // Initial value for a dog name.
            dog_name = "Chai"
  
            // Later on dog_name can be changed to a different value if needed.
            dog_name = "Moo"
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          Note that in DMS, there is always an implicit infinite loop wrapping our code. 
          During execution it will keep creating and assigning a variable 
          named <code>dog_name</code> the values <code>"Chai”</code> and <code>"Moo”</code>. 
        </p>
      </section>

      <section>
        <h3><dfn>Control Flow</dfn></h3>
        <p>
          In order to remove these redundant <a>variable</a> creation and assignments 
          we can wrap code in a block beginning with the keyword <dfn><code>once</code></dfn>. 
          The <a>once</a> keyword tells the compiler that the variable creation and 
          assignments should only be executed one time over the lifetime of the <a>component</a>.
        </p>
        <div>
          <pre class="example">
            once {
              dog_name = "Chai"
            }
            dog_name = "Moo"
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          Deciding whether or not to run some code depending on if a condition is true 
          is a basic building block in most programming languages. 
          The most common construct thats allows programmers to control the flow of execution 
          of DMS code are <a>if statements</a>.
          Recall that in DMS there is always an implicit infinite loop wrapping our code, 
          meaning that loops are inherently built in, 
          and any code outside of a <a>once</a> block will be repeatedly executed over the lifetime of our program. 
        </p>
        <section>
          <h3><dfn>If Statements</dfn></h3>
          <p>
            An <code>if</code> statement allows us to branch our code depending on conditions. 
            These statements start with the keyword <code>if</code>, and 
            follow up with a condition that evaluates to a Boolean value. 
          </p>
          <div>
            <pre class="example">
              once {
                number = 1
              }
              
              if number >= 2 {
                act "Number is greater than or equal to 2."
              }
              else {
                act "Number is less than 2."
              }

              number = number + 1
            </pre>
            <blockquote>
              <button onclick="return runClicked(this);">Run</button>
              <pre></pre>
            </blockquote>
          </div>
          <p>
            We can link multiple conditions by combining <code>if</code> and <code>else</code> 
            in an <code>else if</code> block. For example:
          </p>
          <div>
            <pre class="example">
              once {
                number = 7
              }
              
              if number % 3 == 0 {
                act "Number is divisible by 3."
              }
              else if number % 2 == 0 {
                act "Number is divisible by 2."
              }
              else {
                act "Number is not divisible by 2 or 3."
              }
            </pre>
            <blockquote>
              <button onclick="return runClicked(this);">Run</button>
              <pre></pre>
            </blockquote>
          </div>
        </section>
      </section>

      <section>
        <h3><dfn>Fork Statements</dfn></h3>
        <p>
          Forks are generalized <a>if statements</a>. 
          They're the heart and soul of DM Script.
          As a refresher, let's consider the trivial example below of branching logic.
        </p>
        <div>
          <pre class="example">
            if true {
              act "Let's talk about animals."
            }
            else {
              act "Let's talk about colors."
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          A <code>fork</code> statement allows a more general way of representing branching behavior.
          First, let's recreate the example above using <code>fork</code>.
          Think of it as a fork in the road, where we can only go down one candidate path. 
          Each candidate has an entry-condition.
          In the example below, notice that the underscore <code>_</code> 
          is a shortcut for the Boolean value <code>true</code>.
        </p>
        <div>
          <pre class="example">
            fork {
              _ {
                act "Let's talk about animals."
              }
              _ {
                act "Let's talk about colors."
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          By default, a <code>fork</code> picks the first path whose entry-condition is met, 
          from top to bottom.
          This method for resolving a fork is also called the "greedy" strategy,
          because it picks the first possible candidate instead of considering all candidates.
        </p>
        <p>
          Forks allow powerful customization of the branching behavior.
          In the example below, the <code>fork</code> picks a child-block at random.
          We can optionaly change the <dfn>fork-strategy</dfn> by providing a dictionary 
          in a decorator <code>#{}</code> directly before the statement.
          In the example below, a strategy of <code>{depth: 0}</code> 
          is associated with the <code>fork</code>.
        </p>
        <div>
          <pre class="example">
            #{depth: 0}
            fork {
              _ {
                act "Let's talk about animals."
              }
              _ {
                act "Let's talk about colors."
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          The content of the dictionary specifying the <a>fork-strategy</a> depends 
          on what the underlying runtime supports.
          In this case, <code>{depth: 0}</code> means use bounded depth-first search (BDFS),
          with a depth of <code>0</code> to resolve the fork.
          A depth of <code>0</code> in BDFS is effectively picking a candidate at random. 
          Different run-times may support different search algorithms,
          such as Monte Carlo Tree Search.
        </p>
        <p>
          The heuristic function for the search algorithm is specified by declaring a <dfn>model</dfn>. 
          The <a>model</a> of a <a>fork-strategy</a> is a list of lists, representing preferences.
          For example, the pair <code>[{x: 0}, {x:10}]</code>, declares that the value of <code>x</code>
          is preferred to be <code>0</code> as opposed to <code>10</code>.
          Internally, the runtime infers a utility-function, which is a real-valued function over the
          variables in DM Script, that provides a total-ordering of preferences.
        </p>
        <div>
          <pre class="example">
            once {
              x = 5
            }
            #{depth: 1, model: [[{x: 0}, {x: 10}]]}
            fork {
              _ {
                x = x + 1
              }
              _ {
                x = x - 1
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          Changing the preference <a>model</a> changes the program behavior.
          For example, by swapping the pair <code>[{x: 10}, {x: 0}]</code>,
          the program now counts up instead of counting down.
        </p>
        <div>
          <pre class="example">
            once {
              x = 5
            }
            #{depth: 1, model: [[{x: 10}, {x: 0}]]}
            fork {
              _ {
                x = x + 1
              }
              _ {
                x = x - 1
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          If we want to say that the value of <code>x</code> should be <code>5</code>,
          we can write the <a>model</a> as a list of preference-pairs, as follows.
        </p>
        <div>
          <pre class="example">
            once {
              x = 3
            }
            #{depth: 1, model: [[{x: 5}, {x: 0}], [{x: 5}, {x: 10}]]}
            fork {
              _ {
                x = x + 1
              }
              _ {
                x = x - 1
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          Consider the following scenario, where a autonomous agent has 3 possible actions,
          (1) eat food, (2) do nothing, or (3) work for food.
          In DM Script, we can use <code>fork</code> to define 
          the pre-conditions and outcomes of each action.
          We specify that <code>{health: 10}</code> is desirable over <code>{health: -10}</code>,
          and use BDFS to resolve the fork, with a depth of <code>1</code>.
        </p>
        <div>
          <pre class="example">
            once {
              health = 2
              food = 1
            }
            #{depth: 1, model: [[{health: 10}, {health: -10}]]}
            fork {
              food > 0 {
                act "eat"
                food = food - 1
                health = health + 3
              }
              _ {
                act "do nothing"
                health = health - 1
              }
              _ {
                act "work"
                food = food + 1
                health = health - 2
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this, false);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          Unfortunately, the program chooses the suboptimal sequence of actions: 
          it chooses to do nothing after eating up all the available food.
          Let's increase its intelligence by changing the fork-strategy to <code>{depth: 3}</code>.
          Notice that now, the program will alternate between eating food and working,
          which is the optimal strategy.
        </p>
        <div>
          <pre class="example">
            once {
              health = 2
              food = 1
            }
            #{depth: 3, model: [[{health: 10}, {health: -10}]]}
            fork {
              food > 0 {
                act "eat"
                food = food - 1
                health = health + 3
              }
              _ {
                act "do nothing"
                health = health - 1
              }
              _ {
                act "work"
                food = food + 1
                health = health - 2
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this, false);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          We'll cover more interesting use-cases of <code>fork</code> in the <a>effective DMS</a> section.
        </p>

      </section>

      <section>
        <h3><dfn>Primitive Types</dfn></h3>
        <p>
          The example in the <a>variables</a> section only allowed the variable <code>dog_name</code>
          to take on <a>string</a> values. 
          However, DMS is a dynamically typed language meaning that variables can 
          take on any basic data type such as <dfn><code>string</code></dfn>, <dfn><code>float</code></dfn>, and
          <dfn><a>Boolean</a></dfn>.
          Consider the following example where we have a variable named 
          <code>current_thought</code> which denotes what a programmer might be 
          thinking about throughout the day.
        </p>
        <div>
          <pre class="example">
            once {
              // Early in the morning their first thought could potentially be
              current_thought = "coffee"
              
              // Next they could be thinking, do I want office coffee?
              current_thought = false
              
              // Note that we don't use double quotes when assigning a boolean value to a variable.
              
              // And so they decide to buy coffee elsewhere, which has an associated cost.
              current_thought = 5.20
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>

        Every value in DMS has a data type which tells DMS what kind of data is being specified 
        so it knows how to work with the data. 
        Recall that DMS is dynamically typed meaning that it doesn’t need to know the 
        types of all variables at compile time. 
      </section>

      <section>
        <h3><dfn>Structures</dfn></h3>
        <p>
          The <a>primitive types</a> defined in the previous section are all <dfn>atomic</dfn> literals.
          DMS also allows programmers to build more complex structures such as lists, or dictionaries.
        </p>
        <section>
          <h3><dfn>List</dfn></h3>
          <p>
            A <code>list</code> is an ordered arrangement of other <a>structures</a>. 
            All elements are enclosed within square-brackets <code>[ ]</code>, 
            and separated by commas as follows.
          </p>
          <div>
            <pre class="example">
              once {
                // list of integers
                student_grades = [87, 90, 88, 92, 93]
                
                // list of strings
                student_names = ["Nawar", "Tom", "Chris"]
                
                // list of arbitrary types
                a_bunch_of_stuff = [false, 1, "two", [3, 4, 5]]
              }
            </pre>
            <blockquote>
              <button onclick="return runClicked(this);">Run</button>
              <pre></pre>
            </blockquote>
          </div>
        </section>

        <section>
          <h3><dfn>Dictionary</dfn></h3>
          <p>
            A <code>dictionary</code> is a <a>structure</a> that maps data in key-value pairs.
            The value of a corresponding key can be any <a>structure</a>.
          </p>
          <div>
            <pre class="example">
              once {
                student_grades = {
                  Nishant: 0,
                  Carol: 93,
                  Daniel: 90
                } 
              }
            </pre>
            <blockquote>
              <button onclick="return runClicked(this);">Run</button>
              <pre></pre>
            </blockquote>
          </div>
          <p>
            Take note of the syntax that was used to create the <code>dictionary</code> 
            in the above code snippet. 
            The keys of the <code>dictionary</code> are symbols which are a finite sequence 
            of characters without the double quotation-marks, 
            and the values in this example are simply integer values. 
            Note that when accessing the values of a <code>dictionary</code>,
            the keys must be enclosed within double quotation marks.
          </p>
          <div>
            <pre class="example">
              once {
                student_grades = {
                  Nishant: 0,
                  Carol: 93,
                  Daniel: 90
                } 
                act student_grades["Nishant"]
              }
            </pre>
            <blockquote>
              <button onclick="return runClicked(this);">Run</button>
              <pre></pre>
            </blockquote>
          </div>
        </section>
      </section>

      <section>
        <h3><dfn>Functions</dfn></h3>
        <p>
          Custom function definitions in DMS start with the keyword <code>def</code> and have a set of 
          parentheses after the function name. 
          The curly-brackets <code>{ }</code> tell the compiler where the function body begins and ends. 
          Lastly, a <dfn><code>pop</code></dfn> statement returns the value to be used by the caller.
          Consider the following function which simply returns the <a>string</a>, <code>"Greetings!"</code>.
        </p>
        <pre class="example">
          def greet() {
            pop "Greetings!"
          }
        </pre>
        <p>
          Our declaration of the <code>greet</code> function begins with the keyword <code>def</code>, 
          is followed by the function name <code>greet</code>, and ends with a set of empty parentheses <code>()</code>. 
          The function body contains all the logic that is expected to be executed when calling the function. 
          In the above example, we simply return the <a>string</a> <code>"Greetings!"</code> using the keyword <a>pop</a>. 
          In order to call our function and print the corresponding greeting, we use the keyword <dfn><code>act</code></dfn>. 
        </p>
        <div>
          <pre class="example">
            once {
              def greet() {
                pop "Greetings!"
              }
              act greet()
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          Functions in DMS can also have parameters, 
          which are special variables that are part of the function declaration. 
          The following re-declaration of the greet function allows programmers to pass in a variable of their choice, 
          such as the name of a user in the following example.
        </p>
        <div>
          <pre class="example">
            once {
              programmer = "Naitian"
              def greet(user) {
                pop "Greetings " + user
              }
            }
            act greet(programmer)
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>
        <p>
          The variables introduced in a function are local variables that are
          only accessible within the current scope, and they shadow the variables
          defined in the outer scope. 
          In the example below, we define a variable called <code>greetings</code>
          within a function, and later try to access that variable out of scope.
          Undefined variables by default evaluate to <dfn><code>null</code></dfn>.
        </p>

        <div>
          <pre class="example">
            once {
              programmer = "Naitian"
              def greet(user) {
                greetings = pick(["Greetings", "Howdy", "Sup"])
                pop greetings + " " + user
              }
              act greet(programmer)
              act programmer
              act greetings
            }
            
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>

        <p>
          You can also implement <dfn>closure</dfn> using <a>functions</a>. For example, in the following code-snippet we show how
          to define a function that raises a number to an exponent.
        </p>
        <div>
          <pre class="example">
            once {
              def powerOf(power) {
                  def f(num) {
                      pop pow(num, power)
                  }
                  pop f
              }

              square = powerOf(2)
              cube = powerOf(3)

              act square(3)
              act cube(3)
          }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
          </blockquote>
        </div>

        <p>
          In DMS, functions are pure, so <a>act</a> or <a>input</a>
          statements are not recommended in the body of user defined functions.
        </p>

        <section>
          <h3><dfn>Built-in Functions</dfn></h3>
          A handful of functions are available out of the box in DMS, forming a standard library. 
          The sections below cover the essential functions.
          <section>
            <h3><dfn>Comparison operators</dfn></h3>
            Check for equality with <code>==</code> or <code>!=</code>.
            Compare <code>numbers</code> with <code>></code>, <code>>=</code>, <code><</code>, and <code><=</code>.
            <div>
              <pre class="example">
                once {
                  x = 1
                  y = 2
                  act x == y
                  act x != y
                  act x < y
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>Boolean operators</dfn> </h3>
            Typical <code>Boolean</code> functions such as <code>&&</code>, <code>||</code>, and <code>!</code> are supported.
            <div>
              <pre class="example">
                once {
                  x = true
                  act x || false
                  act (x && !x) == false
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>Arithmetic operations</dfn></h3>
            Frequently used mathematical functions over <code>numbers</code> are available, such as
            <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>%</code>, and <code>floor</code>.
            <div>
              <pre class="example">
                once {
                  x = (1 + 2 * 3) / 4
                  y = (x + 0.25) % 2
                  z = floor(x)
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>Type casting operators</dfn></h3>
            The <code>to_num</code> and <code>to_str</code> operators allow changing types between <code>numbers</code>
            and <code>strings</code>.
            <div>
              <pre class="example">
                once {
                  number = 13.5
                  act "The number is " + to_str(number)
                  guess = "10"
                  act "You're off by..."
                  act number - to_num(guess)

                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>++</dfn></h3>
            <p>
              The <code>++</code> operator concatenates two <a>lists</a>.
              Note, on the other hand, the <code>+</code> operator combines <code>strings</code>.
            </p>
            <div>
              <pre class="example">
                once {
                  act [1, 2, 3] ++ [4, 5, 6]
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>len</dfn></h3>
            <p>
              The <code>len</code> function returns the length of the given argument. 
              Possible argument types include: <code>string</code>, <a>list</a>, or <a>dictionary</a>.
            </p>
            <div>
              <pre class="example">
                once {
                  school_data = {
                    student_names: ["Jeremy", "Earle", "Chad"],
                    school_name: "Institute of Good Learning"
                  }
                  act len(school_data)
                  act len(school_data["student_names"])
                  act len(school_data["student_names"][0])
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>
          
          <section>
            <h3><dfn>pick</dfn></h3>
            <p>
              The <code>pick</code> function allows programmers to pseudo-randomly select an item from a <a>list</a>.
            </p>
            <div>
              <pre class="example">
                once {
                  athlete_rankings = [
                    { lonzo: 2 },
                    { zion: 1 }
                  ]
                }
                
                act pick(athlete_rankings)
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>
          
          <section>
            <h3><dfn>get</dfn></h3>
            <p>
              The <code>get</code> function allows users to select a specific element of a <a>list</a>.
              In the above example if we wanted to retrieve the last element we could do so as follows.
            </p>
            <div>
              <pre class="example">
                act get(len(athlete_rankings) - 1, athlete_rankings)
              </pre>
            </div>
            <p>
              Or, use the <code>[ ]</code> notation, which is just a syntactic-sugar of <code>get</code>, as shown below.
            </p>
            <div>
              <pre class="example">
                act athlete_rankings[len(athlete_rankings) - 1]
              </pre>
            </div>
          </section>

          <section>
            <h3><dfn>range</dfn></h3>
            <p>
              The <code>range</code> function generates a <a>list</a> from the starting value (inclusive) to the ending value (exclusive).
            </p>
            <div>
              <pre class="example">
                once {
                  act range(1, 11)
                  act range(1, 5) ++ range(5, 11)
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
            <p>An optional third argument specifies the step-size.</p>
            <div>
              <pre class="example">
                once {
                  act range(1, 11, 2)
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>map</dfn></h3>
            <p>
              The <code>map</code> function iterates through a <a>list</a> passed in, and produces a new <a>list</a> with modified elements.
            </p>
            <div>
              <pre class="example">
                once {
                  act map(to_str, [1, 2, 3])
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
            <p>
              Multiple <a>lists</a> may be passed in, as long as the operator passed in supports that number of arguments.
            </p>
            <div>
              <pre class="example">
                once {
                  act map("+", [1, 2, 3], [4, 5, 6])
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
            <p>This opens up a lot of useful <a>list</a> manipulation techniques, such as implementing <code>zip</code> below.</p>
            <div>
              <pre class="example">
                once {
                  def zip(xs, ys) {
                    def pair(x, y) {
                      pop [x, y]
                    }
                    pop map(pair, xs, ys)
                  }
                  act zip([1, 2, 3], ["a", "b", "c"])
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>foldl</dfn></h3>
            <p>
              The <code>foldl</code> function iterates through a <a>list</a> from the left to yield a value by
              applying a given operator to each element of the <a>list</a> with an accumulator.
            </p>
            <div>
              <pre class="example">
                once {
                  def sum(xs) {
                    pop foldl("+", 0, xs)
                  }
                  act sum([1, 2, 3])
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>sort</dfn>, <dfn>shuffle</dfn>, <dfn>reverse</dfn></h3>
            <p>
              The <code>sort</code>, <code>shuffle</code>, and <code>reverse</code> functions operate on <a>lists</a>.
            </p>
            <div>
              <pre class="example">
                once {
                  xs = [4, 3, 2, 1]
                  ys = shuffle(xs)
                  act sort(ys) == xs
                  act reverse(sort(ys)) == xs
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>in</dfn></h3>
            <p>
              The <code>in</code> function is an in-fix operator that checks if an element exists within a <a>structure</a>.
            </p>
            <div>
              <pre class="example">
                once {
                  month = {
                    days: range(1, 31),
                    month: "June"
                  }
                  act "days" in month
                  act 31 in month["days"]
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>edit</dfn></h3>
            <p>
              the <code>edit</code> function performs a mutation on a <a>dictionary</a> variable based on the specified
              key value pair. The general syntax is as follows: <code>edit(dictionary, value, key)</code>. Note that
              if the specified key does not exist, an entry will be create within the specified <a>dictionary</a> variable
              with the specified value.
            </p>
            <div>
              <pre class="example">
                once {
                  info = {name: "unknown", inventory: {belt: 1, jacket: 2}}
                  act edit(info, "Bob", "name")
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>patch</dfn></h3>
            <p>
              The <code>patch</code> function mutates a
              <a>dictionary</a> variable based on instructions encoded by another dictionary.
              The general syntax is as follows: <code>patch(dictionary, key_values)</code>.
              Note that like <a>edit</a> if <code>patch</code> encounters a key that does not exist within the specified
              <a>dictionary</a> variable, <code>patch</code> with create an entry with the missing key and
              corresponding value.

            </p>
            <div>
              <pre class="example">
                once {
                  info = {name: "unknown", inventory: {belt: 1, jacket: 2}}
                  act patch(info, {name: "Bob", inventory: {jacket: 3}})
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>from_list</dfn></h3>
            <p>
              The <code>from_list</code> function converts a <a>list</a> of pairs (2-element lists) into a
              <a>dictionary</a>.
            </p>
            <div>
              <pre class="example">
                once {
                  table = [
                    ["glasses", 1],
                    ["jacket", 2],
                    ["shirt", 0]
                  ]
                  act from_list(table)
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>
          
          <section>
            <h3><dfn>exists</dfn></h3>
            <p>
              The <code>exists</code> function allows programmers to check whether the given variable has been defined or not.
            </p>
            <div>
              <pre class="example">
                if exists("count") {
                  count = count + 1
                }
                else {
                  act "Initializing count to 0"
                  count = 0
                }
                act count
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
            <p>
              Note that because we haven't defined the variable <code>count</code> anywhere, 
              our program defaults to the <code>else</code> branch of the conditional statement.
            </p>
          </section>

          <section>
            <h3><dfn>pow</dfn></h3>
            <p>
              The <code>pow</code> function raises a <code>base</code> number to a specified <code>exponent</code>.
            </p>
            <div>
              <pre class="example">
                once {
                  base = 2
                  exponent = 3
                  act pow(base, exponent)
                }
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
              </blockquote>
            </div>
          </section>

          <section>
            <h3><dfn>hop</dfn></h3>
            <p>
              Recall that DMS compiles down to [[DMPL]] compliant [[JSON]], which is a tree-like structure. 
              The <a>hop</a> statement allows programmers to revisit the ancestors of the current
              code block. Consider the following example, keeping in mind the notion of code blocks having ancestors.
            </p>
            <div>
              <pre class="example">
                act "What's the largest planet?"  // <-- hop 3, comes back to here

                input -> result { // <-- hop 2, go to grandparent
                  result == "jupiter" {
                    act "Correct!"
                  }
                  _ { // <-- hop 1, go to parent
                    act "Nope"
                    act "Try again..."
                    hop 3
                  }
                }

                pop true
              </pre>
              <blockquote>
                <button onclick="return runClicked(this);">Run</button>
                <pre></pre>
                <input style="display: none;" placeholder="type input here" />
                <button style="display: none;" onclick="return handleIntent(this);">Send</button>
              </blockquote>
            </div>
            <p>
                The above example can be hard to understand at first sight so lets break it down. At a high-level the
              component itself is the root of our tree structure. From there, code blocks and statements having equal scope
              can be thought of as children of the root. In the above example, the <a>act</a> statement and the code block
              following the <code>input</code> statement have equal scope and hence are children of the root. Stepping
              into the code block following the <code>input</code> statement, the code blocks following <code>result == "jupiter"</code>
              and <code>_</code> have equal scope; as such they are both children
              of the <code>input</code> statement. Finally looking at the code block following <code>_</code>, both <a>act</a>
              statements and the <a>hop</a> statement have equal scope, and hence are all children of the <code>_</code>
              statement. With this in mind the <a>hop</a> statement is essentially saying, return to the third ancestor of
              this code block.
            </p>
          </section>


        </section>
      </section>

      <section>
        <h3><dfn>Input</dfn> Handling</h3>
        <p>
          Up to now all program behavior has been predefined. 
          <a>Variables</a> have been assigned persistent values, and all output can be predetermined ahead of time. 
          However part of what makes any program engaging and meaningful, 
          is when a user or programmer is able to directly interact with the application. 
          In this section we showcase how DMS captures and processes user input.

          In DMS, user input is handled by a special structure which assigns intents 
          to a temporary user-defined variable, as follows.
        </p>
        <div>
          <pre class="example">
            once {
              act "Hi there! I'm Parrot-Bot. I repeat anything you say!"
            }

            input -> result {
              result == "Hello" {
                act "Ahoj to you!"
              }
              _ {
                act "You said: " + result
              }
            }
          </pre>
          <blockquote>
            <button onclick="return runClicked(this);">Run</button>
            <pre></pre>
            <input style="display: none;" placeholder="type input here" />
            <button style="display: none;" onclick="return handleIntent(this);">Send</button>
          </blockquote>
        </div>
        <p>
          In order to begin capturing input, we use the syntax <code>input -></code>. 
          The expression can be thought of as follows, 
          “Anything that is typed in or captured, 
          redirect and store in the variable immediately following the arrow <code>-></code> “. 
          In the example above, all captured input is stored in the variable result. 
          Once DMS is done capturing input, the body of the input block begins its execution. 
          Simply put, the conditions contained within the body of the input block can be thought 
          of as if-else expression. 
          This means that the first expression, using the input, that evaluates to true will be executed. 
          In the above example, whenever user input happens to be "Hello" the program will output "Ahoj to you!", 
          (Note: Ahoj is Czech for Hello) and in all other cases will default to the expression beginning with the underscore <code>_</code>. 

          Note that within an input block whenever an underscore <code>_</code> is used as the condition of an expression, 
          it will always evaluate to true; essentially acting as the default else of a branching statement.
        </p>
      </section>

      <section>
        <h3>Running components</h3>
        <p>
          Most programming languages allow programmers to use external packages/libraries and 
          launch child processes from anywhere within the main process. 
          In this chapter we demonstrate how programmers are able to import and run components 
          which can be thought of as scripts from within the main DMS program. 
          Being able to import and launch components allows for programmers to develop modular and sophisticated DMS programs. 
        </p>
        <section>
          <h3><dfn>use</dfn> statement</h3>
          <p>
              The <code>use</code> statement allows programmers to import variables and user-defined 
              functions from an external component or script. 
              Consider the following example where we have a component containing a number of math functions, 
              and a main component wanting to reuse them.
              Create the following two files: <code>main.dms</code> and <code>math.dms</code>. 
              Inside <code>math.dms</code> place the following code segment.
          </p>
          <pre class="example">
            once {
              pi = 3.14
              def square(number) {
                  pop number * number
              }
              
              def increment(number) {
                  pop number + 1
              }
            }
          </pre>
          <p>
            Now suppose that we wanted to use both the <code>square</code> and <code>increment</code> functions. 
            Inside the <code>main.dms</code> file we write the following,
          </p>
          <pre class="example">
            once {
              use "math" import _
            }
            
            act square(2)
            act increment(3)
            act pi
          </pre>
          <p>
            In order to introduce the component, we begin with the keyword <code>use</code>, 
            followed by the component name, in this case <code>math</code>. 
            Note that we leave off the file extension. 
            
            Next in order to bring all predefined functions into scope within 
            <code>main.dms</code> we use the keyword <code>import _</code>. 
            This can essentially be thought of as bringing everything that was 
            defined within <code>main.dms</code> into scope and made usable.
            The manner in which components are introduced might be a little tough to understand. 
            
            At a high level the use of components can be thought of as follows. 
            Suppose we're making curry. We have a recipe, which calls for spices. 
            Naturally we ask ourself, which ones? To which our recipe might say, all of them. 
            And so we proceed to bring all the individual ingredients defined in spices 
            and use them within our curry recipe.
          </p>
        </section>
        <section>
          <h3><dfn>run</dfn> statement</h3>
          <p>
            In the last section we introduced the idea of a component or simply a script. 
            Components not only make a programmers life easier by allowing DMS code to be modular, 
            but also save developers from writing their entire code base within a single component.
            DMS allows programmers to launch sub-components from within a main-component. 
            At a high level this means that if our current task is to make dinner, 
            completing the sub-task of washing dishes gives us the clean dishes we need to finish our main task. 
            Consider the following DMS code which does exactly that. Create the following two files: <code>main.dms</code>
            and <code>wash_dishes.dms</code>. Inside <code>wash_dishes.dms</code> place the following code segment.
          </p>
          <div>
            <pre class="example">
              once {
                num_dishes = 1
              }

              if num_dishes >= 2 {
                act "done"
                pop true
              }

              num_dishes = num_dishes + 1
            </pre>
            <blockquote>
              <button onclick="return runClicked(this);">Run</button>
              <pre></pre>
            </blockquote>
          </div>
          <p>
            Similarly within <code>main.dms</code> place the following.
          </p>
          <pre class="example">
            once {
              clean_dishes = false
            }
            act "Lets make some food!"
            if !clean_dishes {
              run "wash_dishes" () -> result {
                result {
                  act "Ok lets get to cooking!"
                }
                _ {
                  act "On second thought, lets order in."
                }
              }
            }
          </pre>
          <p>
              There’s a lot going on in the above example, 
              so lets break it down. In order to launch a sub-component we use the keyword <code>run</code>. 
              The line containing <code>run "wash_dishes" () -> result</code>
              tells DMS that we want to pause our current component, 
              run the sub-component, and wait for it to finish. 
              Upon finishing, the <code>wash_dishes</code> sub-component returns a <a>Boolean</a> value denoting its success,
              which is stored in result. 
              (Note that the returned value of the sub-component does not have to be a <a>Boolean</a> value,
              and can actually be any of the <a>atomic</a> or <a>structure</a> data types defined in the previous chapter.)
          </p>
          <p>
              The expressions that follow are again an example of conditional <code>if-else</code> expressions.
              The first expression that evaluates to true will be executed, and the others will be ignored. 
            In this case because we happen to be returning a <a>Boolean</a> value, whenever the result is <code>true</code>,
              the first expression will be executed, and our program defaults to the case 
              beginning with an underscore <code>_</code> as this evaluates to <code>true</code>.
              
              
          </p>

        </section>

        <section>
          <h3><dfn>_args</dfn> builtin</h3>
          <p>
            In the <a>run</a> example we showed how to launch a sub-component by calling, <code>run "wash_dishes" () -> result</code>
            from within the main component. Note the empty parentheses, <code>()</code>, following the name of our sub-component. In DMS
            we can pass arguments to our sub-component by placing all intended parameters (i.e. arguments) within <code>()</code>.
            The sub-component can then access these arguments by unpacking or indexing the builtin <a>_args</a> variable.
            In the following example we show how to pass arguments to our sub-component and access their values using both
            array indexing and unpacking notation.
          </p>
          <p>
            Create two files: <code>jury.dms</code> and <code>decision.dms</code>. Within <code>jury.dms</code> place the
            following code snippet.
          </p>
          <pre class="example">
          once {
              first = "Nishant"
              last = "Shukla"

              run "decision" (first, last) -> verdict {
                  verdict {
                      act "Jail forever."
                  }
                  _ {
                      act "Freedom!"
                  }
              }
          }
          </pre>
          <p>
            Similarly, within <code>decision.dms</code> place the following code snippet. Here we show how to unpack the
            <a>_args</a> builtin variable using both aforementioned notations.
          </p>
          <pre class="example">
          // unpack the array
          first, last = _args
	    
          // or, access the array by index
          first = _args[0]
          last = _args[1]
	  
          pop first == "Nishant" && last == "Shukla"
          </pre>
          <p>
            <b>Note</b>: The <a>_args</a> builtin variable is <a>null</a> in any component that is not called by another
            component, such as a <code>main</code> component, and is otherwise an empty <a>list</a>.
          </p>
        </section>
      </section>
    </section>

    <section>
      <h2><dfn>Effective DMS</dfn></h2>
      <p>
        Beyond this point we begin to define the key ideas that make DMS special. 
        We introduce the notion of what makes DMS a task-oriented programming language and illustrate 
        how tasks can be broken down into actions that have a corresponding utility. 
        With this notion of tasks, actions, and utility we show how DMS allows programmers to rid themselves of the 
        overhead of having to think about the sequential-steps required to achieve a task and simply let DMS 
        pick the best sequence of actions for us. Lets dive in!
      </p>
      <p>
        The <code>fork</code> statement is the most important aspect of DMS.
        It lists possible branches of program flow in a declarative manner.
      </p>
      <p>
        In this section, we'll design a chat-bot that asks "What's the capital of France?". 
        If we type an incorrect answer, such as "Rome", 
        then the script will diagnose the mistake, and help us get to the answer.
      </p>
      <p>
        First, set up a couple variables and constants.
        A <code>score</code> variable will be used to track dialogue quality.
        The entities, such as <code>ROME</code>, and relations, such as <code>CITY_IN</code>, 
        will be declared as variables, just to keep our code clean.
        We'll also track a <code>user_response</code> variable that indicates whether 
        the dialogue has already processed the user's input.
      </p>
      <div>
        <pre class="example">
          once {
            score = 0
            EUROPE, FRANCE, ITALY, ROME, PARIS, LYON = 
                ["Europe", "France", "Italy", "Rome", "Paris", "Lyon"]
            COUNTRY_IN, NEXT_TO, CITY_IN, CAPITAL_OF = 
                ["a country in", "next to", "a city in", "the capital of"]
            user_response = null
          }
        </pre>
        <blockquote>
          <button onclick="return runClicked(this, true);">Run</button>
          <pre></pre>
        </blockquote>
      </div>

      The remaining bit of code obtains the user's input and 
      then interpets the answer. 
      The program loops at the <code>else</code> branch until 
      the <code>user_response</code> variable is reset to <code>null</code>.
      <pre class="example">
        if user_response == null {
          // get the user's input
        } else {
          // interpret the user's input
        }
      </pre>
      
      <p>
        The complete script is shown below.
      </p>

      <div>
        <pre class="example">
          once {
            score = 0
            EUROPE, FRANCE, ITALY, ROME, PARIS, LYON = 
                ["Europe", "France", "Italy", "Rome", "Paris", "Lyon"]
            COUNTRY_IN, NEXT_TO, CITY_IN, CAPITAL_OF = 
                ["a country in", "next to", "a city in", "the capital of"]
            user_response = null
          }
          
          if user_response == null {
              answer = ""
              relation, entity = [CAPITAL_OF, FRANCE]
              act "What is " + relation + " " + entity + ": " + 
                  "Italy, Rome, Paris, or Lyon?"
              input -> response {
                  _ {
                      user_response = response
                  }
              }
          }
          else {
              #{depth: 4, model: [[{score: 10}, {score: 0}]]}
              fork {
                  [relation, entity] == [COUNTRY_IN, EUROPE] {
                      answer = ITALY
                  }
                  [relation, entity] == [NEXT_TO, FRANCE] {
                      answer = ITALY
                  }
                  [relation, entity] == [COUNTRY_IN, EUROPE] {
                      answer = FRANCE
                  }
                  [relation, entity] == [NEXT_TO, ITALY] {
                      answer = FRANCE
                  }
                  [relation, entity] == [CAPITAL_OF, ITALY] {
                      answer = ROME
                  }
                  [relation, entity] == [CITY_IN, ITALY] {
                      answer = ROME
                  }
                  [relation, entity] == [CITY_IN, FRANCE] {
                      answer = LYON
                  }
                  [relation, entity] == [CAPITAL_OF, FRANCE] {
                      answer = PARIS
                  }
                  [relation, entity] == [CITY_IN, FRANCE] {
                      answer = PARIS
                  }
                  relation == CAPITAL_OF {
                      relation = CITY_IN
                      act "Not every city is the captial"
                  }
                  relation == CITY_IN {
                      relation = CAPITAL_OF
                  }
                  relation == CAPITAL_OF {
                      relation = NEXT_TO
                  }
                  relation == NEXT_TO {
                      relation = CAPITAL_OF
                  }
                  entity == FRANCE {
                      entity = ITALY
                      act "I think you're thinking of a different country"
                  }
                  entity == ITALY {
                      entity = FRANCE
                      act "I think you're thinking of a different country"
                  }
                  answer == user_response {
                      user_response = null
                      act answer + " is " + relation + " " + entity
                      score = score + 1
                  }
              }
          }
        </pre>
        <blockquote>
          <button onclick="return runClicked(this, false);">Run</button>
          <pre></pre>
          <input style="display: none;" placeholder="type input here" />
          <button style="display: none;" onclick="return handleIntent(this);">Send</button>
        </blockquote>
      </div>
    </section>
    
  </body>
  
</html>