1: FlareSpeak example

FlareSpeak will use semantic whitespacing - like Python, only more so.  Rather than indicating the beginning and end of a function with "BEGIN" and "END", or "{" and "}", FlareSpeak tracks indentation.  For example:

num Calculate(num inFirst, num inSecond, var inThird)
        precondition
            inFirst < inSecond
            inFirst != (inSecond / 2)
        postcondition
            returned >= inThird
    var fourth = inFirst * inSecond
            invariant
                fourth > inThird
    if inThird > 0
        fourth *= 2
    elif inThird < -10 # Why < -10?  Magic numbers!
        fourth *= 8
    else
        fourth *= 3
    if (fourth % 3) == 0
        return inThird
    fourth = (fourth - 3) / 5
    return fourth
Unlike Python, FlareSpeak does not require an extraneous colon at the end of most lines.  All whitespacing is completely determined by the underlying FlareCode.  Thus, for example, fourth % 3 can be cleanly distinguished from fourth%3 and so on.  The "double indentation" shown for the precondition and postcondition elements is used to distinguish between annotations and direct content.

(Ideally, a FlareSpeak IDE should very subtly shade the indented "whitespace" depending on level of indentation, so as to make it even easier to visually determine the boundaries of a method or block statement.)

Because the underlying FlareCode is represented in extensible XML, it should be possible to attach semantic comments in addition to the more usual natural-language comments.  An example of a semantic comment would be HTML produced by editing software and automatically added to documentation, a filename pointing to an MP3 recording of a voice comment with attached text produced by voice recognition, or a timestamp and attribution automatically left by the editing software.

2: FlareCode for above example

A prototype FlareCode representation for the above source code might appear as:

(Please note that this representation was made up on the spot.  The actual FlareCode representation should be almost the last decision made in the language specification.)

<verb>
 <name>Calculate</name>
 <argument><num>inFirst</num></argument>
 <argument><num>inSecond</num></argument>
 <argument><var>inThird</var></argument>
 <variable><num>returned</num></variable>
 <variable>
  <var>fourth</var>
  <invariant>
   <more>
    <left>fourth</left>
    <right>inThird</right>
   </more>
  </invariant>
 </variable>
 <precondition>
  <less>
   <left>inFirst</left>
   <right>inSecond</right>
  </less>
 </precondition>
 <precondition>
  <neq>
   <left>inFirst</left>
   <right>
    <divide>
     <left>inSecond</left>
     <right><num>2</num></right>
    </divide>
   </right>
  </neq>
 </precondition>
 <postcondition>
  <preserve>inThird</preserve>
  <moreeq>
   <left>returned</left>
   <right>
    <access>
     <left>entry</left>
     <right><str>inThird</str><right>
    </access>
   </right>
  </moreeq>
 </postcondition>
 <code>
  <expression>
   <store>
    <left>fourth</left>
    <right>
     <multiply>
      <left>inFirst</left>
      <right>inSecond</right>
     </multiply>
    </right>
   </store>
  </expression>
  <branch>
   <if>
    <condition>
     <more>
      <left>inThird</left>
      <right><num>0</num></right>
     </more>
    </condition>
    <expression>
     <store_multiply>
      <left>fourth</left>
      <right><num>2</num></right>
     </store_multiply>
    </expression>
   </if>
   <if>
    <condition>
     <comment>
      <date>01.12.23:17:53</date>
      <author>Agent Smith</author>
      <str>Why < -10?  Magic numbers!</str>
     </comment>
     <less>
      <left>inThird</left>
      <right><num>-10</num></right>
     </less>
    </condition>
    <expression>
     <store_multiply>
      <left>fourth</left>
      <right><num>8</num></right>
     </store_multiply>
    </expression>
   </if>
   <expression>
    <store_multiply>
     <left>fourth</left>
     <right><num>3</num></right>
    </store_multiply>
   </expression>
  </branch>
  <branch>
   <if>
    <condition>
     <eq>
      <left>
       <modulo>
        <left>fourth</left>
        <right><num>3</num></right>
       </modulo>
      </left>
      <right><num>0</num></right>
     </eq>
    </condition>
    <statement>
     <return>inThird</return>
    </statement>
   </if>
  </branch>
  <expression>
   <store>
    <left>fourth</left>
    <right>
     <divide>
      <left>
       <subtract>
        <left>fourth</left>
        <right><num>3</num></right>
       </subtract>
      </left>
      <right><num>5</num>
     </divide>
    </right>
   </store>
  </expression>
  <statement>
   <return>fourth</return>
  </statement>
 </code>
</verb>

Please note that this representation was made up on the spot.  The actual FlareCode representation should be almost the last decision made in the language specification.  The final designer might come up with a considerably more efficient representation than the one hacked-up above.

On the other hand, despite the apparent awkwardness of the above XML representation, the internal representation might be acceptably fast and powerful.  It's not entirely a matter of "We have the computing power" or "We'll wait for Moore's Law", although such tradeoffs are perfectly acceptable where complex but non-computationally-intensive application logic is concerned.  Also, an early Flare implementation written in, e.g., Perl, might easily incorporate Perl code - in an element named <perl> - for faster execution.

3: FlareSpeak rules

Although FlareSpeak looks like Python, FlareSpeak does not try to be totally, beautifully simple in the way Python does.  Rather, FlareSpeak should not look complicated if you are doing something simple.  However, more complexity than Python is acceptable if something useful is being accomplished.

For example, where Python would write:

if hasattr(object, "property") and object.property:
    object.property = object.property + 4 # (1)
FlareSpeak would write:
if object.?property && object.property
    object.property += 4
