ceml 0.2.1 → 0.3.0

data/README.markdown

@@ -3,9 +3,9 @@ Introducing CEML
 
 CEML is the world's first programming language custom-built for bringing people together.
 
-It's for describing live coordinated events among people with different roles and across places.
+Short scripts define the structure for live coordinated events among people with different roles and across locations.
 
-All assignments and reassignments given through Groundcrew are actually CEML programs which are then executed on the server, resulting in a test message-, IM-, or mobile application-based coordination.
+All assignments and reassignments given in Groundcrew are CEML programs that are submitted via our API and executed on the server.  Scripts can result in a text message, IM, twitter, and mobile application-based coordination.
 
 A sample program
 ----------------
@@ -76,7 +76,7 @@ Also helps the user or the system pick which agents to involve, based on their s
 Reference - Syntax
 ------------------
 
-The syntax is simple and a bit like a cross between tcl and ruby.  Every line starts with a command keyword, some arguments, and possibly a string after a colon.  The terminal string parameter can be indented on the following line.
+The syntax is simple and inherits from tcl and ruby.  Every line starts with a command keyword, some arguments, and possibly a string after a colon.  Like RFC822 headers, a terminal string parameter can fall either directly after a colon or on a series of indented line.
 
 Copyright
 ------------------

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/beginners-guide.md

