Struct ScopeContext 

pub struct ScopeContext {

    scope_stack: Vec<ScopeEntry>,
    root: ScopeEntry,
    scope_names: TigerHashMap<&'static str, (usize, Temporary)>,
    scope_list_names: TigerHashMap<&'static str, (usize, Temporary)>,
    local_names: TigerHashMap<&'static str, usize>,
    local_list_names: TigerHashMap<&'static str, usize>,
    named: Vec<ScopeEntry>,
    is_input: Vec<Option<Token>>,
    is_builder: bool,
    is_unrooted: bool,
    prev_levels: usize,
    strict_scopes: bool,
    no_warn: bool,
    source: Token,
    traceback: Vec<ActionOrEvent>,
}

The ScopeContext represents what we know about the scopes leading to the Block currently being validated.

Fields

scope_stack: Vec<ScopeEntry>

scope_stack contains all known previous scopes, with this at the end. The oldest scope is at index 0. INVARIANT: it is never empty, because there is always this.

Normally, this starts as a ScopeEntry::Rootref, but there are cases where the relationship to root is not known.

root: ScopeEntry

root is always a ScopeEntry::Scope

scope_names: TigerHashMap<&'static str, (usize, Temporary)>

Names of named scopes; the values are indices into the named vector.

scope_list_names: TigerHashMap<&'static str, (usize, Temporary)>

Names of named lists; the values are indices into the named vector.

local_names: TigerHashMap<&'static str, usize>

Names of local variables; the values are indices into the named vector.

local_list_names: TigerHashMap<&'static str, usize>

Names of local variable lists; the values are indices into the named vector.

named: Vec<ScopeEntry>

Named scope values are ScopeEntry::Scope or ScopeEntry::Named or ScopeEntry::Rootref. Invariant: there are no cycles in the array via ScopeEntry::Named entries. Invariant: entries are only added, never removed or rearranged. This is because the indices are used by ScopeEntry::Named values throughout this ScopeContext.

is_input: Vec<Option<Token>>

Same indices as named, is a token iff the named scope is expected to be set on entry to the current scope context. Invariant: named and is_input are the same length.

is_builder: bool

Is this scope level a level in progress? is_builder is used when evaluating scope chains like root.liege.primary_title. It affects the handling of prev, because the builder scope is not a real scope level yet.

is_unrooted: bool

Was this ScopeContext created as an unrooted context? Unrooted means we do not know whether this and root are the same at the start.

prev_levels: usize

How many dummy prev levels were added to this scope context? They affect how the scope context is cleaned up. Usually 0 or 1, but imperator and hoi4 can have multiple prev levels.

strict_scopes: bool

Is this scope context one where all the named scopes are (or should be) known in advance? If strict_scopes is false, then the ScopeContext will assume any name might be a valid scope name that we just don’t know about yet.

no_warn: bool

A special flag for scope contexts that are known to be wrong. It’s used for the scope_override config file feature. If no_warn is set then this ScopeContext will not emit any reports.

source: Token

A token indicating where this context was created and its named scopes were initialized.

traceback: Vec<ActionOrEvent>

A history of the actions and events that were triggered on the way from source to the current context.

Implementations

impl ScopeContext

pub fn new<T: Into<Token>>(root: Scopes, token: T) -> Self

Make a new ScopeContext, with this and root the same, and root of the given scope types. token is used when reporting errors about the use of root.

pub fn new_unrooted<T: Into<Token>>(this: Scopes, token: T) -> Self

Make a new ScopeContext, with this and root unconnected, and this of the given scope types. token is used when reporting errors about the use of this, root, or prev.

This function is useful for the scope contexts created for scripted effects, scripted triggers, and script values. In those, it’s not known what the caller’s root is.

pub fn set_strict_scopes(&mut self, strict: bool)

Declare whether all the named scopes in this scope context are known. Default is true.

Set this to false in for example events, which start with the scopes defined by their triggering context.

Having strict scopes set to true makes the ScopeContext emit errors when encountering unknown scope names.

pub fn is_strict(&self) -> bool

Return whether this ScopeContext has strict scopes set to true. See Self::set_strict_scopes.

pub fn set_no_warn(&mut self, no_warn: bool)

Set whether this ScopeContext should emit reports at all. no_warn defaults to false.

It’s used for scope contexts that are known to be wrong, related to the scope_override config file feature.

pub fn set_source<T: Into<Token>>(&mut self, source: T)

Change this context’s source value to something more appropriate than the default (which is the token passed to new).

fn root_for(&self, trace: ActionOrEvent, data: &Everything) -> Option<Self>

Helper function for root_for_event and root_for_action.

pub fn root_for_event<T: Into<Token>>( &self, event_id: T, data: &Everything, ) -> Option<Self>

