Stan reference: local variables

[tmalsburg]

The term local variable is used a lot in the manual but it is difficult to extract a complete definition. For example, section 25.7 says:

At the beginning of each block, local variables may be declared that are scoped over the rest of the
statements in the block.

However, since all variables are defined at the beginning of a block, that would mean that all variables are local, which is clearly not the case. On the other hand, the section variable scope explains that variables declared in one program block are visible in subsequent blocks except for variables declared in the model block. This section, however, fails to mention that this is not the case for variables declared in nested blocks.

I think it would help if there was one place in the manual that gives the whole story. It may also make sense to use this opportunity to clarify why the term global variable isn't used (only variables in the data block are global).

[bob-carpenter]

Thanks. That's a good idea---the descriptions are confusing as is.

I moved the issue to the long-term manual updates (that's where non-bug issues with the manual go and I get to them when I can):

https://github.com/stan-dev/stan/issues/1238#issuecomment-97313609

The trouble with global vs. local is a bit tricky --- every variable is "local" in the programming language sense of being like variables declared in the block of a function definition because there's no forward reference mechanism for truly global variables of the kind you see in C. And the data variables are odd in that they're more like function arguments than they are like local variable declarations. I'll think about how to clarify all this in one section.

[davidmanheim]

@bob-carpenter I think part of the confusion (and if I'm wrong, it probably points to a different confusion) is that there is a distinction between 'program (execution) blocks', or 'named blocks' on the one hand, and 'statement blocks' or local blocks on the other. Program execution blocks are the ones that are defined in the language, and statement blocks are additional ones that you can put inside those.

If I understand correctly, any variable declared in the beginning of a named block (excluding the function block, maybe?) is global, anything declared inside a statement block is local.

[bob-carpenter]

Closed issues are probably not the best place for a discussion. Your definition's part of the way there.

A variable defined in the beginning of one of the named blocks other than the model block can be used anywhere after it's defined. A variable defined in an anonymous local block can only be used in that block.

A variable can only ever be defined in the block in which it is declared (this goes for named and local blocks).