CWParser

Python library for parsing Stellaris (and hopefully other Clausewitz) script

Important functions for initial configuration of this module: set_vanilla_path(path): tells the module where to find vanilla content set_workshop_path(path): tells the module where to find steam workshop content set_mod_docs_path(path): tells the module where to find your own content

***

This package contains 3 files:

cw_parser contains a range of functions and modules for parsing clausewitz-style mods and game code.

mod_data contains example code of how one might set up mods; it is not usable as-is since it relies on computer-specific details of which mods are downloaded and which are locally built.

cwp_stellaris contains stellaris-specific configuration for effect parsing.

***

<b>Central concepts</b>

This module represents stellaris code as a tree of CWList and CWElement objects, with CWList objects containing CWElements which in turn often contain CWList objects.

<b>CWElement objects</b>

The cw_parser.CWELement class is used to represent key-value pairs such as "cost = 5" or "effect = { kill_pop = yes }", and also to represent elements in arrays such as each tech in a "prerequisitea" block or trait in an "opposites" block. A CWElement has the following properties: name: The left-hand key; str (for key-value pairs) or None (For elements in arrays such as "prerequisite" and "opposites" blocks). value: the right-hand value; str, cw_parser.inlineMathsUnit, cw_parser.CWListValue, or cw_parser.metaScript. Should only be set using the setValue() method. comparitor: an array generally containing one or more of the characters '=', '<', or '>'. metadata: a dictionary for storing freeform data. filename: file this element was read from. overwrite_type: string representing overwrite type, e.g. 'LIOS' or 'FIOS'. mod: mod this element was read from.

<b>CWList objects</b>

The CWList class, a subclass of UserList, is used to represent the contents of files and folders. Its subclass CWListValue is used to represent the contents of {} blocks. CWList lists should never contain objects of types other than CWElement. The CWList.contents() method returns the contents of a CWList, if appropriate also looking in the expansions of any scripts.

<b>Mod objects</b>

The Mod class is used to represent mods. The special Mod object cw_parser.vanilla_mod_object is used to represent vanilla game contents.

For the purpose of full-file overwriting, mods are assumed to be loaded in the order in which they are created. The set_load_order function can be used to change this.

For the purpose of looking inside inline scripts, resolving global variables, and so on, the parser needs to know which mods to treat as loaded. This can be controlled using the Mod.is_base property, the Mod.parents property, and the Mod.activate() method.

At a given time, the module will assume that the following mods are active: - All mods where is_base=True (including cw_parser.vanilla_mod_object) - The current active mod, i.e. whichever mod most recently had its Mod.activate() method called. - All mods in the current active mod's Mod.parents list.

The Mod.read_folder() method reads the contents of a folder within a mod, returning a CWList object. It will also read from that mod's parents and from all mods where is_base is true if either: - the include_parents parameter is True - the include_parents parameter is not specified AND the mod's is_base value is True

The registered_mods dictionary is a dictionary containing all Mods where the 'key' parameter was specified on creation. cw_parser.vanilla_mod_object will be included with the key "base".

***

functions:

set_vanilla_path( str ): tells the module where to find the vanilla game

set_mod_docs_path( str ): tells the module where to find your homemade mods

set_workshop_path( str ): tells the modulewhere to find steam workshop mods

set_expand_inlines( bool ): sets whether to look inside inline scripts by default when iterating over CWList contents (default False)

set_replace_local_variables( bool ): sets whether to replace local variables by default when parsing strings (default True)

set_parser_commands( list[str] ): Sets a list of strings that identify commands for the parser by default. By default, this is ["CW_PARSER"], meaning that all file contents between "#CW_PARSER:skip" and "#CW_PARSER:/skip" will be ignored.

set_load_order( list[Mod] ): Changes the assumed load order. By default, mods are assumed to be loaded in the order the objects were created. The list given as input should be in REVERSE load order.

to_yesno( bool ): converts a boolean to a string "yes" or "no"

in_common( *args ): shorthand for os.path.join('common',*args)

escapeString( str ): escapes quotes and backslashes in a string

quote( str ): escapes quotes and backslashes in a string then wraps it in quotation marks

indent( str, count=1, initial_linebreak=False ): indents a string with tabs

numerify( str ): converts a string to an int or float if possible

