Chapter ‍5 Variables and Naming

• private.
• this.
• global.
• protected.
• public.
• Qualified blocks
• declare

During evaluation, there are three different kinds of namespaces. Variables can be private, or they may refer to fields in the current this object, or they can be part of the global namespace. The namespace can be specified directly by including an explicit qualifier before the variable name. The three namespaces are separate; a variable can be bound in one or more simultaneously.

    # private namespace
    private.X = 1
    # current object
    this.X = 2
    # public, globally defined
    global.X = 3

5.1 private.

The private. qualifier is used to define variables that are private to the current file/scope. The values are not accessible outside the scope. Private variables are statically (lexically) scoped.

Unforunately, private variables have always been incorrectly implemented in every omake version. Read the section below on the issues. In version 0.10 the problems still exist, and will probably be tackled in 0.11.

    Obj. =
       private.X = 1

       print() =
          println(The value of X is: $X)

    # Prints:
    #    The private value of X is: 1
    Obj.print()

    # This is an error--X is private in Obj
    y = $(Obj.X)

In addition, private definitions do not affect the global value of a variable.

   # The public value of x is 1
   x = 1

   # This object uses a private value of x
   Obj. =
       private.x = 2

       print() =
          x = 3
          println(The private value of x is: $x)
          println(The public value of x is: $(public.x))
          f()

   # Prints:
   #    The private value of x is: 3
   #    The public value of x is: 1
   Obj.print()

Private variables have two additional properties.

1. Private variables are local to the file in which they are defined.
2. Private variables are not exported by the export directive, unless they are mentioned explicitly in the export directive.

          private. =
             FLAG = true
   
          section
             FLAG = false
             export
   
          # FLAG is still true
          section
             FLAG = false
             export FLAG
   
          # FLAG is now false
     

As mentioned above, there are issues with private variables. In particular, when a function closure is built, the current values are remembered with the closure, and any future updates are not seen. For example:

    private.X = foo
    f() =
        println($"The value of X is $(X)")
    f()
    X = bar
    f()

This prints foo twice! As this is probably not what you want, the recommendation is:

• Use private variables only within functions, and do not expect that updates work across function boundaries.
• Do not export private variables at the end of a function.
• If you want to pass an anonymous function around, and want to export some private variable, consider to use the => notation (see Section ‍4.5.1).

These issues will likely be fixed soon.

5.2 this.

The this. qualifier is used to define fields that are local to an object. Object variables are dynamically scoped.

    X = 1
    f() =
       println(The public value of X is: $(X))

    # Prints:
    #    The public value of X is: 2
    section
       X = 2
       f()

    # X is a protected field in the object
    Obj. =
       this.X = 3

       print() =
          println(The value of this.X is: $(X))
          f()

    # Prints:
    #    The value of this.X is: 3
    #    The public value of X is: 1
    Obj.print()

    # This is legal, it defines Y as 3
    Y = $(Obj.X)

In general, it is a good idea to define object variables as protected. The resulting code is more modular because variables in your object will not produce unexpected clashes with variables defined in other parts of the project.

5.3 global.

The global. qualifier is used to specify global dynamically-scoped variables. In the following example, the global. definition specifies that the binding X = 4 is to be dynamically scoped. Global variables are not defined as fields of an object.

    X = 1
    f() =
       println(The global value of X is: $(X))

    # Prints:
    #    The global value of X is: 2
    section
       X = 2
       f()

    Obj. =
       this.X = 3

       print() =
          println(The protected value of X is: $(X))
          global.X = 4
          f()

    # Prints:
    #    The protected value of X is: 3
    #    The global value of X is: 4
    Obj.print()

5.4 protected.

In OMake 0.9.8, protected is a synonym for this.

    osh>protected.x = 1
    - : "1" : Sequence
    osh>value $(this.x)
    - : "1" : Sequence

In 0.9.9, this will change, so that the qualifier protected means (in 0.9.9) that a variable is local to the current object or file, and may not be accessed outside it.

5.5 public.

In OMake 0.9.8, public is a synonym for global.

    osh>public.x = 1
    - : "1" : Sequence
    osh>value $(global.x)
    - : "1" : Sequence

In 0.9.9, this will change, so that the qualifier public means (in 0.9.9) that a variable is to be accessible from outside the current file or object.

5.6 Qualified blocks

If several qualified variables are defined simultaneously, a block form of qualifier can be defined. The syntax is similar to an object definition, where the name of the object is the qualifier itself. For example, the following program defines two private variables X and Y.

    private. =
        X = 1
        Y = 2

The qualifier specifies a default namespace for new definitions in the block. The contents of the block is otherwise general.

    private. =
        X = 1
        Y = 2
        public.Z = $(add $X, $Y)
        # Prints "The value of Z is 3"
        echo The value of Z is $Z

Stylistically, it is usually better to avoid large qualified blocks because the qualifier status can be easy to forget. For example, consider the following fragment.

    private. =
        # Large code sequence
        ...
        # build foo.o with -g option (ERROR)
        CFLAGS = -g
        foo.o:

In this case, the programmer probably forgot that the definition of the variable CFLAGS is in the private block, so a fresh variable private.CFLAGS is being defined, not the global one. The target foo.o does not use this definition of CFLAGS.

5.7 declare

When a variable name is unqualified, its namespace is determined by the most recent definition or declaration that is in scope for that variable. We have already seen this in the examples, where a variable definition is qualified, but the subsequent uses are not qualified explicitly. In the following example, the first occurrence of $X refers to the private definition, because that is the most recent. The public definition of X is still 0, but the variable must be qualified explicitly in order to access the public value.

    public.X = 0
    private.X = 1

    public.print() =
        println(The value of private.X is: $X)
        println(The value of public.X is: $(public.X))

Sometimes it can be useful to declare a variable without defining it. For example, we might have a function that uses a variable X that is to be defined later in the program. The declare directive can be used for this.

    declare public.X

    public.print() =
        println(The value of X is $X)

    # Prints "The value of X is 2"
    X = 2
    print()

Finally, what about variables that are used but not explicitly qualified? In this case, the following rules are used.

• If the variable is a function parameter, it is private.
• If the variable is defined in an object, it is qualified with this..
• Otherwise, the variable is public.