From 8521d5ad7989d71ca9c383783b9a009e328aec28 Mon Sep 17 00:00:00 2001 From: Bob Nystrom Date: Wed, 4 Dec 2013 07:46:41 -0800 Subject: [PATCH] Bunch more work on docs. --- doc/site/flow-control.markdown | 65 ++++++++++++++++++++++++++++++++++ doc/site/template.html | 54 ++++++++++++++++++++++++++++ doc/site/values.markdown | 49 +++++++++++++++++++++++++ make_docs | 43 +++++++++++++++++----- 4 files changed, 203 insertions(+), 8 deletions(-) create mode 100644 doc/site/flow-control.markdown create mode 100644 doc/site/template.html create mode 100644 doc/site/values.markdown diff --git a/doc/site/flow-control.markdown b/doc/site/flow-control.markdown new file mode 100644 index 00000000..bbf2fe2d --- /dev/null +++ b/doc/site/flow-control.markdown @@ -0,0 +1,65 @@ +^title Flow Control + +## Truthiness + +Flow control is about evaluating an expression and then choosing which code to execute based on whether or not the result is "true". That's easy if the value happens to be a boolean, but what if it's some other type? + +Languages handle this by having a set of rules for what values of any given type are "true" and will cause a condition to be met. Wren calls this "truthiness" and "falsiness". The rules are simple (and follow Ruby): + + * The boolean value `false` is falsey. + * The null value `null` is falsey. + * Everything else is truthy. + +This means `0`, empty strings, and empty collections are all considered truthy values. + +## If statements + +The simplest flow control structure, `if` lets you conditionally skip a chunk of code. It looks like this: + + :::wren + if (ready) io.write("go!") + +That will evaluate the parenthesized expression after `if`. If it's truthy, then the expression after the condition is evaluated. Otherwise it is skipped. Instead of an expression, you can have a block: + + :::wren + if (ready) { + io.write("getSet") + io.write("go!") + } + +You may also provide an `else` branch. It will be evaluated if the condition is falsey: + + :::wren + if (ready) io.write("go!") else io.write("not ready!") + +And, of course, it can take a block too: + + if (ready) { + io.write("go!") + } else { + io.write("not ready!") + } + +## The logical operators `&&` and `||` + +The `&&` and `||` operators are lumped here under flow control because they conditionally execute some code—they short-circuit. Both of them are infix operators, and, depending on the value of the left-hand side, the right-hand operand expression may or may not be evaluated. + +An `&&` ("logical and") expression evaluates the left-hand argument. If it's falsey, it returns that value. Otherwise it evaluates and returns the right-hand argument. + + :::wren + io.write(false && 1) // false + io.write(1 && 2) // 2 + +An `||` ("logical or") expression is reversed. If the left-hand argument is truthy, it's returned, otherwise the right-hand argument is evaluated and returned: + + :::wren + io.write(false || 1) // 1 + io.write(1 || 2) // 1 + +## While statements + +**TODO** + +## For statements + +**TODO** diff --git a/doc/site/template.html b/doc/site/template.html new file mode 100644 index 00000000..b65e4175 --- /dev/null +++ b/doc/site/template.html @@ -0,0 +1,54 @@ + + + + +Wren - {title} + + + + + + Fork me on GitHub + +
+
+

wren

+

a minimal class-based scripting language

+
+
+
+
+

Welcome

+
    +
  • Getting Started
    • +
+

Language

+ +

Types

+
    +
  • Values
    • +
  • Classes
    • +
  • Functions
    • +
  • Fibers
    • +
  • Lists
    • +
  • Maps
    • +
+

Usage

+
    +
  • Standalone
    • +
  • Embedding
    • +
+
+
+

{title}

+{html} +

Last modified on {mod}. By Bob Nystrom.

+
+ + \ No newline at end of file diff --git a/doc/site/values.markdown b/doc/site/values.markdown new file mode 100644 index 00000000..24d1abf5 --- /dev/null +++ b/doc/site/values.markdown @@ -0,0 +1,49 @@ +^title Values + +Values are the built-in object types that all other objects are composed of. +They can be created through *literals*, expressions that evaluate to a value. + +All value types in Wren are immutable. That means that once created, they +cannot be changed. `3` is always three and `"hi"` is always `"hi"`. + +## Booleans + +A boolean value represents truth or falsehood. There are two boolean literals, +`true` and `false`. Its class is `Bool`. + +## Numbers + +Like other scripting languages, Wren has a single numeric type: double-precision floating point. Number literals look like you expect coming from other languages: + + :::wren + 0 + 1234 + -5678 + 3.14159 + 1.0 + -12.34 + +Numbers are instances of the `Num` class. + +## Strings + +Strings are chunks of text. String literals are surrounded in double quotes: + + :::wren + "hi there" + +A couple of escape characters are supported: + + :::wren + "\n" // Newline. + "\"" // A double quote character. + "\\" // A backslash. + +Their class is `String`. + +## Null + +Wren has a special value `null`, which is the only instance of the class `Null`. +(Note the difference in case.) It functions a bit like `void` in some +languages: it indicates the absence of a value. If you call a method that +doesn't return anything and get its returned value, you get `null` back. diff --git a/make_docs b/make_docs index 63fdd30b..23a2b3af 100755 --- a/make_docs +++ b/make_docs @@ -4,10 +4,10 @@ import glob import markdown import os import shutil +import sys +import time from datetime import datetime -# from finch import FinchLexer - TEMPLATE = """ @@ -39,7 +39,7 @@ TEMPLATE = """
  • Method calls
  • Variables
  • Blocks
    • -
  • Flow control
    • +
  • Flow control

    • Objects