parsii.eval

Class Scope

java.lang.Object

parsii.eval.Scope

All Implemented Interfaces:

Serializable

public class Scope
extends Object
implements Serializable

Contains a mapping of names to variables.

Both the user as well as the Parser use a Scope to resolve a name into a Variable. In contrast to a simple Map, this approach provides two advantages: It's usually faster, as the variable only needs to be resolved once. Modifying it and especially reading it when evaluating an expression is as cheap as a simple field access. The second advantage is that scopes can be chained. So variables can be either shared by two expression or kept separate, if required.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Scope() Creates a new empty scope.

Method Summary

Modifier and Type	Method and Description
static Scope	create() Deprecated. use plain old java code like new Scope()
Variable	create(String name) Searches or creates a variable in this scope.
static Scope	createStrict() Deprecated. Use plain java like new Scope().withStrictLookup(true)
static Scope	createWithParent(Scope parent) Deprecated. Use plain java code like new Scope().withParent(parent)
Variable	find(String name) Searches for a Variable with the given name.
Set<String>	getLocalNames() Returns all names of variables known to this scope (ignoring those of the parent scope).
Collection<Variable>	getLocalVariables() Returns all variables known to this scope (ignoring those of the parent scope).
Set<String>	getNames() Returns all names of variables known to this scope or one of its parent scopes.
Variable	getVariable(String name) Searches for or creates a variable with the given name.
Collection<Variable>	getVariables() Returns all variables known to this scope or one of its parent scopes.
Variable	remove(String name) Removes the variable with the given name from this scope.
Scope	withDefaultValue(double newDefaultValue) Specifies a default value for auto created variables.
Scope	withParent(Scope parent) Specifies the parent scope for this scope.
Scope	withStrictLookup(boolean strictLookup) Determines if strict lookup should be used or not.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Scope

public Scope()

Creates a new empty scope.

The scope will not be completely empty, as Math.PI (pi) and Math.E (E) are always defined as constants.

If an not yet known variable is accessed, it will be created and initialized with 0.

Method Detail

create

@Deprecated
public static Scope create()

Deprecated. use plain old java code like new Scope()

Creates a new empty scope.

The scope will not be completely empty, as Math.PI (pi) and Math.E (E) are always defined as constants.

If an not yet known variable is accessed, it will be created and initialized with 0.

Returns:

a new scope and empty

createStrict

@Deprecated
public static Scope createStrict()

Deprecated. Use plain java like new Scope().withStrictLookup(true)

Creates a new empty scope which will not autocreate variables.

The scope will not be completely empty, as Math.PI (pi) and Math.E (E) are always defined as constants.

If an not yet known variable is accessed, a ParseException will be thrown.

Returns:

a new scope and empty

withDefaultValue

public Scope withDefaultValue(double newDefaultValue)

Specifies a default value for auto created variables.

Unless changes, variables are initialized with 0. One could change this i.e. to NaN to visualize the use of undeclared variables without creating an error.

Note that this will not change the value of variables which have been created before calling this method.

Parameters:

newDefaultValue - the new default value to use when creating yet unknown variables.

Returns:

the instance itself for fluent method calls

withStrictLookup

public Scope withStrictLookup(boolean strictLookup)

Determines if strict lookup should be used or not.

A scope with strict lookup will not create unknown variables upon their first access but rather throw an error.

By default, scopes are not strict and will automatically create variables when first reuqested.

Parameters:

strictLookup - true if the scope should be switched to strict lookup, false otherwise

Returns:

the instance itself for fluent method calls

withParent

public Scope withParent(Scope parent)

Specifies the parent scope for this scope.

If a scope cannot resolve a variable, it tries to resolve it using its parent scope. This permits to share a certain set of variables.

Parameters:

parent - the parent scope to use. If null, the common root scope is used which defines a bunch of constants (e and pi).

Returns:

the instance itself for fluent method calls

createWithParent

@Deprecated
public static Scope createWithParent(Scope parent)

Deprecated. Use plain java code like new Scope().withParent(parent)

Creates a new scope with the given parent.

If a variable is resolved, first the own scope is scanned. If no variable for the given name is found, the parent scope is scanned. If this yields a variable, it will be returned. Otherwise it will be defined in the local scope (not in the parent).

Parameters:

parent - the scope to use as lookup source for further variables

Returns:

a new scope with the given parent as super scope

find

public Variable find(String name)

Searches for a Variable with the given name.

If the variable does not exist null will be returned

Parameters:

name - the name of the variable to search

Returns:

the variable with the given name or null if no such variable was found

getVariable

public Variable getVariable(String name)

Searches for or creates a variable with the given name.

If no variable with the given name is found, a new variable is created in this scope

Parameters:

name - the variable to look for

Returns:

a variable with the given name

Throws:

IllegalArgumentException - if autocreateVariables is false and the given variable was not creted yet.

create

public Variable create(String name)

Searches or creates a variable in this scope.

Tries to find a variable with the given name in this scope. If no variable with the given name is found, the parent scope is not checked, but a new variable is created.

Parameters:

name - the variable to search or create

Returns:

a variable with the given name from the local scope

remove

public Variable remove(String name)

Removes the variable with the given name from this scope.

If will not remove the variable from a parent scope.

Parameters:

name - the name of the variable to remove

Returns:

the removed variable or null if no variable with the given name existed

getLocalNames

public Set<String> getLocalNames()

Returns all names of variables known to this scope (ignoring those of the parent scope).

Returns:

a set of all known variable names

getNames

public Set<String> getNames()

Returns all names of variables known to this scope or one of its parent scopes.

Returns:

a set of all known variable names

getLocalVariables

public Collection<Variable> getLocalVariables()

Returns all variables known to this scope (ignoring those of the parent scope).

Returns:

a collection of all known variables

getVariables

public Collection<Variable> getVariables()

Returns all variables known to this scope or one of its parent scopes.

Returns:

a collection of all known variables