Re: [Adobe-source-devel] Interest in ASL

[Sean P. <sp...@ad...>]

Hi Robert,
Welcome!

>
> I've been very interested in using ASL for an open source project of  
> mine, however I am having an extreme difficulty learning how to use  
> it. I have read as much documentation as possible on the ASL website  
> but it seems very incomplete to me.

It is incomplete - there is still much writing to do. Here are some  
suggestions to fill in the holes:

Check out the papers and presentations on the wiki:

<http://stlab.adobe.com/wiki/index.php/Papers_and_Presentations>

The ACCU talk goes into a fair amount of detail on both Adam and Eve,  
the Possible Future Talk has some discussion of Adam in the later  
half. The Property Model paper, though technical, is also a good  
source of background information.

Download the sources and the Begin application (binaries available for  
both Mac and Windows on Source Forge. There is a directory full of  
examples of both Adam and Eve files for Begin - most cover test cases  
and techniques but there is also an implementation of the Photoshop  
Image Size dialog as an example.

Also, if you haven't found the main TOC yet, it's here <http://stlab.adobe.com/modules.html 
 >

> The Eve grammar (in the scripting language) is very cryptic and  
> inconsistent to me and very hard to learn/follow. This page is all  
> I've been able to find in regards to documentation for the scripting  
> language. Is there any detailed documentation outlining syntax (What  
> each operator does, etc)? What exactly is the best approach to  
> learning Adam & Eve?

The best approach to learning is to start with the examples and ask  
lots of questions on the list. The documentation for the expression  
syntax (shared by both Adam and Eve) is here <http://stlab.adobe.com/group__expression__reference.html 
 >. A short summary is the basic syntax is very similar to C (except  
dynamically typed).
>
>
> The concepts "Sheets" and "Cells" are also very confusing. When I  
> hear these 2 words my first thought is a spreadsheet, and I have no  
> idea how they relate.

Absolutely - the terms are borrowed from spreadsheets. Cells are named  
instead of having a coordinate system. Within a sheet, "value" cells  
can be either constants or inputs (inputs are intended to be set to  
from outside to initialize the sheet. A colon after the cell name is  
followed by an expression to initialize the cell:

sheet example {
  constant:
	constant_cell : "Initialized with a string";
  input:
	input_cell: 10; // initialized with a number
}

Corresponding to spreadsheet equation cells, you have logic cells and  
output cells (output cells are logic cells that can be read  
externally) - a defines operator "<==" after the cell name is followed  
by the equation:

sheet example {
  constant:
	constant_cell : "Initialized with a string";
  input:
	input_cell: 10; // initialized with a number
  logic:
	logic_cell <== input_cell + 10;
  output:
	output_cell <== { result: logic_cell }; // result is a dictionary  
with the key/value pair "result" and the value of logic cell
}

Unlike a spreadsheet, an Adam sheet can have cells that behave as both  
input and output cells. These are known as "interface" cells and can  
be bound to externally, typically by a UI widget.

sheet example {
  constant:
	constant_cell : "Initialized with a string";
  input:
	input_cell: 10; // initialized with a number
  interface:
	interface_cell : input_cell;
  logic:
	logic_cell <== input_cell + 10;
  output:
	output_cell <== { result: logic_cell }; // result is a dictionary  
with the key/value pair "result" and the value of logic cell
}

By default, if you don't provide an defines operator on an interface  
cell, it is defined to be the identity - the above is equivalent to:

interface_cell : input_cell <== interface_cell;

Interface cells can participate in a relationship with one or more  
other cells using a relate clause - the idea with a relate clause is  
that for any state of the system, one of the defines holds:

sheet example {
  constant:
	constant_cell : "Initialized with a string";
  input:
	input_cell: 10; // initialized with a number
  interface:
	interface_cell : input_cell;
	another_interface_cell;
  logic:
	logic_cell <== input_cell + 10;

	relate {
		interface_cell <== another_interface_cell + 3;
		another_interface_cell <== interface_cell - 3;
	}

  output:
	output_cell <== { result: logic_cell }; // result is a dictionary  
with the key/value pair "result" and the value of logic cell
}


An interface cell can appear in more than one relate clause, and  
relates can have an optional predicate - for example if you want width  
and height to be the same when some predicate p is true it would be  
expressed as:

when (p) relate {
	width <== height;
	height <== width;
}

If you look at the Image Size example you can see how powerful the  
relate clause is.

That's my 2 minute tutorial - hopefully it helps.


> The documentation itself is very technical and isn't a good warmup  
> for beginners to the library. I need something "dummified" that  
> makes it easy to understand how ASL works (Analogies/Examples).

Play with the examples and with the Begin app and ask lots of  
questions - that's currently the best way to learn. Please also point  
out specific holes in the docs (I know there are _many_), knowing what  
people are struggling with helps me to prioritize the work.

> My head is spinning right now, so I hope someone can help point me  
> in the right direction.
>

I hope that help!

Sean