@@ -0,0 +1,214 @@
+Beginners Guide to CEML
+=======================
+
+Thanks for taking an interest in CEML, the Coordinated Event Modeling Language.  Using CEML you'll be able to get people to do whatever you want, whether it's evacuating a submarine, finding a gym buddy, helping people nearby, or just throwing a great party.
+
+A CEML _script_ is a recipe for action.  Just like a recipe, it has three parts: a title, a list of ingredients, and then a section that says what to do with the ingredients.  Here's an example:
+
+    "Trade favorite colors"
+    gather 1 answerer and 1 listener within 50 feet
+    ask answerer re favorite_color:
+        What's your favorite color?
+    tell listener:
+        Someone nearby likes the color |answerer.favorite_color|.  Find them.
+
+In the example, the first line is the title, which is written in double quotes.  The second line is the ingredients and how they are obtained.  In CEML, the ingredients are usually people (although sometimes they can be places, things, or notes).  The remaining lines are the instructions.
+
+A good way to learn how flexible CEML is is to write the same script a different way.  Then you can see which parts can change and which parts have to stay the same:
+
+    "Trade favorite colors"
+    gather a, b within 50ft
+    ask a re x: What's your favorite color?
+    tell b: Someone nearby likes the color |a.x|.  Find them.
+
+Whether you write a script compactly with short names for roles and answers or long names, it runs exactly the same.
+
+Commands
+--------
+
+The above script only uses three CEML commands—*gather*, *ask*, and *tell*—but there aren't many more commands to learn.  Only four more, actually: besides *gather*, the other ingredients commands are *await* and *nab*.  Besides *ask* and *tell*, the other instructions commands are *assign* and *certify*.
+
+As a sneak preview, here's an example that uses the other commands:
+
+    "Emergency Medicine"
+    await 1 concerned patient
+    nab a doctor within 5 miles
+    ask patient re problem: What's wrong?
+    assign doctor to patient: Attend to patient's |problem|.
+    certify doctor as responsive
+
+Texts
+-----
+
+Commands like *ask*, *tell*, and *assign* contain texts which are delivered to the player who is the subject of the command.  These texts appears after a colon, and can appear on the same or the following lines.  If they appears on the following lines, they must be indented, as in the very first example above or the one following.
+
+    "Signups"
+    await 1 new signup
+    tell signup:
+        We are so glad
+        that you have
+        signed up.
+
+Texts may also contain hyperlinks, which if the player has a smartphone with a web browser, will be openable.
+
+    "Hostility"
+    gather enemy, reporter within 1 block
+    ask reporter re clothing: What are you wearing?
+    assign enemy: Find someone wearing |clothing| and harass them.
+    assign reporter:
+        Someone will harass you.  Notice how it feels.
+        Then fill out this google spreadsheet form
+        to describe your experience.
+        http://spreadsheet.google.com/foo
+    tell both: thanks so much for participating!
+
+Roles
+-----
+
+In the examples so far, the words like 'enemy', 'reporter', 'answerer', 'listener', 'a', 'b', 'signup', 'patient', and 'doctor' are *role names*.  Most of the time, a role name can be any word you like.  They are just a placeholder to connect *casting commands* like *gather* and *await*, with *coordination commands* like *tell*.
+
+Squads on Groundcrew, however, can define special meanings for certain roles.  So on a particular squad, a 'doctor' might mean someone who's been tagged/certified with the tag 'doctor', and a patient might mean anyone else.
+
+Some role names are always special.  For instance, if you use the role name 'organizer', it always means someone who's an official organizer for that squad.  And if you use the role names 'both', 'all', 'each', or 'everyone', it means that the instruction applies to everyone regardless of how they were *cast*.
+
+    "Get Help"
+    await concerned user
+    nab organizer
+    tell organizer: someone's not doing well.
+
+When there is only one kind of role in a script, it is possible to omit the role name in instructional commands.
+
+    await 1 tired user
+    ask re cause: why are you tired?
+    tell: i hope you feel better
+
+Social Information
+------------------
+
+Texts (see above) may contain *social information* that's inserted from answers by another player.  To do this, we use a section surrounded by vertical bars (|).  In the text that's sent to the player, this section will be replaced by the other player's answer.
+
+    "Empire"
+    gather emperor and 2-5 servants
+    ask emperor re tasks: What should your servants do today?
+    assign servants: The emperor has asked you to do |tasks|. Do them now.
+
+In situations where there may be confusion about which answer you mean, you can specify a particular role by using a dot (.) in between the role and the answer names.
+
+    "Cheese Monte"
+    gather a,b,c
+    ask each re cheese: What kind of cheese do you have?
+    tell a: Someone near you has |c.cheese|. Take it!
+    tell b: Someone near you has |a.cheese|. Take it!
+    tell c: Someone near you has |b.cheese|. Take it!
+
+Assign
+------
+
+It is probably clear what *ask* and *tell* do, but we haven't exactly covered *assign*.  *Assign* gives a task which is expected to last a certain duration.  While a *tell* command for a particular player completes immediately and goes on to the next command, an *assign* will wait for the player to say they've completed the task, and collect photo and textual reports as they do it.  There are different representations for this depending on whether the player is connected to the script via text messaging, the iphone, or the mobile web.
+
+A special form of *assign* will additionally direct the player to a person or place where they are supposed to go.
+
+    "Streetcorner Observation"
+    gather player, streetcorner within 5 blocks
+    assign player to streetcorner:
+        Go there and report what you observe.
+
+On iPhone or mobile web, the player will get a little map to direct them.  There are several special *role names* which are used to indicate places rather than people.  These include "streetcorner", "park", "field", and "landmark".
+
+Choosing Players: Await, Gather, and Nab.
+----------------------------------------------
+
+So what is really the difference between *await*, *gather*, and *nab*, you may be asking?  Or perhaps you have already figured it out.
+
+*Await* defines a kind of trigger—as soon as the conditions awaited for are met, the script will run.
+
+    await 2-5 level1 players within 50ft
+    assign: shout out "woo-hoo!"
+    certify as level2 not level1
+
+Unless there's an await statement in your script, it will have to be executed manually by an organizer.
+
+*Gather* issues invitations.  It will keep issuing invitations and processing people's replies to them until it has the requisite number of players for its roles.
+
+    "Pick-up basketball"
+    gather 4-8 basketball players within 4 blocks
+
+*Nab* just involves people, straight up, without asking their permission or issuing them an invitation.
+
+By default, the people that triggered an *await* script are nabbed, not gathered.  That means they will never receive an invitation.  If you want to make sure they accept, you need an *await* line and a *gather* line for the same role name.
+
+    "A study about vomitting"
+    await 5 sick users
+    gather 2-5 users
+    ask re feeling: how do you feel?
+
+Qualifying players
+------------------
+
+You may have noticed that some of the *await*, *gather*, and *nab* statements have adjectives or qualifiers before the role name.  For instance, the word "sick" in "sick users" above is such a qualifier.  So is "basketball", "level1", "tired", "concerned", and "new".
+
+Some of these have special meanings:  the qualifier *new* is automatically applied to new signups.  So if your script has an *await* command that looks for someone new, it will automatically run on signup.
+
+    await 3 new signups
+    assign:
+        You have all just signed up!
+        Take a photo of something you
+        love and share with one another.
+
+Another qualifier with a special meaning is *concerned*.  This is applied to players who, because of their text messaging or their tweeting or their interaction with the iphone or web apps, seem like are confused or have an urgent question or issue.
+
+The other qualifiers don't mean anythings special, but they select only players who have been certified or tagged with that particular word.  So "gather 5-20 level1 users" will only invite users who have been tagged or certified as level1.
+
+Certifying
+----------
+
+When a player has successfully completed their role in your script, you can add or change the tags associated with that player using the *certify* command.
+
+    await 3 new signups
+    assign:
+        You have all just signed up!
+        Take a photo of something you
+        love and share with one another.
+    certify as photo_sharing
+
+Making Connections between Scripts
+----------------------------------
+
+*Certify* and qualifications can be used to link scripts together.  The certification at the end of the first script can trigger the *await* statement in the next script.  Here's an example:
+
+    await 20 photo_sharing users
+    ask re opinion:
+        How did you like sharing photos just now?
+    certify as signed_up not photo_sharing
+
+Congratulations
+---------------
+
+You now know the basics of CEML and can start brainstorming your own scripts.  If you don't have a squad already, contact us at Groundcrew and we'll get you set up.
+
+We will also be creating a google group for CEML developers soon.  Write info@groundcrew.us to make sure you're on it.
+
+----
+
+FAQ
+----------------
+
+### Do I need a title for every script?
+
+You may have noticed that some of the script examples given in this guide do not have titles.  Titles can be omitted under certain conditions.  The main issue is that if a script has a *gather* statement then it MUST have a title.  This is because the invitations that are issued contain the script title.  Otherwise, titles are still often good to have:  if the script is run manually it must have a title so that organizers can select it, and when users are running one of our smartphone clients like the iPhone app or the HTML5 webpage, they will see the title if there is one.  The title will also be associated with any long-lasting media and reports that come from running the script.
+
+### What if I want to share documents or notes in a script?
+
+The February or March 2011 version of CEML will support passing and curating notes and documents between scripts.  This will allow for a mix of flashmob and knowledge work-style coordination.  Syntax is not finalized, but something like:
+
+    await designer
+    assign:
+        sketch out a design for something you
+        want to build and take a photo
+    document as designer_photo
+    certify designer_photo as unreviewed
+
+    await 6 reviewers and unreviewed designer_photo document
+    ask reviewers re opinion:
+        What do you think of this idea? |designer_photo|
+    certify designer_photo as reviewed not unreviewed

