How to write a Promiserver promise
This post is my first attempt to explain how to write Promiserver code. This will eventually also find its way into a Promiserver help section, but I thought I’d try it out here first.
Breach and Success
There are two reserved methods: breach and success. Each takes an optional message parameter. Your code defines the conditions under which the promise breaches or succeeds. For example, a really simply promise would be:
if condition_x success "it happened!" end
The value of the condition_x variable determines whether the promise evaluates to success. When condition_x evaluates to true, the promise will be evaluated as a success, with corresponding message “it happened!”. A marginally more sophisticated promise might look like this:
if condition_x success "x happened!" elsif condition_y breach "sorry, y happened" end
In this one we have possibility of a breach as well, if condition_y evaluates to true.
Promise State
Those variables like condition_x and condition_y aren’t defined anywhere in this code. This means that they are free variables.
All these free variables in your promise code are extracted as you write the promise, and together form the state of the promise. When writing the promise, you can change the values of these variables to the desired initial state. Once published and signed, all participants can also change the values of these variables.
Time
Most promises are commitments with respect to some future action or event. So it may make sense to take time into account.
if document_received success "thanks, nice work" elsif Time.now > document_deadline breach "missed the deadline end
Again, document_deadline and document_received become promise state variables, meaning they can be changed by the participants. If we wanted to fix the deadline and remove it from the state, we could simply add in a line.
document_deadline = Time.parse("5/11/2007 6:00pm")
if document_received
success "thanks, nice work"
elsif Time.now > document_deadline
breach "missed the deadline
end
Keep in mind that Time.now evaluates differently each time the promise is evaluated. Future versions of Promiserver will have a timeline or calendar view, to try out the code for different times in the future.
Ruby Niceness
Since we’re using Ruby with some special activesupport magic, we can use some cool shortcuts. For example, say we want to allow for an extension:
...
if Time.now > (final_date = deadline + extension.days)
breach "missed the extended deadline #{final_date}"
end
...
This is just a starting point. I have a few people using the system now, and in particular Burak has been a great tester, authoring some promises that have pushed Promiserver a little our of its comfort zone. So we’ll see how this contract-as-code idea continues to develop.
rss
