Skip to content

Commit

Permalink
doctests for manual/variables-and-scoping.md, [ci skip]
Browse files Browse the repository at this point in the history
  • Loading branch information
@fredrikekre
fredrikekre committed Jan 26, 2017
1 parent e723a62 commit 788827c
Showing 1 changed file with 51 additions and 65 deletions.
116 changes: 51 additions & 65 deletions doc/src/manual/variables-and-scoping.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ rules; this section spells them out in detail.

Certain constructs in the language introduce *scope blocks*, which are regions of code that are
eligible to be the scope of some set of variables. The scope of a variable cannot be an arbitrary
set of source lines; instead, it will always line up with one of these blocks. There are two
main types of scopes in Julia, *global scope* and *local scope*, the latter can be nested. The
set of source lines; instead, it will always line up with one of these blocks. There are two
main types of scopes in Julia, *global scope* and *local scope*, the latter can be nested. The
constructs introducing scope blocks are:

| Scope name | block/construct introducing this kind of scope |
Expand All @@ -20,25 +20,25 @@ constructs introducing scope blocks are:
| [Local Scope](@ref) | [Hard Local Scope](@ref): functions (either syntax, anonymous & do-blocks), `type`, `immutable`, `macro` |

Notably missing from this table are [begin blocks](@ref man-compound-expressions) and [if blocks](@ref man-conditional-evaluation), which do *not*
introduce new scope blocks. All three types of scopes follow somewhat different rules which will
introduce new scope blocks. All three types of scopes follow somewhat different rules which will
be explained below as well as some extra rules for certain blocks.