data/examples/breakfast-exchange.ceml

@@ -1,15 +1,16 @@
 "a breakfast exchange"
-gather 2 agents within 1 block
-takes 45m
+await 2 players within 1 block
 
-tell agents:
+assign players:
   Okay, you need to make breakfast for a stranger and hide it
   somewhere public in town.  Do it fast, cause in 30m I will ask
   you where you hid it and tell you where to find yours.
 
-after 30m
-ask agents re where:
+give players 30m
+
+ask players re breakfast_location:
   Where did you hide your breakfast?
-tell agents:
-  Go find your breakfast at |otherguy.where|.  Send back any reports.
+
+tell players:
+  Go find your breakfast at |each_other.breakfast_location|.  Send back any reports.
   Thanks for playing!

data/examples/citizen-investigation.ceml

@@ -1,24 +1,25 @@
 "a citizen investigation"
 takes 20m
-involves 1 photographer, 1-2 interviewers, 1-3 reporters, 1 topic, 1 location
-
 offers connection inclusion democracy adventure
 
-ask photographer re clothing: What are you wearing?  (so the others can recognize you?)
+involves 1 photographer, 1-2 interviewers, 1-3 reporters, 1 topic, 1 location within 5 mi
+
+ask photographer re clothing:
+    What are you wearing?  (so the others can recognize you?)
 
-tell photographer:
+assign photographer:
   go to |location|.  the other members of your team will find you.
   research |topic| by taking photos and sending them back to this number.
   do this for |duration|
 
 
-tell interviewers:
+assign interviewers:
   go to |location| and find someone wearing |clothing|.  that's your photographer.
   your assignment is to interview people to research |topic|
   do this for |duration|
 
 
