Editing User:Button/BAMM

== About ==

=== Features ===

=== Planned Features ===

== Usage Instructions ==

=== Download ===

You can [https://github.com/BoomButton/DF-BAMM download the script] from GitHub.

=== Python 3 ===

=== Configuration ===

== Button's Workspace ==

Sometimes I'm on a computer I can't put a git client on.

# Modders' guide to BAMM! graphics references
# Place your conversions in a file named bamm_gfx_<identifier here>.txt . The file should be encoded in codepage 437, the same as the Dwarf Fortress raws.

# Start by defining names for your target graphics elements. 
# These names must always start with @.
# So if you want to reference the background color being used for the Lion creature token, you can do that with this definition:
# CREATURE:LION|COLOR::@lionbgcolor
# or
# CREATURE:LION|COLOR::@lionbgcolor:
# If you want to reference the *whole* color of the lion tile, which is a 3-argument value, you can add a number after the @, like this:
# CREATURE:LION|COLOR:@3lionfullcolor
# Or you can declare references for each argument of the lion color individually:
# CREATURE:LION|COLOR:@lionfgcolor:@lionbgcolor:@lionbrightness

# The name is case-sensitive and can contain any character in the alphabet. Numbers are not allowed except immediately after the @. Special characters, including underscores, are not allowed.

# You can also create generic all-graphics-belonging-to-this-object referents this way:
# CREATURE:LION|@allLionTags

# BE AWARE: trying to define non-graphics or partially non-graphic referents won't work. Referent declarations which include non-graphic information will simply be ignored.

# OK, now that we have our referents, it's time to use them to modify raws.

# creature_modded.txt
# [CREATURE:MODDED_LION]
# @allLionTags

# This sets all of the modded lion's graphics equal to the lion's graphics, in any graphics set.
# However, this "copy all" functionality couldn't be used to set properties belonging to a non-creature object:

# [INORGANIC:LIONSTONE]	This won't work
# @allLionTags			This won't work

# In order to make lionstone the color of a lion, you'll need to reference the colors instead:
# [INORGANIC:LIONSTONE]
# [DISPLAY_COLOR:@3lionfullcolor]

# NB. References are always made to graphics as declared in the graphics source raws. If you declare a lion to use a deer's graphics, and a deer to use a lion's graphics, they'll swap, not have the same graphics.

# Eventually I intend to expand this to include the ability to apply these changes based on the properties of entries, but right now, this should be enough.

# TODO docstring		
def handle_graphics_references(graphics_root,def_file):
	# Runs after the graphics source has been pulled in
	# Modifies same
	global graphics_referents
	if graphics_refs is None:
		graphics_refs = []	# This is meant to be a dict, check syntax
	definitions_over_yet = False
	for line in def_file:
		actline = line.split('#')[0].strip()
		if len(actline) == 0:
			continue
		elif actline == defs_over	# TODO declare this as a constant
			definitions_over_yet = True
		elif not definitions_over_yet:
			# load referent definition
			# If the referent name already exists in graphics_refs, write an error to the log and continue to the next line.
			# Otherwise, match it against a template
			# Then match it against the GRAPHICS NODES that meet that template
				# Not the bound node or the target node. 
			# (TODO make each template node hold lists of objects that refer to it, by function.)
			# If a partial definition matches more than one object, keep track of all of them so they can be narrowed down later
			# If a full definition matches more than one object, write a warning to the logfile and choose one arbitrarily to go with.
			# If a full definition matches no graphics object, write a warning to the log and try it on target objects. 
				# If a full definition matches neither graphics nor target, write an error to the log.
			# Put the mapping of referent name to an object storing the reference info into graphics_refs
		else:
			# Get a collection of all the targets that meet the reference
@@ Line 19: / Line 19: @@
 Sometimes I'm on a computer I can't put a git client on.
-<pre># Modders' guide to BAMM! graphics references
+# Modders' guide to BAMM! graphics references
 # Place your conversions in a file named bamm_gfx_<identifier here>.txt . The file should be encoded in codepage 437, the same as the Dwarf Fortress raws.
@@ Line 88: / Line 88: @@
 		else:
 			# Get a collection of all the targets that meet the reference
-</pre>
-<pre>class TemplateNode(TreeNode):
-"""A TreeNode tailored for holding graphics templates.
-TemplateNodes store the patterns which define what tags are graphics tags, and which of their tokens are immutable, identifying, graphical, or irrelevant. Each TemplateNode represents the template for a single type of graphics tag.
-Members:
-* _tag is the template string. It is a series of tokens separated by colons. Each token is one of the following:
-    * LITERAL. This is a string, usually in all caps, which must be present in this exact form for a tag to match this template. The first token in a template is always a literal. Enums (e.g. the PLANT_GROWTH timing values of ALL and NONE) may simulated by splitting a template into multiple templates, one for each enum, with the enum in question present as a literal.
-	* VARIABLE. This is a single character, '?' '$' or '&' (quotes not present in _tag).
-		* '?' indicates that this is a graphics token. When matching a tag to a template, this can match any value. When merging occurs, this token's value will come from the graphics source.
-		* '&' indicates that this is an info token. When matching a tag to a template, this can match any value. When merging occurs, this token's value will come from the raw source.
-		* '$' indicates that this is an identifier token. When matching a tag to a template, this can match any value; but for two tags to match each other, they must share the same values for all identifier tokens in their template.
-	* VARIABLE RANGE. This is a variable character, followed by a range in parentheses, e.g. ?(0,3). This means that the tag can contain 0-3 (inclusive) tokens in this position, all of which hold graphical information. The second value is optional - if omitted, it means there is no upper bound on how many tokens can be in this series.
-For examples, please see graphics_templates.config . The string between each pipe ( | ) is a valid TemplateNode._tag .
-* _children is a dict containing the TemplateNodes representing the types of tags which are allowed to be children of the type of tag represented by this TemplateNode. The keys are the full _tags of the child TemplateNodes.
-* _childref is the same as _children, but indexed by the first token (the "value") of the child's _tag, instead of the full _tag. For convenience/performance only.
-* _parent is the TemplateNode representing the type of tag that the type of tag this TemplateNode represents can be a child of.
-* _is_graphics_tag is a boolean that lets us know if this tag is a graphics tag, as opposed to a template included because it can have graphics children. This is necessary because some graphics tags are composed of only a single literal token.
-"""
-    # string does not contain the character '|'.
-    def __init__(self, parent, string=""):
-	""" Initializes a TemplateNode
-	Parameters:
-	* parent is the parent TemplateNode of this node, or None. If it is None, this TemplateNode will replace the current global template_tree.
-	* string is the template-formatted string which will be this TemplateNode's _tag.
-	After creating itself, if the parent isn't None, it adds itself to its parent.
-	"""
-        TreeNode.__init__(self, parent)
-        self._is_graphics_tag = False
-        self._childref = {}
-        self._tag = None
-        global template_tree
-        if parent is None:
-            self._parent = None
-            template_tree = self
-        else:
-            if template_tree is None:
-                self._parent = TemplateNode(None, "")
-            else:
-                self._parent = parent
-            self._tag = string
-            parent.add_child(self)
-    def is_standalone_tag(self):
-	""" Returns True if this is a tag without any non-graphical information. """
-        return ('$' not in self._tag
-                ) and '&' not in self._tag and self._is_graphics_tag
-    def add_child(self, node):
-	""" Adds TemplateNode node as a child of this TemplateNode.
-	If a child with node's ._tag already exists, node will NOT be added.
-	Parameters:
-	* node is an existing TemplateNode.
-	Returns:
-	* The child now living at this TemplateNode._children[node._tag]. This may be the parameter
-	node, or it may be a preexisting TemplateNode with the same ._tag as node._tag .
-	"""
-        if node._tag in self._children.keys():
-            return self._children[node._tag]
-        else:
-            self._children[node._tag] = node
-            first_token = node._tag.split(':')[0]
-            if first_token not in self._childref.keys():
-                self._childref[first_token] = []
-            self._childref[first_token].append(node)
-            return node
-    def get_child(self, tag):
-		""" Returns the child node matching tag.
-		"Matching" in this case can mean two different things:
-		* If there is a child of this node indexed as tag, that is a match and that node will be returned.
-		* If not, we compare tag to the child templates of this template, using template-to-tag comparison logic as defined in TemplateNode.get_template_match.
-		** If more than one child matches tag on this second criterion, the best match is chosen by TemplateNode._get_best_match.
-		Parameters:
-		* tag is a a tag or template tag, which we want to compare to the children of this TemplateNode.
-		Returns:
-		* The best-matching TemplateNode which is a child of self, or None if no matching children were found.
-		"""
-        if tag in self._children.keys():
-            return self._children[tag]
-        else:
-            return_possibilities = []
-            first_token = tag.split(':')[0]
-            if first_token in self._childref:
-                for child in self._childref[first_token]:
-                    return_node = child.get_template_match(tag)
-                    if return_node is not None:
-                        return_possibilities.append((child, return_node))
-                if len(return_possibilities) == 1:
-                    return return_possibilities[0][0]
-                elif len(return_possibilities) == 0:
-                    return None
-                else:
-                    # TODO error handling
-                    userlog.debug("Found more than one matching child. \
-                                  Matching children are:")
-                    for poss in return_possibilities:
-                        userlog.debug(poss[1])
-                    possible_tags = [a[1] for a in return_possibilities]
-                    winner = TemplateNode._get_best_match(possible_tags)
-                    return return_possibilities[possible_tags.index(winner)][0]
-            else:
-                return None
-    # This tells if a single tag matches a single tag; that is, it assumes
-    # we've got one element of the |-separated list
-    def get_template_match(self, tag_to_compare):
-		""" Returns an expanded configuration of this template that describes/matches the given tag.
-		Parameters:
-		* tag_to_compare can be a tag, a template, or a partially-templatized tag. If it is a template, it must be in expanded configuration.
-		Returns:
-		* The fully-expanded configuration of self._tag which matches tag_to_compare, as a list of strings, each a token. If there are no matches, returns None. If there are multiple possible configurations, the configuration to return is chosen by _get_best_match.
-		"""
-        if self._tag is None:
-            return None
-        template_token_bag = []
-        template_token_bag.append(self._tag.split(':'))
-        candidate_tokens = tag_to_compare.split(':')
-        ii = 0
-        while (len(template_token_bag) > 0 and
-               (ii < len(candidate_tokens) or
-                ii < len(template_token_bag[0]))):
-            good_to_go = False
-            for var in template_token_bag:
-                if ii < len(candidate_tokens) and ii >= len(var):
-                    template_token_bag.remove(var)
-                elif ii >= len(var) and len(var) == len(candidate_tokens):
-                    good_to_go = True
-                elif (ii >= len(candidate_tokens) and
-                      (ii >= len(var) or
-                       (ii < len(var) and '(0,' not in var[ii]))):
-                    template_token_bag.remove(var)
-                elif ('&' == var[ii] or '?' == var[ii] or '$' == var[ii] or
-                      (ii < len(candidate_tokens) and
-                       var[ii] == candidate_tokens[ii])):
-                    # This case is an auto-pass
-                    good_to_go = True
-                else:
-                    if '&' in var[ii] or '?' in var[ii] or '$' in var[ii]:
-                        varii_type = var[ii][0]
-                        varii_range = var[ii][2:var[ii].index(')')].split(',')
-                        # If len(varii_range) == 1 then we have a range of
-                        # format (x,), indicating any number of :'s
-                        if len(varii_range[1]) == 0:
-                            varii_range[1] = len(candidate_tokens)-len(var) + 1
-                        # For every possible length (the +1 is because range is
-                        # exclusive-end and my notation is inclusive-end)
-                        for jj in range(int(varii_range[0]),
-                                        int(varii_range[1])+1):
-                            # Make a copy of var
-                            new_var = var[:]
-                            # Remove the range item
-                            del new_var[ii]
-                            # Replace it with (one of the possible lengths)
-                            # times the multiplied symbol
-                            # If jj is 0 the range item is just removed
-                            for kk in range(0, jj):
-                                new_var.insert(ii, varii_type)
-                            # Place the new variant in the token bag for
-                            # evaluation
-                            template_token_bag.append(new_var)
-                    # No counting, there is a new template_token_bag[ii]
-                    template_token_bag.remove(var)
-            if good_to_go:
-                ii += 1
-        for tag in template_token_bag:
-            if len(tag) != len(candidate_tokens):
-                template_token_bag.remove(tag)  # This isn't working properly?
-        if len(template_token_bag) == 0:
-            return None
-        elif len(template_token_bag) == 1:
-            return template_token_bag[0]
-        else:
-            highest_priority = TemplateNode._get_best_match(template_token_bag)
-            userlog.debug("More than one template matched.\nTag: %s Matches:",
-                          tag_to_compare)
-            for template in template_token_bag:
-                userlog.debug("\t%s", template)
-            userlog.debug("The highest-priority match is %s", highest_priority)
-            # Technically this does in fact have a matching template
-            return highest_priority
-    @staticmethod
-    def _get_best_match(template_tokens_bag):
-		""" Chooses between different templates which both have been found to match a tag.
-		It chooses based on the number of tokens which are NOT wildcards. The principle is that a template which matches a tag with fewer wildcards is probably a better match, because matches on wildcards are cheap.
-		Parameters:
-		* template_tokens_bag is a list of fully-expanded templates, with each template configured as a list of tokens.
-		Returns:
-		* the list in template_tokens_bag with the least wildcards. If there is a tie on the number of wildcards, it returns the earliest one in the list.
-		"""
-        if not template_tokens_bag:        # empty bag returns false
-            return None
-        elif len(template_tokens_bag) == 1:
-            return template_tokens_bag[0]
-        else:
-            best_currently = template_tokens_bag[0]
-            best_tokens = 0
-            for tag in template_tokens_bag:
-                challenger_tokens = 0
-                for token in tag:
-                    if token != '?' and token != '&' and token != '$':
-                        challenger_tokens = challenger_tokens + 1
-                if challenger_tokens > best_tokens:
-                    best_currently = tag
-                    best_tokens = challenger_tokens
-            return best_currently
-    def how_many_generations(self):
-	""" Returns how deep into the template tree this node lives."""
-		# TODO consider moving this into TreeNode
-        temp_node = self
-        count = -1
-        global template_tree
-        while temp_node != template_tree:
-            temp_node = temp_node._parent
-            count = count + 1
-        return count</pre>