Julia uses [lexical scoping](https://en.wikipedia.org/wiki/Scope_%28computer_science%29#Lexical_scoping_vs._dynamic_scoping),
meaning that a function's scope does not inherit from its caller's scope, but from the scope in
which the function was defined. For example, in the following code the `x` inside `foo` refers
to the `x` in the global scope of its module `Bar`:

```julia
```jldoctest moduleBar
julia> module Bar
x = 1
foo() = x
x = 1
foo() = x
end;
```

and not a `x` in the scope where `foo` is used:

```julia
julia> import Bar
```jldoctest moduleBar
julia> import .Bar
julia> x = -1;
Expand All @@ -53,36 +53,34 @@ Thus *lexical scope* means that the scope of variables can be inferred from the
*Each module introduces a new global scope*, separate from the global scope of all other modules;
there is no all-encompassing global scope. Modules can introduce variables of other modules into
their scope through the [using or import](@ref modules) statements or through qualified access using the
dot-notation, i.e. each module is a so-called *namespace*. Note that variable bindings can only
dot-notation, i.e. each module is a so-called *namespace*. Note that variable bindings can only
be changed within their global scope and not from an outside module.

```julia
```jldoctest
julia> module A
a = 1 # a global in A's scope
a = 1 # a global in A's scope
end;
julia> module B
module C
c = 2
c = 2
end
b = C.c # can access the namespace of a nested global scope
# through a qualified access
import A # makes module A available
d = A.a
b = C.c # can access the namespace of a nested global scope
# through a qualified access
import ..A # makes module A available
d = A.a
end;
julia> module D
b = a # errors as D's global scope is separate from A's
end;
ERROR: UndefVarError: a not defined
...
julia> module E
import A # make module A available
A.a = 2 # throws below error
import ..A # make module A available
A.a = 2 # throws below error
end;
ERROR: cannot assign variables in other modules
...
```

Note that the interactive prompt (aka REPL) is in the global scope of the module `Main`.
Expand All @@ -91,31 +89,30 @@ Note that the interactive prompt (aka REPL) is in the global scope of the module

A new local scope is introduced by most code-blocks, see above table for a complete list.
A local scope *usually* inherits all the variables from its parent scope, both for reading and
writing. There are two subtypes of local scopes, hard and soft, with slightly different rules
concerning what variables are inherited. Unlike global scopes, local scopes are not namespaces,
writing. There are two subtypes of local scopes, hard and soft, with slightly different rules
concerning what variables are inherited. Unlike global scopes, local scopes are not namespaces,
thus variables in an inner scope cannot be retrieved from the parent scope through some sort of
qualified access.

The following rules and examples pertain to both hard and soft local scopes. A newly introduced
variable in a local scope does not back-propagate to its parent scope. For example, here the
The following rules and examples pertain to both hard and soft local scopes. A newly introduced
variable in a local scope does not back-propagate to its parent scope. For example, here the
`z` is not introduced into the top-level scope:

```julia
```jldoctest
julia> for i = 1:10
z = i
end
julia> z
ERROR: UndefVarError: z not defined
...
```

(Note, in this and all following examples it is assumed that their top-level is a global scope
with a clean workspace, for instance a newly started REPL.)

Inside a local scope a variable can be forced to be a local variable using the `local` keyword:

```julia
```jldoctest
julia> x = 0;
julia> for i = 1:10
Expand All @@ -129,7 +126,7 @@ julia> x

Inside a local scope a new global variable can be defined using the keyword `global`:

```julia
```jldoctest
julia> for i = 1:10
global z
z = i
Expand All @@ -142,7 +139,7 @@ julia> z
The location of both the `local` and `global` keywords within the scope block is irrelevant.
The following is equivalent to the last example (although stylistically worse):

```julia
```jldoctest
julia> for i = 1:10
z = i
global z
Expand All @@ -152,27 +149,18 @@ julia> z
10
```

Multiple global or local definitions can be on one line and can also be paired with assignments:

```julia
julia> for i = 1:10
global x = i, y, z
local a = 4, b, c = 1
end
```

### Soft Local Scope

> In a soft local scope, all variables are inherited from its parent scope unless a variable is
> specifically marked with the keyword `local`.
Soft local scopes are introduced by for-loops, while-loops, comprehensions, try-catch-finally-blocks,
and let-blocks. There are some extra rules for [Let Blocks](@ref) and for [For Loops and Comprehensions](@ref).
and let-blocks. There are some extra rules for [Let Blocks](@ref) and for [For Loops and Comprehensions](@ref).

In the following example the `x` and `y` refer always to the same variables as the soft local
scope inherits both read and write variables:

```julia
```jldoctest
julia> x, y = 0, 1;
julia> for i = 1:10
Expand All @@ -183,7 +171,7 @@ julia> x
12
```

Within soft scopes, the *global* keyword is never necessary, although allowed. The only case
Within soft scopes, the *global* keyword is never necessary, although allowed. The only case
when it would change the semantics is (currently) a syntax error:

```julia
Expand All @@ -194,7 +182,6 @@ julia> let
end
end
ERROR: syntax: `global j`: j is local variable in the enclosing scope
...
```

### Hard Local Scope
Expand All @@ -209,11 +196,11 @@ and macro-definitions.
Thus global variables are only inherited for reading but not for writing:

```julia
```jldoctest
julia> x, y = 1, 2;
julia> function foo()
x = 2 # assignment introduces a new local
x = 2 # assignment introduces a new local
return x + y # y refers to the global
end;
Expand All @@ -226,7 +213,7 @@ julia> x

An explicit `global` is needed to assign to a global variable:

```julia
```jldoctest
julia> x = 1;
julia> function foobar()
Expand All @@ -242,13 +229,13 @@ julia> x
Note that *nested functions* can behave differently to functions defined in the global scope as
they can modify their parent scope's *local* variables:

```julia
```jldoctest
julia> x, y = 1, 2;
julia> function baz()
x = 2 # introduces a new local
function bar()
x = 10 # modifies the parent's x
x = 10 # modifies the parent's x
return x + y # y is global
end
return bar() + x # 12 + 10 (x is modified in call of bar())
Expand All @@ -262,10 +249,10 @@ julia> x, y
```

The distinction between inheriting global and local variables for assignment can lead to some
slight differences between functions defined in local vs. global scopes. Consider the modification
slight differences between functions defined in local vs. global scopes. Consider the modification
of the last example by moving `bar` to the global scope:

```julia
```jldoctest
julia> x, y = 1, 2;
julia> function bar()
Expand All @@ -292,14 +279,14 @@ keyword function arguments which are described in the [Function section](@ref ma
An assignment introducing a variable used inside a function, type or macro definition need not
come before its inner usage:

```julia
```jldoctest
julia> f = y -> y + a
(::#2) (generic function with 1 method)
(::#1) (generic function with 1 method)
julia> f(3)
ERROR: UndefVarError: a not defined
in (::##2#3)(::Int64) at ./none:1
...
Stacktrace:
[1] (::##1#2)(::Int64) at ./none:1
julia> a = 1
1
Expand All @@ -312,10 +299,10 @@ This behavior may seem slightly odd for a normal variable, but allows for named
are just normal variables holding function objects -- to be used before they are defined. This
allows functions to be defined in whatever order is intuitive and convenient, rather than forcing
bottom up ordering or requiring forward declarations, as long as they are defined by the time
they are actually called. As an example, here is an inefficient, mutually recursive way to test
they are actually called. As an example, here is an inefficient, mutually recursive way to test
if positive integers are even or odd:

```julia
```jldoctest
julia> even(n) = n == 0 ? true : odd(n-1);
julia> odd(n) = n == 0 ? false : even(n-1);
Expand All @@ -337,7 +324,7 @@ variables in their parent scope. Thus their default is to fully access all varia
parent scope.

Conversely, the code inside blocks which introduce a hard local scope (function, type, and macro
definitions) can be executed at any place in a program. Remotely changing the state of global
definitions) can be executed at any place in a program. Remotely changing the state of global
variables in other modules should be done with care and thus this is an opt-in feature requiring
the `global` keyword.

Expand Down Expand Up @@ -369,7 +356,7 @@ This difference is usually not important, and is only detectable in the case of
outlive their scope via closures. The `let` syntax accepts a comma-separated series of assignments
and variable names:

```julia
```jldoctest
julia> x, y, z = -1, -1, -1;
julia> let x = 1, z
Expand All @@ -378,15 +365,14 @@ julia> let x = 1, z
end
x: 1, y: -1
ERROR: UndefVarError: z not defined
...
```

The assignments are evaluated in order, with each right-hand side evaluated in the scope before
the new variable on the left-hand side has been introduced. Therefore it makes sense to write
something like `let x = x` since the two `x` variables are distinct and have separate storage.
Here is an example where the behavior of `let` is needed:

```julia
```jldoctest
julia> Fs = Array{Any}(2); i = 1;
julia> while i <= 2
Expand All @@ -405,7 +391,7 @@ Here we create and store two closures that return variable `i`. However, it is a
variable `i`, so the two closures behave identically. We can use `let` to create a new binding
for `i`:

```julia
```jldoctest
julia> Fs = Array{Any}(2); i = 1;
julia> while i <= 2
Expand Down Expand Up @@ -442,11 +428,11 @@ outer local `x`.
### For Loops and Comprehensions

`for` loops and [Comprehensions](@ref) have the following behavior: any new variables introduced
in their body scopes are freshly allocated for each loop iteration. This is in contrast to `while`
in their body scopes are freshly allocated for each loop iteration. This is in contrast to `while`
loops which reuse the variables for all iterations. Therefore these constructs are similar to
`while` loops with `let` blocks inside:

```julia
```jldoctest
julia> Fs = Array{Any}(2);
julia> for j = 1:2
Expand All @@ -462,7 +448,7 @@ julia> Fs[2]()

`for` loops will reuse existing variables for its iteration variable:

```julia
```jldoctest
julia> i = 0;
julia> for i = 1:3
Expand All @@ -474,7 +460,7 @@ julia> i

However, comprehensions do not do this, and always freshly allocate their iteration variables:

```julia
```jldoctest
julia> x = 0;
julia> [ x for x = 1:3 ];
Expand All @@ -488,7 +474,7 @@ julia> x
A common use of variables is giving names to specific, unchanging values. Such variables are only
assigned once. This intent can be conveyed to the compiler using the `const` keyword:

```julia
```jldoctest
julia> const e = 2.71828182845904523536;
julia> const pi = 3.14159265358979323846;
Expand Down

0 comments on commit 788827c

Please sign in to comment.