valueString( object ): converts an object back to the corresponding string for use in stellaris script for objects from this module str() is equivalent, but this is useful if you might also receive a string containing spaces

match( string1, string2 ): checks that two strings are the same apart from case.

mod_doc_path(name): returns the path to one of your own mods; name is the folder name

resolveValue( value, vars=None ): attempts to solve inlineMathsBlocks and look up global variables to give a final value. e.g. resolveValue("@discovery_weight") returns "3" parameters: value( str or inlineMathsBlock ): object to resolve value of vars( Mod ): Mod to treat as active for the purpose of global variables lookup. If not specified, uses the current active mod.

stringToCW( string, filename=None, replace_local_variables=None, parser_commands=None, overwrite_type=None, mod=None, bracketClass=cw_parser.CWListValue ) -> CWList: parses a string into a CWList object.

parameters:
	string (str):
		String to parse
	filename (str):
		Filename to assign to these objects
	replace_local_variables (bool):
		If True, local @ variable assignments (@key = value) in the string will be used to replace subsequent local @ variable usages (key = @variable) as appropriate.
		A default value for this parameter can be set with the set_replace_local_variables(bool) function. Initially this will be True.
	parser_commands (list[str]):
		List of strings to identify commands for the parser within the text.
		A default value for this parameter can be set with the set_parser_commands(list) function. Initially this will be ["CW_PARSER"].
		This means the following commands will function:
			#CW_PARSER:skip (begin ignoring text)
			#CW_PARSER:/skip (stop ignoring text)
			#CW_PARSER:add_metadata:<key>:<value> (add metadata to the next object)
			#CW_PARSER:add_block_metadata:<key>:<value> (start adding metadata to objects)
			#CW_PARSER:/add_block_metadata (undoes the most recent add_block_metadata effect)
	overwrite_type (str):
		string representing overwrite type. If equalt to 'LIOS' or 'FIOS' this can be used by certain methods to figure out what overwrites what.
	mod (cw_parser.Mod):
		mod this data belongs to
	bracketClass (type):
		set to cw_parser.metaScript for metascripts when parsing scripted effects, scripted triggers, and script values.

fileToCW( path, filename=None, parent=None, replace_local_variables=None, parser_commands=None, overwrite_type="LIOS", mod=None, bracketClass=cw_parser.CWListValue ) -> CWList: Parses a file using stringToCW. If filename is not given, defaults to using that file's filename.

findEffectScopes( criteria, mods=cw_parser.registered_mods.values() ): Scans all effect blocks (except, currently, those in queue_actions blocks) and returns a list of (CWElement,scopesContext) tuples corresponding to effects. Note: this function requires game-specific configuration. Stellaris configuration can be set up by importing and running cwp_stellaris.configureCWP(). Note: currently this function is unable to see effects that are within "queue_actions" block

parameters: criteria (callable[CWElement to boolean]): Should take a CWElement and return a boolean. Effects will be included in the returned list if criteria(effect) return True. mods (iterator[cw_parser.Mod]): Provides the mods to scan. When the iterator returns a mod where is_base=True (for example, when cw_parser.registered_mods.values() returns the vanilla mod object), this function will also scan all mods where is_base=True.

***

public classes in cw_parser:

<b>inlineMathsStep( operator, value, negative )</b>

object representing a step in an inline maths block operator should be None (for first element of block), '+', '-', '*', '/', or '%' value should be a number, a string representing a global variable, or an inlineMathsBlock

<b>inlineMathsBlock()</b> UserList of inlineMathsSteps representing a bracket-enclosed inline maths subsection

<b>absValBlock()</b> Subclass of inlineMathsBlock representing a ||-enclosed inline maths subsection

<b>inlineMathsUnit()</b> Subclass of inlineLathsBlock representing a @[]-enclosed inline maths value.

<b>Mod( workshop_item=None, mod_path=None, parents=[], is_base=False, key=None, compat_var=None )</b>:

Class representing a mod (or vanilla). Mod load order is assumed to correspond to the order in which mods are created. This can be changed using the cw_parser.set_load_order function, which takes a list of mods and moves those mods to the end of the assumed load order. cw_parser.registered_mods is a dictionary to which mods can be automatically added on creation by assigning a key. The vanilla mod object is included in this dictionary with the key 'base'.

init parameters/properties: workshop_item (str): string (NOT int) containing this mod's steam workshop number. mod_path (str): path to th