-tell reporters:
+assign reporters:
   go to |location| and find someone wearing |clothing|.  that's your photographer.
   your assignment is to to research |topic| and send back textual reports
   do this for |duration|.  good luck!

data/lib/ceml.rb

@@ -9,27 +9,39 @@ require 'ceml/tt/casting'
 require 'ceml/tt/instructions'
 require 'ceml/tt/scripts'
 
-require 'ceml/engine'
+require 'ceml/incident'
+
+module CEML
+  extend self
+  attr_accessor :delegate
+  @delegate = Class.new{ def method_missing(meth, *args, &blk);end }.new
+  # puts "#{meth}: #{args.to_s.inspect}"
+end
+
+class CEML::ScriptsParser
+  def parse_with_root(string, root)
+    self.root = root
+    parse(string)
+  end
+end
 
 module CEML
   def parse(what, string)
     result = nil
     string.gsub!(/\n +/, ' ')
     string << "\n"
-    p = ScriptsParser.new
-    p.root = what
-    result = p.parse(string)
-    raise "parse failed: \n#{p.failure_reason}" unless result
-    case what
-    when :scripts
-      raise "no scripts found" unless result.elements and !result.elements.empty?
-      result = result.elements
-      result.each{ |s| s.validate! }
-    when :script
-      result.validate!
+    ScriptsParser.new.tap do |parser|
+      result = parser.parse_with_root(string, what)
+      raise "parse failed: \n#{parser.failure_reason}" unless result
+      case what
+      when :scripts
+        raise "no scripts found" unless result.elements and !result.elements.empty?
+        result = result.elements
+        result.each{ |s| s.validate! }
+      when :script
+        result.validate!
+      end
     end
     result
   end
-
-  extend self
 end

data/lib/ceml/{engine.rb → incident.rb}

@@ -1,42 +1,40 @@
 require 'set'
 
 module CEML
-  class Dummy
-    def method_missing(meth, *args, &blk)
-      # puts "#{meth}: #{args.to_s.inspect}"
-    end
-  end
-
-  class Engine
-    attr_reader :script, :parts
-    def this;       @parts[@current_id]; end
+  class Incident
+    attr_reader :script
+    def this;       players[@current_id]; end
     def roles;      this[:roles] ||= Set.new; end
     def got;        this[:received];   end
     def recognized; this[:recognized]; end
     def pc;         this[:pc] ||= 0;   end
+    def qs_answers; this[:qs_answers] ||= Hash.new; end
 
-    def initialize(script_text, delg = Dummy.new)
+    def initialize(script_text, id = rand(36**10).to_s(36))
       @script = CEML.parse(:script, script_text)
-      @delg   = delg
-      @parts  = {}
-      @seq    = {}
+      @id     = id
+    end
+
+    def players
+      @players ||= CEML.delegate.players(@id) || {}
     end
 
     def add(id, *roles)
       obj = Hash === roles[-1] ? roles.pop : {}
-      parts[id] = obj.merge :roles => Set.new(roles)
+      players[id] = obj.merge :roles => Set.new(roles)
     end
 
     def run
-      :loop while parts.keys.any? do |@current_id|
+      :loop while players.keys.any? do |@current_id|
         # puts "trying: #{@current_id}: #{seq[pc]}"
         next unless seq[pc] and send(*seq[pc])
-        @delg.send(*seq[pc] + [@current_id])
+        CEML.delegate.send(*seq[pc] + [@iid, @current_id])
         this[:pc]+=1
       end
     end
 
     def seq
+      @seq ||= {}
       @seq[roles] ||= begin
         bytecode = [[:start]]
         instrs = script.instructions_for(roles)
@@ -67,14 +65,10 @@ module CEML
       this.merge! params
     end
 
-    def qs_answers
-      this[:qs_answers] ||= Hash.new
-    end
-
     def expand(role, var)
       role = nil if role == 'otherguy'
       role = role.to_sym if role
-      parts.each do |key, thing|
+      players.each do |key, thing|
         next if key == @current_id
         next if role and not thing[:roles].include? role
         value = (thing[:qs_answers]||{})[var] and return value
@@ -121,7 +115,7 @@ module CEML
         say :ok
         true
       else
-        @delg.send :did_report
+        CEML.delegate.send :did_report
         false
       end
     end

data/lib/ceml/script.rb

