Prerequirement

• Windows XP/Vista
• GHC 6.10 or higher

Installation

After downloaded the file, extract the file to any directory you like. You will find a directory structure like follows.

| examples/ |Containing some example programs| |:--------------|:-------------------------------| | src/ |Containing the Beanbag source. The source files are also needed to compile the generated synchronizer.| | beanbag.exe |The main compiler of Beanbag, converting a Beanbag program into a Haskell program.| | compile.bat |Use "compile.bat sourceFile targetExe" to compile a Beanbag program into an exe file.| | run.bat |Use "run.bat sourceFile" to run a Beanbag program directly.|

Walkthrough

This section will guide you compile and run a simple Beanbag program. This article only shows how to use the implementation. For the Beanbag language itself, please refer to the ESEC/FSE'09 paper.

First, let us write a simple Beanbag program, and save it as "basic.beanbag". (This program can also be found in the example directory.)

def main(a, b, c) := b = a and c = b

This simple program keeps three variables equal. To run this program, we type the following command:

run basic.beanbag

The run.bat will first invoke beanbag.exe to compile this program into a Haskell program and then run the Haskell program.

The execution of the program will try to synchronize some updates. After the program starts, we will see the following message.

Please input the values:

Here we need to input the values before user update the data. We may type as follows, which means initially a, b and c are all equal to 1.

{a=1, b=1, c=1}

Then the program will prompt

Please input the updates:

This time we need to tell the program how users have updated program. We may type as follows, which means b is changed to 3 by users.

{b->3}

After the input, the program will prompt the following output, which means all variables should be changed to 3 to make them equal.

output updates: {$a->3, $b->3, $c->3}

Note the program only tells how we should update the data, and does not tell us what the updated data are. To obtain that, we can use the --updatedValues or -v option. Let us try the following input.

Please input the values: {a=1, b=1, c=1} Please input the updates: {a->1}

The user update does not actually change the data. After the input, the synchronizer will produce:

output updates: {} output values: {$a->1, $b->1, $c->1}

The output updates are empty, meaning nothing need to be updated. The second line shows the updated values, which is as same as the original one.

A synchronization may not succeed because the user updates may conflict. For example, given the following input, we will get a message "Synchronization failed".

Please input the values: {a=1, b=1, c=1} Please input the updates: {a->2, b->3} Synchronization failed.

Usually a synchronizer is not invoked through keyboard. It is integrated into an application to synchronize application data. To make it easy for integrating a synchronizer into an application, we provide a silent mode. In this mode the synchronizer produces no prompt message, so that we can easily write programs to interact with the synchronizer through standard IO. This mode is invoked through the option --silentMode or `-s'. The follows shows an execution in the silent mode.

{a=1, b=1, c=1} {b->3} {$a->3, $b->3, $c->3}

The first two lines are input and the third line is output. The prompt message is completely suppressed.

Options of the compiled synchronizer

|--help or -h|print help message| |:-----------|:-----------------| |--updatedValues or -v| show the result of applying the output update to input values| |--fullUpdates or -f| show all updates produced even if it does not changes values| |--sildentMode or -s| print no prompt message(suitable for analysis by programs)|