Bunch more work on docs.

2013-12-04 07:46:41 -08:00
parent 047cfacede
commit 8521d5ad79
4 changed files with 203 additions and 8 deletions
--- a/doc/site/flow-control.markdown
+++ 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&mdash;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**
--- a/doc/site/template.html
+++ b/doc/site/template.html
@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="Content-type" content="text/html;charset=UTF-8" />
+<title>Wren - {title}</title>
+<link rel="stylesheet" type="text/css" href="style.css" />
+<link href='http://fonts.googleapis.com/css?family=Sanchez:400|Source+Sans+Pro:300,400,700,400italic,700italic|Source+Code+Pro:300,400' rel='stylesheet' type='text/css'>
+</head>
+<body id="top">
+<a href="https://github.com/munificent/wren">
+  <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 100;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
+</a>
+<div class="header">
+  <div class="page">
+    <h1><a href="index.html">wren</a></h1>
+    <h2>a minimal class-based scripting language</h2>
+  </div>
+</div>
+<div class="page">
+  <div class="nav">
+    <h2>Welcome</h2>
+    <ul>
+      <li>Getting Started</li>
+    </ul>
+    <h2>Language</h2>
+    <ul>
+      <li><a href="syntax.html">Syntax</a></li>
+      <li>Method calls</li>
+      <li>Variables</li>
+      <li>Blocks</li>
+      <li><a href="flow-control.html">Flow control</a></li>
+    </ul>
+    <h2>Types</h2>
+    <ul>
+      <li><a href="values.html">Values</a></li>
+      <li>Classes</li>
+      <li>Functions</li>
+      <li>Fibers</li>
+      <li>Lists</li>
+      <li>Maps</li>
+    </ul>
+    <h2>Usage</h2>
+    <ul>
+      <li>Standalone</li>
+      <li>Embedding</li>
+    </ul>
+  </div>
+  <div class="content">
+<h1>{title}</h1>
+{html}
+<p class="footer">Last modified on {mod}. By Bob Nystrom.</p>
+</div>
+</body>
+</html>
--- a/doc/site/values.markdown
+++ 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.
--- a/43
+++ b/43
@ -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 = """
 <!DOCTYPE html>
 <html>
@ -39,7 +39,7 @@ TEMPLATE = """
      <li>Method calls</li>
      <li>Variables</li>
      <li>Blocks</li>
-      <li>Flow control</li>
+      <li><a href="flow-control.html">Flow control</a></li>
    </ul>
    <h2>Objects</h2>
    <ul>
@ -65,10 +65,23 @@ TEMPLATE = """
 </html>
 """

-def format_file(path):
+def format_file(path, skip_up_to_date):
  basename = os.path.basename(path)
  basename = basename.split('.')[0]

+  out_path = "build/site/" + basename + ".html"
+
+  # See if it's up to date.
+  source_mod = os.path.getmtime(path)
+  source_mod = max(source_mod, os.path.getmtime('doc/site/template.html'))
+
+  dest_mod = 0
+  if os.path.exists(out_path):
+    dest_mod = os.path.getmtime(out_path)
+
+  if skip_up_to_date and source_mod < dest_mod:
+    return
+
  title = ""

  # Read the markdown file and preprocess it.
@ -98,20 +111,34 @@ def format_file(path):

  fields = {'title': title, 'html': html, 'mod': mod_str}

+  with open("doc/site/template.html") as f:
+    template = f.read()
+
  # Write the html output.
-  with open("build/site/" + basename + ".html", 'w') as out:
-    out.write(TEMPLATE.format(**fields))
+  with open(out_path, 'w') as out:
+    out.write(template.format(**fields))

  print "converted", basename

+
+def format_files(skip_up_to_date):
+  for f in glob.iglob("doc/site/*.markdown"):
+    format_file(f, skip_up_to_date)
+
+
 # Clean the output directory.
 if os.path.exists("build/site"):
  shutil.rmtree("build/site")
 os.mkdir("build/site")

 # Process each markdown file.
-for f in glob.iglob("doc/site/*.markdown"):
-  format_file(f)
+format_files(False)

 # Copy the CSS file.
 shutil.copyfile("doc/site/style.css", "build/site/style.css")
+
+# TODO(bob): Check for CSS modification.
+if len(sys.argv) == 2 and sys.argv[1] == '--watch':
+  while True:
+    format_files(True)
+    time.sleep(0.3)