@@ -30,6 +30,10 @@ module CEML
       casting_statement.empty? ? nil : casting_statement
     end
 
+    def max_to_invite
+      dramatis_personae ? dramatis_personae.max : 0
+    end
+
     alias_method :dp, :dramatis_personae
 
     def simple?
@@ -99,5 +103,44 @@ module CEML
     def concludes_immediately?
       !title and instructions.asks([:agents]).empty?
     end
+
+    def color(odds)
+      return :red    if odds < 0.1
+      return :yellow if odds < 0.4
+      return :green
+    end
+
+    def likelihood(yesprob, needed, psize)
+      return 1 if needed <= 0
+      return 0 if psize < needed
+      return (needed..psize).inject(0) do |memo, yes_count|
+        memo + begin
+          no_count = psize - yes_count
+          ways_it_could_happen = psize.choose(yes_count)
+          prob_of_each = (yesprob ** yes_count) * ((1 - yesprob) ** no_count)
+          ways_it_could_happen * prob_of_each
+        end
+      end
+    end
+
+    def availabilities(potential_count, committed_count = 0)
+      return {} unless script.dramatis_personae
+      min        = script.dramatis_personae.min
+      needed     = min - committed_count
+      possible   = potential_count + committed_count
+      yesprob    = 0.7  # just make this up for now
+      odds       = likelihood(yesprob, needed, potential_count)
+
+      {
+        :odds => odds, :color => color(odds),
+        :availability_counts => {
+          :total => possible,
+          :unknown => potential_count
+        },
+        :estimated_size => yesprob * potential_count + committed_count,
+        :needed => min
+      }
+    end
+
   end
 end

data/test/helper.rb

@@ -26,7 +26,7 @@ ENDOFSCRIPT
 
 class Test::Unit::TestCase
   def play script
-    @e = CEML::Engine.new(script)
+    @e = CEML::Incident.new(script)
   end
 
   def player id, *roles
@@ -35,21 +35,21 @@ class Test::Unit::TestCase
   end
 
   def asked id, rx
-    p = @e.parts[id]
+    p = @e.players[id]
     assert_equal :ask, p[:said]
     assert_match rx, p[:q]
     p.delete :said
   end
 
   def told id, rx
-    p = @e.parts[id]
+    p = @e.players[id]
     assert_match rx, p[:msg]
     p.delete :said
   end
 
   def says id, str
-    @e.parts[id][:received] = str
+    @e.players[id][:received] = str
     @e.run
-    @e.parts[id][:received] = nil
+    @e.players[id][:received] = nil
   end
 end

data/test/{test_engine.rb → test_incident.rb}

@@ -1,9 +1,9 @@
 require 'ceml'
 require 'test/helper'
 
-class TestEngine < Test::Unit::TestCase
+class TestIncident < Test::Unit::TestCase
 
-  def test_engine
+  def test_incident
     play COMPLIMENT_SCRIPT
     player :joe, :organizer, :agent
     player :bill, :agent

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Joe Edelman
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-07 00:00:00 -07:00
+date: 2010-12-24 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -46,6 +46,7 @@ files:
 - README.markdown
 - Rakefile
 - VERSION
+- beginners-guide.md
 - editors/CEML.tmbundle/Syntaxes/ceml.tmLanguage
 - editors/CEML.tmbundle/info.plist
 - examples/breakfast-exchange.ceml
@@ -53,7 +54,7 @@ files:
 - examples/high-fives.ceml
 - lib/ceml.rb
 - lib/ceml/casting.rb
-- lib/ceml/engine.rb
+- lib/ceml/incident.rb
 - lib/ceml/instructions.rb
 - lib/ceml/script.rb
 - lib/ceml/tt/casting.rb
@@ -66,7 +67,7 @@ files:
 - lib/ceml/tt/scripts.treetop
 - test/helper.rb
 - test/test_casting.rb
-- test/test_engine.rb
+- test/test_incident.rb
 - test/test_instructions.rb
 - test/test_scripts.rb
 has_rdoc: true
@@ -102,6 +103,6 @@ summary: a language for coordinating real world events
 test_files: 
 - test/helper.rb
 - test/test_casting.rb
-- test/test_engine.rb
+- test/test_incident.rb
 - test/test_instructions.rb
 - test/test_scripts.rb