variables_as_storage.txt

Variables as text storage
=========================

[[Parent]]: variables.txt

This section introduces the basic use of variables in Remark.
Here we view variables as a way to store and retrieve text.

Defining variables
------------------

[[Example]]:
	[[set Gallery.thumbnail_max_width: 500]]
	[[Gallery.thumbnail_max_width]]

[[Example]]:
	[[set some_file_list]]:
		filename.txt
		another.txt
	[[some_file_list]]

[[Example]]:		
	[[set_many]]:
		Gallery.thumbnail_max_width 300
		Gallery.thumbnail_max_height 400
	[[Gallery.thumbnail_max_width]]
	[[Gallery.thumbnail_max_height]]

[[Example]]:		
	[[set_many Gallery]]:
		thumbnail_max_width 200
		thumbnail_max_height 100
	[[Gallery.thumbnail_max_width]]
	[[Gallery.thumbnail_max_height]]

Note that with `set_many` it is not possible to assign multi-line parameters.

Appending to a variable
-----------------------

[[Example]]:
	[[set some_file_list]]:
		filename.txt
		another.txt
	[[add some_file_list]]:
		third_file.txt
	[[some_file_list]]

### Alternative 

[[Example]]:
	[[set some_file_list]]:
		filename.txt
		another.txt
	[[+set some_file_list]]:
		[[some_file_list]]
		third_file.txt
	[[some_file_list]]

However, 

[[Verbatim]]:
	[[set some_file_list]]:
		filename.txt
		another.txt
	[[set some_file_list]]:
		[[some_file_list]]
		third_file.txt
	[[some_file_list]]

sends Remark into a never-ending loop (Python cuts the recursion).

Variable scopes
---------------

Each variable lives in some scope which defines its visibility and 
life-time. Each macro-invocation creates a child-scope into the 
current scope. Variables defined inside the macro-invocation are 
placed into this scope. When a macro finishes, its scope is closed 
and all the local variables in the scope are destroyed. When no 
macro invocations are active, the only active scope is the _global 
scope_. Child scopes can refer to variables in the parent scopes, 
but not vice versa. When a variable that does not exist in the 
current scope is set, a new local variable is created.

[[Example]]:
	[[set word: world]]
	[[set my_macro]]:
	    [[set word: jello]]
		Hello [[word]]!
	[[my_macro]]
	word = [[word]]

That is, the variable `word` inside `set my_macro` is introduced as a 
local variable and hence does not affect the variable `word` at the 
outer scope.

### Retrieving a variable in an outer scope 

The `get` command will look at outer scopes if a variable is not
found at the local scope. However, when there is _both_ a local variable 
and a variable of the same name in an outer scope, the latter can be 
retrieved with the `outer` command.    

[[Example]]:
	[[set word: world]]
	[[set my_macro]]:
		[[set word: jello]]
		Hello [[outer word]]!
	[[my_macro]]
	word = [[word]]
	
### Setting a variable in an outer scope 

The `set` command always creates a local variable. You
can use the `set_outer` command to set an existing variable
at an outer scope. In case no such variable is found, a
new variable is created at the global scope. 

[[Example]]:
	[[set word: world]]
	
	[[set my_macro]]:
		[[set word: cello]]
		[[set_outer word: jello]]
		Hello [[word]]!
		Hello [[outer word]]!
	[[my_macro]]
	word = [[word]]
	
### Appending a variable in an outer scope.

The `add_outer` command works similarly to `set_outer`,
but instead of assigning, it appends text.