One of the major goals in Python is to have a very small, very easily learned set of language idioms.  FlareSpeak does not share this goal.  It shouldn't have endless incomprehensible punctuation *cough*Perl*cough*, but a degree of punctuation about equivalent to that in C++ should be considered acceptable.  FlareSpeak looks like Python on first glance, having imported Python's syntactic whitespacing idiom, but Flare is not Python.

One of Python's advantages is that it is possible to sit down and rapidly begin writing code, without needing to memorize a whole set of exotic operators first.  Ideally, it should be possible to do this in FlareSpeak as well.  However, as greater expertise is acquired, it should become possible to write more complex programs.

Where Python defines only the single operator '.', Flare defines, at least:

foo.bar     # direct reference

foo.?bar    # succeeds if foo (or a parent of foo) has a property 'bar'

foo.%bar    # Planar access; access or store an
            # element 'bar' in the local plane.

foo%plane.bar    # Access a non-local plane.

foo.&bar    # Get a reference to the element foo.bar

baz = 'bar'
foo.(baz)   # Look up property matching content of baz

foo@.bar    # Map access across list 'foo'.  Produce list
            # of results.

.foo = bar  # Set property 'foo' of the object whose instance
            # method we are.  Equals 'this.foo' or 'self.foo'.

Some other known idioms of Flare:
foo =? bar  # Set foo equal to expression `bar` if `bar` succeeds.

*foo        # Dereference a pointer, or something that looks like a
            # pointer, exactly once.  (Usually, references are
            # followed automatically, though.)

`foo + 3`   # Produces an encapsulated expression.

repeat(x)   # Repeat expression x until it fails.

repeat(`foo =? *foo`)   # Follow a chain of pointers to its end.

foo@.doSomething(3)     # Call doSomething(3) on each element in list
                        # foo.  May be carried out in parallel.

foo@.bar()@.baz()       # In parallel, call bar() on each element of
                        # foo, then call baz() on each result as it is
                        # produced.  bar() may return a list, in which
                        # case baz() will be called on each item in
                        # each list returned.

foo[@] += 3     # Add three to each element in list foo.  The Flare
                # interpreter may choose to carry out this operation
                # in parallel.
 

return x        # Return from current method.
                # Succeeds if x is true (nonzero, etc.)

succeed x       # Return x and succeed current expression.
fail x          # Return x and fail current expression.

generate x      # ICON generator syntax (see also Python 2.2).

continuation x  # Delegate responsibility for returning a result
                # to an expression or method with an equivalent
                # return signature.  Pops current method off the
                # stack, and replaces it with the continuation.
 

x.generate(3)   # Call method "generate" on x

generate(3)     # Call method stored in local variable "generate".

generate (3)    # Same as `generate 3`

# All whitespacing is determined and all whitespacing is significant!
# Note - comments can contain italics.
 

# <some-stuff-that-works-just-like-Python>

array[0]   = 1      # Set first member to 1

array[0:1] = void   # Delete first and second members of array.
                    # (In Python, this would be `del array[0:1]`)
                    # del array[0:1]    - also works
                    # array[0:1] = []   - also works

array[0:1] = 1      # Error.

array[0:1] = [1]    # Replace first and second members with a single
                    # member 1.

array[-1]  = 1      # Set last member of array to 1.

# Note:  Somebody must have set the FlareSpeak IDE option "Use up to
# 4 extra spaces to align similar expressions."

array[1:-2]         # Second through second-to-last elements.
array[2:]           # Third through last elements.
array[:4]           # First through fourth elements.

# </some-stuff-that-works-just-like-Python>

array[:]            # Pretty much the same as `array`.

foo.bar[3] = 1      # If foo allows multiple <bar> elements, set
                    # fourth <bar> element to 1.  Fail and except
                    # if three or fewer <bar> elements exist.

foo.bar[3] ?= x     # If four or more bar elements exist, evaluate
                    # and assign x. Note that this reverses the
                    # usual order of evaluation.

array1[@] = array2[@] + 1   # array1 and array2 must have same length.
                            # Set each member of array1 to equal the
                            # equivalent member of array2, plus 1.
                            # May be processed in parallel.

foo.bar[4:10] @?+=? foo.baz   # Adds `foo.baz` to fourth through ninth
                              # elements of `foo.bar`, if those elements
                              # and `foo.baz` exist; operation is carried
                              # out in parallel.  Violates Flare IDE
                              # invariant "No more than 3 sequential
                              # punctuation characters."
 

if 2 < 4            # Call instance method doSomething()
    .doSomething()

if? foo.bar[3]      # If foo has at least four <bar> elements,
    .doSomething()  # call doSomething().  An expression exception
                    # occurring is treated as an ordinary failure.
 

for item in foo.bar     # Do something with each item in a list.
    doSomething(item)   # Carried out in parallel.

for$ item in foo.bar    # As above, but in serial instead of
    doSomething(item)   # parallel.

for& item in foo.bar    # Item points to foo.bar[n]
    item += 3           # In C terms: lvalue instead of rvalue
 

while x                 # Continue with doSomething() until `x` fails.
    .doSomething()

while@ x                # Parallel-while.
    .doSomething(y)     # Fork off each doSomething(), reevaluate `x`,
                        # doSomething() again immediately, until
                        # `x` fails.

while@ item is x        # Set value of item to x on each (parallelized)
    .doSomething(item)  # call to doSomething().

# Note:  for@ and while@ are locally parallel, but the next statement
# is not executed until all parallel subthreads return.  On non-SMP
# machines, the main benefit is that if, i.e., doSomething() is
# waiting on a file operation, the next doSomething() happens while
# the first one is blocking.  On SMP machines, a Flare interpreter
# with 8 processors will actually run 8 times as fast, or at least
# that's the ideal.