Create a ScopeContext to use for a triggered event, if validating the event with this scope context is useful.

pub fn root_for_action<T: Into<Token>>( &self, action: T, data: &Everything, ) -> Option<Self>

Create a ScopeContext to use for a triggered action, if validating the action with this scope context is useful.

pub fn wipe_temporaries(&mut self)

pub fn change_root<T: Into<Token>>(&mut self, root: Scopes, token: T)

Change the scope type and related token of root for this ScopeContext.

This function is mainly used in the setup of a ScopeContext before using it. It’s a bit of a hack and shouldn’t be used. TODO: get rid of this.

pub fn define_name<T: Into<Token>>( &mut self, name: &'static str, scopes: Scopes, token: T, )

Declare that this ScopeContext contains a named scope of the given name and type, supplied by the game engine.

The associated token will be used in error reports related to this named scope.

pub fn define_name_token<T: Into<Token>>( &mut self, name: &'static str, scopes: Scopes, token: T, temp: Temporary, )

Declare that this ScopeContext contains a named scope of the given name and type, not supplied by the game engine but deduced from script.

The associated token will be used in error reports related to this named scope. The token should reflect why we think the named scope has the scope type it has.

pub fn is_name_defined( &mut self, name: &str, data: &Everything, ) -> Option<Scopes>

Look up a named scope and return its scope types if it’s known.

Callers should probably check Self::is_strict() as well.

pub fn exists_scope<T: Into<Token>>(&mut self, name: &'static str, token: T)

This is called when the script does exists = scope:name.

It records name as “known”, but with no scope type information, and records that the caller is expected to provide this scope.

The ScopeContext is not smart enough to track optionally existing scopes. It assumes that if you do exists on a scope, then from that point on it exists. Improving this would be a big project.

pub fn exists_local<T: Into<Token>>(&mut self, name: &'static str, token: T)

This is called when the script does exists = local_var:name or has_local_variable = name.

It records name as “known”, but with no scope type information, and records that the caller is expected to provide this local variable.

pub fn exists_local_list<T: Into<Token>>( &mut self, name: &'static str, token: T, )

This is called when the script does has_local_variable_list = name.

It records name as “known”, but with no scope type information, and records that the caller is expected to provide this local variable list.

pub fn define_list<T: Into<Token>>( &mut self, name: &'static str, scopes: Scopes, token: T, )

Declare that this ScopeContext contains a list of the given name and type, supplied by the game engine.

The associated token will be used in error reports related to this list.

Lists and named scopes exist in different namespaces, but under the hood ScopeContext treats them the same. This means that lists are expected to contain items of a single scope type, which sometimes leads to false positives.

pub fn save_current_scope(&mut self, name: &'static str, temp: Temporary)

This is like Self::define_name(), but scope:name is declared equal to the current this.

pub fn set_local_variable(&mut self, name: &Token, scope: Scopes)

Sets a local variable to the provided scope type

pub fn define_or_expect_list_this( &mut self, name: &Token, data: &Everything, temp: Temporary, )

If list name exists, narrow its scope type down to this and narrow the this scope types down to the existing list. Otherwise, define it as having the same scope type as this.

pub fn define_or_expect_list( &mut self, name: &Token, scope: Scopes, data: &Everything, temp: Temporary, )

If list name exists, narrow its scope type down to the given scopes. Otherwise, define it as having the given scopes.

pub fn define_or_expect_local_list( &mut self, name: &Token, scope: Scopes, data: &Everything, )

If local variable list name exists, narrow its scope type down to the given scopes. Otherwise, define it as having the given scopes.

pub fn expect_list(&mut self, name: &Token, data: &Everything)

Expect list name to be known and (with strict scopes) warn if it isn’t. Narrow the type of this down to the list’s type.

pub fn expect_local_list(&mut self, name: &Token, data: &Everything)

Expect local variable list name to be known and (with strict scopes) warn if it isn’t. Narrow the type of this down to the list’s type.

pub fn expect_local(&mut self, name: &Token, scope: Scopes, data: &Everything)

Expect local variable name to be known and (with strict scopes) warn if it isn’t.

pub fn open_scope(&mut self, scopes: Scopes, token: Token)

Open a new scope level of scopes scope type. Record token as the reason for this type.

This is mostly used by iterators. prev will refer to the previous scope level.

pub fn open_builder(&mut self)

Open a new, temporary scope level. Initially it will have its this the same as the previous level’s this.

The purpose is to handle scope chains like root.liege.primary_title. Call the replace_ functions to update the value of this, and at the end either confirm the new scope level with Self::finalize_builder() or discard it with Self::close().

pub fn stash_builder(&mut self) -> StashedBuilder

pub fn unstash_builder(&mut self, stash: StashedBuilder)

pub fn finalize_builder(&mut self)

Declare that the temporary scope level opened with Self::open_builder() is a real scope level.

pub fn close(&mut self)

Exit a scope level and return to the previous level.

pub fn signature(&self, data: &Everything) -> Signature

Return an object that captures the essentials of this ScopeContext, to be used for hashing.

pub fn replace(&mut self, scopes: Scopes, token: Token)

Replace the this in a temporary scope level with the given scopes type and record token as the reason for this type.

This is used when a scope chain starts with something absolute like faith:catholic.

pub fn replace_root(&mut self)

Replace the this in a temporary scope level with a reference to root.

pub fn replace_prev(&mut self)

Replace the this in a temporary scope level with a reference to the previous scope level.

pub fn replace_this(&mut self)

Replace the this in a temporary scope level with a reference to the real level below it.

This is usually a no-op, used when scope chains start with this. If a scope chain has this in the middle of the chain (which itself will trigger a warning) then it resets the temporary scope level to the way it started.

pub fn replace_named_scope(&mut self, name: &'static str, token: &Token)

Replace the this in a temporary scope level with a reference to the named scope name.

This is used when a scope chain starts with scope:name. The token is expected to be the scope:name token.

pub fn replace_local_variable(&mut self, name: &'static str, token: &Token)

Replace the this in a temporary scope level with a reference to the local variable name.

This is used when a scope chain starts with local_var:name. The token is expected to be the local_var:name token.

pub fn replace_global_variable(&mut self, name: &'static str, token: &Token)

Replace the this in a temporary scope level with a reference to the global variable name.

This is used when a scope chain starts with global_var:name. The token is expected to be the global_var:name token.

pub fn replace_variable(&mut self, name: &'static str, token: &Token)

Replace the this in a temporary scope level with a reference to the variable name.

This is used when a scope chain starts with var:name. The token is expected to be the var:name token.

pub fn replace_list_entry(&mut self, name: &Token)

Replace the this in a temporary scope level with a reference to the scope type of the list name.

pub fn replace_local_list_entry(&mut self, name: &Token)

Replace the this in a temporary scope level with a reference to the scope type of the local variable list name.

pub fn replace_global_list_entry(&mut self, name: &Token)

Replace the this in a temporary scope level with a reference to the scope type of the global variable list name.

pub fn replace_variable_list_entry(&mut self, name: &Token)

Replace the this in a temporary scope level with a reference to the scope type of the variable list name.

pub fn can_be(&self, scopes: Scopes, data: &Everything) -> bool

Return true iff it’s possible that this is the same type as one of the scopes types.

pub fn scopes(&self, data: &Everything) -> Scopes

Return the possible scope types of this scope level.

pub fn local_variable_scopes(&self, name: &str, data: &Everything) -> Scopes

Return the possible scope types of this local variable.

pub fn local_list_scopes(&self, name: &str, data: &Everything) -> Scopes

Return the possible scope types of this local variable list.

pub fn get_multiplier_context(&self, key: &Token) -> Self

fn resolve_root(&self) -> (Scopes, &Reason)

Return the possible scope types of root, and the reason why we think it has those types

pub fn scopes_reason(&self, data: &Everything) -> (Scopes, &Reason)

Return the possible scope types for the current scope layer, together with the reason why we think that.

pub fn log_traceback(&self, builder: ReportBuilderFull) -> ReportBuilderFull

Add messages to a report that describe where this ScopeContext came from.

pub fn expect(&mut self, scopes: Scopes, reason: &Reason, data: &Everything)

Record that the this in the current scope level is one of the scope types scopes, and if this is new information, record token as the reason we think that. Emit an error if what we already know about this is incompatible with scopes.

fn expect3( &mut self, scopes: Scopes, reason: &Reason, key: &Token, back: usize, report: &str, data: &Everything, )

Like Self::expect(), but the error emitted will be located at token key.

This function is used when the expectation of scope compatibility comes from key, for example when matching up a caller’s scope context with a scripted effect’s scope context.

pub fn expect_compatibility( &mut self, other: &ScopeContext, key: &Token, data: &Everything, )

Compare this scope context to other, with key as the token that identifies other.

This function examines the root, this, prev, and named scopes of the two scope contexts and warns about any contradictions it finds.

It expects self to be the caller and other to be the callee.

pub(crate) fn destroy(self)

Safely destroy a ScopeContext without fully unwinding its stack. This is useful when a ScopeContext needed to be cloned for some reason.

Trait Implementations

impl Clone for ScopeContext

fn clone(&self) -> ScopeContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ScopeContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for ScopeContext

fn drop(&mut self)

This drop function checks that every opened scope level was also closed.