def bauxitetoaluminum(df, aluminum_value=0.75, entities=default_entities, add_to_file=default_file):
    # Affect value of aluminum
    pydwarf.log.debug('Multiplying value of aluminum by %f.' % aluminum_value)
    try:
        aluminum = df.getobj('INORGANIC:ALUMINUM')
        if aluminum is None: return pydwarf.failure('Couldn\'t find aluminum token to affect its value.')
        matvaluetoken = aluminum.getprop('MATERIAL_VALUE')
        matvaluetoken.args[0] = int( float(matvaluetoken.args[0]) * aluminum_value )
    except:
        pydwarf.log.exception('Failed to affect value of aluminum.')
        return pydwarf.failure()
        
    # Add the reaction
    return pydwarf.urist.getfn('pineapple.utils.addobject')(
        df,
        type = 'REACTION',
        id = 'SMELT_BAUXITE_ALUMINUM_PINEAPPLE',
        tokens = '''
            [NAME:smelt aluminum from bauxite]
            [SMELTER]
            [REAGENT:1:STONE:NO_SUBTYPE:STONE:BAUXITE]
            [REAGENT:1:STONE:NO_SUBTYPE:STONE:CRYOLITE]
            [PRODUCT:100:1:BAR:NO_SUBTYPE:METAL:ALUMINUM]
            [FUEL]
        ''',
        add_to_file = add_to_file,
        permit_entities = entities
    )

def restrictnobles_custom(raws, inclusions=None, exclusions=None):
    mountain = raws.get('ENTITY:MOUNTAIN')
    if mountain:
        positions = mountain.alluntil(exact_value='POSITION', until_exact_value='ENTITY')
        if inclusions:
            pydwarf.log.debug('Handling position inclusions %s...' % inclusions)
            for inclusion in inclusions:
                for position in positions: addwm(position, 'ALLOWED_CLASS:WITTY_%s' % inclusion)
                creature = raws.get(exact_value='CREATURE', exact_args=[inclusion])
                if creature:
                    addwm(creature, 'CREATURE_CLASS:WITTY_%s' % inclusion)
                else:
                    return pydwarf.failure('Couldn\'t find CREATURE:%s.' % inclusion)
        if exclusions:
            pydwarf.log.debug('Handling position exclusions %s...' % exclusions)
            for exclusion in exclusions:
                for position in positions: addwm(position, 'REJECTED_CLASS:WITTY_%s' % exclusion)
                creature = raws.get(exact_value='CREATURE', exact_args=[exclusion])
                if creature:
                    addwm(creature, 'CREATURE_CLASS:WITTY_%s' % exclusion)
                else:
                    return pydwarf.failure('Couldn\'t find CREATURE:%s.' % exclusion)
        return pydwarf.success('Restricted %d positions.' % len(positions))
    else:
        return pydwarf.failure('Couldn\'t find ENTITY:MOUNTAIN.')

def subterraneanplants(df):
    # Get subterranean plants
    subplants = []
    for plant in df.allobj('PLANT'):
        if plant.getprop('BIOME:SUBTERRANEAN_WATER'):
            subplants.append(plant)
    if not len(subplants): return pydwarf.failure('Found no subterranean plants.')
    
    # Ensure each has all four seasons
    pydwarf.log.info('Found %d subterranean plants. Modifying...' % len(subplants))
    modified = 0
    for subplant in subplants:
        seasontokens = subplant.allprop(value_in=seasons)
        if len(seasontokens) > 0 and len(seasontokens) < len(seasons):
            pydwarf.log.debug('Adding season tokens to %s...' % subplant)
            # First remove the existing tokens (To avoid making duplicates)
            for seasontoken in seasontokens:
                seasontoken.remove()
            # Then add all four anew
            for season in seasons:
                subplant.add(raws.token(value=season))
            modified += 1
        else:
            pydwarf.log.debug('Plant %s either has no seasonal tokens or already has all of them, skipping.' % subplant)
    
    # All done
    if modified > 0:
        return pydwarf.success('Made %d subterranean plants grow year-round.' % modified)
    else:
        return pydwarf.failure('All subterranean plants already grew year-round.')

def prefstring(df):
    # Get the smallthings ModBase raws, which is where this data will be coming from
    smallraws = getsmallraws()
    if not smallraws: return pydwarf.failure('Failed to read smallthings raws.')
    
    # Get all creatures
    smallcreatures = smallraws.allobj('CREATURE')
    dfcreaturesdict = df.objdict('CREATURE')
    
    # Add the new prefstrings
    failedcreatures = 0
    for smallcreature in smallcreatures:
        dfcreature = dfcreaturesdict.get(smallcreature.args[0])
        if not dfcreature:
            pydwarf.log.debug('Found prefstrings for %s but there was no corresponding creature in the DF raws. Skipping.' % smallcreature)
            failedcreatures += 1
        else:
            prefs = smallcreature.allprop(exact_value='PREFSTRING', args_count=1)
            dfcreature.add(tokens=prefs.copy())
            pydwarf.log.debug('Added %d prefstrings to %s.' % (len(prefs), dfcreature))
            
    # All done!
    if (len(smallcreatures) - failedcreatures):
        return pydwarf.success('Added prefstrings to %d creatures.' % (len(smallcreatures) - failedcreatures))
    else:
        return pydwarf.failure('Added prefstrings to no creatures.')

def addhack(df, auto_run, onload=True, startup=False, **kwargs):
    name = kwargs.get('name', kwargs.get('path', 'unnamed'))
    
    onload_path = 'raw/onLoad.init'
    startup_path = 'dfhack.init'
    
    if kwargs: 
        pydwarf.log.debug('Adding new file %s.' % name)
        hackfile = df.add(**kwargs)
    else:
        hackfile = None
    
    if auto_run:
        if auto_run is True:
            if not hackfile: return pydwarf.failure('Failed to add lines to DFHack because auto_run was True but no file was created.')
            auto_run = '\n%s' % hackfile.name
        
        pydwarf.log.debug('Adding text %s to the end of dfhack.init.' % auto_run)
        addtext = '\n%s\n' % auto_run
        
        if onload:
            if onload_path not in df:
                init = df.add(
                    loc = 'raw',
                    name = 'onLoad',
                    ext = '.init',
                    kind = raws.binfile
                )
            else:
                init = df[onload_path]
            init.add(addtext)
            
        if startup:
            if startup_path not in df:
                if 'dfhack.init-example' in df:
                    pydwarf.log.info('Copying dfhack.init-example to new file dfhack.init before adding new content to the file.')
                    init = df['dfhack.init-example'].copy().bin()
                    init.name = startup_path
                    df.add(file=init)
                else:
                    return pydwarf.failure('Failed to locate dfhack.init or dfhack.init-example.')
            else:
                init = df[startup_path].bin()
            init.add(addtext)
        
        return pydwarf.success(
            'Added text to %s: "%s"' % (
                ' and '.join(
                    item for item in (
                        onload_path if onload else None, startup_path if startup else None
                    ) if item
                ),
                auto_run
            )
        )
        
    else:
        return pydwarf.success('Added new file %s.' % name)

def trans(dfraws, species=default_species, beards=True, frequency=500):
    # Add new interaction
    pydwarf.log.debug('Adding sterility interaction...')
    objinteraction = dfraws.get('OBJECT:INTERACTION')
    if objinteraction:
        objinteraction.add(pretty=add_sterile_interaction)
    else:
        return pydwarf.failure('Unable to add sterility interaction.')
    
    # Add new castes
    creaturetokendict = dfraws.objdict('CREATURE')
    castefailures = []
    for creature in species:
        pydwarf.log.debug('Handling creature %s...' % creature)
        creaturetoken = creaturetokendict.get(creature)
        if creaturetoken:
            castes = creaturetoken.alluntil(exact_value='CASTE', args_count=1, until_exact_value='CREATURE')
            if len(castes) == 2 and ((castes[0].args[0] == 'MALE' and castes[1].args[0] == 'FEMALE') or (castes[1].args[0] == 'MALE' and castes[0].args[0] == 'FEMALE')):
                
                # Remove DESCRIPTION token from the creature and add it to each caste
                descriptiontoken = creaturetoken.get(exact_value='DESCRIPTION', args_count=1)
                if descriptiontoken:
                    descriptiontoken.remove()
                    for castetoken in castes: castetoken.add(token=raws.token.copy(descriptiontoken))
                
                # Handle existing castes
                for caste in castes:
                    # Add beards to dwarven women
                    if beards and caste.args[0] == 'FEMALE': caste.add(pretty=add_beard_tokens)
                    # Add population ratio token
                    caste.add(raws.token(value='POP_RATIO', args=[str(frequency)]))
                
                # Add each new caste
                for castename, castedict in additional_castes.iteritems():
                    castetoken = castes[0].add(raws.token(value='CASTE', args=[castename]), reverse=True)
                    # Every new caste gets these tokens
                    castetoken.add(pretty=add_trans_tokens)
                    # Add beards to new dwarf castes
                    if beards and creature == 'DWARF': castetoken.add(pretty=add_beard_tokens)
                    # Tokens unique to each new caste
                    if 'addtokens' in castedict: castetoken.add(pretty=castedict['addtokens'])
                    # Add the caste-specific description
                    description = ' '.join((descriptiontoken.args[0], castedict['description'])) if descriptiontoken else castedict['description']
                    castetoken.add(raws.token(value='DESCRIPTION', args=[description]))
                    
            else:
                pydwarf.log.error('Unexpected castes for creature %s: %s.' % (creature, castes))
                castefailures.append(creature)
        
        else:
            pydwarf.log.error('Failed to find token for creature %s.' % creature)
            castefailures.append(creature)
    
    if len(castefailures) == 0:
        return pydwarf.success('Added new castes to %d creatures.' % len(species))
    else:
        return pydwarf.failure('Added new castes to %d creatures, but failed to add castes to %s.' % (len(species) - len(castefailures), castefailures))

def addreaction(df, id, tokens, add_to_file='reaction_custom', permit_entities=None):
    if permit_entities is not None and (not addtoentity(df, permit_entities, permitted_reaction=(id,)).success):
        return pydwarf.failure('Failed to add permitted reactions to entites.')
    else:
        if df.getobj(type='REACTION', exact_id=id):
            return pydwarf.failure('Reaction %s already exists.' % id)
        else:
            rfile = df.getfile(add_to_file, create=True)
            rfile.add(raws.token(value='REACTION', args=[id], prefix='\n\n')).add(tokens)
            return pydwarf.success('Added reaction %s to file %s and entities %s.' % (id, add_to_file, permit_entities))

def engraving(df):
    if 'descriptor_shape_umiman' in df: return pydwarf.failure('File descriptor_shape_umiman already exists.')
        
    # Get the smallthings ModBase raws, which is where this data will be coming from
    smallraws = getsmallraws()
    if not smallraws: return pydwarf.failure('Failed to read smallthings raws.')
    
    # Get existing words and shapes
    dfwordsdict = df.objdict('WORD')
    dfshapesdict = df.objdict('SHAPE')
    
    # Add a new file for the new shapes
    dfshapesfile = df.add('raw/objects/descriptor_shape_umiman.txt')
    dfshapesfile.add('OBJECT:DESCRIPTOR_SHAPE')
    shapesadded = 0
    
    # Add each shape
    smallshapes = smallraws['descriptor_shape_standard']
    if smallshapes is None: return pydwarf.failure('Failed to find smallthings raws file named descriptor_shape_standard.')
    for smallshape in smallshapes.all(exact_value='SHAPE'):
        if smallshape.args[0] not in dfshapesdict: # Verify that the shape isn't already in the raws
            pydwarf.log.debug('Adding shape %s...' % smallshape)
            
            # Get the tokens describing this shape
            smallshapetokens = smallshape.all(until_exact_value='SHAPE')
            
            # Shapes in DF's descriptor_shape_standard all have a [WORD:X] token but these do not
            # To compensate, let's do our best to map each shape to a word automatically
            smallshapename = smallshape.get(exact_value='NAME', args_count=2)
            if smallshapename:
                useshapename = smallshapename.args[0].upper()
                if useshapename in shapenamedict: useshapename = shapenamedict[useshapename]
                shapeword = dfwordsdict.get(useshapename)
            else:
                pydwarf.log.error('Found no names for %s.' % shallshape)
                
            # Actually add the new shape to the raws
            dfshapesfile.add(smallshape.copy())
            dfshapesfile.add(smallshapetokens.copy())
            
            # And also add the word, provided one was found
            if shapeword:
                dfshapesfile.add(raws.token(value='WORD', args=(shapeword.args[0],)))
            else:
                pydwarf.log.info('Found no word for %s, named %s.' % (smallshape, smallshapename))
            
            # And on to the next iteration
            shapesadded += 1
    
    # All done!
    return pydwarf.success('Added %s new shapes.' % shapesadded)

def controllable(df, entities='*'):
    controllable = set()
    
    if entities == '*': # Enable all entities
        for entity in df.allobj('ENTITY'):
            entity.setprop('SITE_CONTROLLABLE')
            controllable.add(entity.args[0])
    else: # Enable listed entities and disable others
        entities = set([entities]) if isinstance(entities, basestring) else set(entities)
        for entity in df.allobj('ENTITY'):
            if entity.args[0] in entities:
                entity.setprop('SITE_CONTROLLABLE')
                controllable.add(entity.args[0])
                entities.remove(entity.args[0])
            else:
                entity.removeprop('SITE_CONTROLLABLE')
        if entities:
            pydwarf.log.error(
                'Nonexistent objects in controllable entities list: %s' % ', '.join(entities)
            )
                
    if controllable:
        return pydwarf.success('Assigned %d controllable entities.' % len(controllable))
    else:
        return pydwarf.failure('Assigned no controllable entities.')

def noaquifers(df):
    aquifers = df.all('AQUIFER')
    if len(aquifers):
        for aquifer in aquifers: aquifer.remove()
        return pydwarf.success('Removed %d AQUIFER tokens.' % len(aquifers))
    else:
        return pydwarf.failure('Found no AQUIFER tokens.')

def metalitems(df, metals=default_metals, items=default_item_tokens):
    # Handle each metal
    modified = 0
    for inorganictoken in df.allobj('INORGANIC'):
        if inorganictoken.args[0] in metals:
            metal = inorganictoken.args[0]
            pydwarf.log.debug('Handling metal %s...' % metal)
            itemtokens = inorganictoken.allprop(value_in=items)
            if len(itemtokens) < len(items):
                pydwarf.log.debug('Adding tokens to metal %s...' % metal)
                # Remove existing item tokens from the list (To avoid making duplicates)
                for itemtoken in itemtokens:
                    itemtoken.remove()
                # Add new ones
                templatetoken = inorganictoken.getlastprop('USE_MATERIAL_TEMPLATE')
                addaftertoken = templatetoken if templatetoken else inorganictoken
                for item in items:
                    addaftertoken.add(item)
                modified += 1
            else:
                pydwarf.log.debug('Metal %s already allows all the item types specified, skipping.' % metal)
            
    # All done
    if modified > 0:
        return pydwarf.success('Added tokens to %d metals.' % modified)
    else:
        return pydwarf.failure('No tokens were added to any metals.')

def permitobject(df, type=None, id=None, permit_entities=None, all_entities=False, item_rarity=None):
    # Decide what tokens need to be added to the entities based on the object type
    if type == 'REACTION':
        tokens = raws.token(value='PERMITTED_REACTION', args=[id])
    elif type.startswith('BUILDING_'):
        tokens = raws.token(value='PERMITTED_BUILDING', args=[id])
    elif type.startswith('ITEM_'):
        value = type.split('_')[1]
        args = [id, item_rarity] if item_rarity else [id]
        tokens = raws.token(value=value, args=args)
    else:
        tokens = None
    
    pydwarf.log.debug('Permitting object [%s:%s] for %s entities.' % (
        type, id, 'all' if all_entities == '*' else len(permit_entities)
    ))
    
    # Actually add those tokens
    if tokens is None:
        return pydwarf.success('Didn\'t actually permit object [%s:%s] because objects of this type cannot be permitted.' % (type, id))
    elif not permit_entities:
        return pydwarf.failure('No entities were given for permitting.')
    else:
        response = addtoentity(
            df,
            entities = permit_entities,
            tokens = tokens
        )
        if not response:
            return response
        else:
            return pydwarf.success('Permitted object [%s:%s] for %d entities.' % (type, id, len(permit_entities)))

def maxage(df, required_property=default_required_property, apply_to_creatures=None):
    removedfrom = []
    creaturedict = df.objdict('CREATURE')
    
    # Handle by properties
    if required_property:
        remove_all = len(required_property) == 1 and required_property[0] == '*'
        for creaturename, creaturetoken in creaturedict.iteritems():
            if remove_all or (creaturetoken.getprop(value_in=required_property) is not None):
                maxage = creaturetoken.getprop('MAXAGE')
                if maxage: maxage.remove(); removedfrom.append(creaturetoken)
                    
    # Handle by creature names
    if apply_to_creatures:
        for creaturename in apply_to_creatures:
            creaturetoken = creaturedict.get(creaturename)
            if creaturetoken:
                maxage = creaturetoken.getprop('MAXAGE')
                if maxage: maxage.remove(); removedfrom.append(creaturetoken)
            else:
                pydwarf.log.error('Couldn\'t find creature %s for removal of MAXAGE token.' % creaturename)
                
    # All done!
    pydwarf.log.debug('Removed MAXAGE tokens from creatures: %s.' % [token.args[0] for token in removedfrom])
    if len(removedfrom):
        return pydwarf.success('Removed MAXAGE tokens from %d creatues.' % len(removedfrom))
    else:
        return pydwarf.failure('Found no MAXAGE tokens to remove.')
        

def materialsplus(df, entities=default_entities):
    # Add properties to various inorganics as defined by the add_properties dict
    errors = 0
    for identifier, re_id, addprops in add_properties:
        additions = df.allobj(type='INORGANIC', re_id=re_id).each(
            lambda token: token.addprop(addprops), none=True
        )
        if len(additions):
            pydwarf.log.debug('Added %s properties to %d inorganics.' % (identifier, len(additions)))
        else:
            errors += 1
            pydwarf.log.error('Failed to add %s properties because no matching inorganics were found.' % identifier)
    
    for path in add_paths:
        pydwarf.log.debug('Adding file at %s.' % path)
        df.add(path=path, loc='raw/objects')
    
    for path in patch_paths:
        response = pydwarf.urist.getfn('pineapple.easypatch')(
            df,
            files = path,
            loc = 'raw/objects',
            permit_entities = entities
        )
        if not response: return response
    
    if not errors:
        return pydwarf.success()
    else:
        return pydwarf.failure('Failed to add inorganic properties for %d groups.' % errors)

def stoneclarity(dfraws, rules=default_rules, query=default_inorganics_query, fuels=None):
    if rules and len(rules):
        groups, ids = builddicts(query, dfraws, fuels if fuels else autofuels(dfraws, pydwarf.log), pydwarf.log)
        applyrules(rules, groups, ids)
        return pydwarf.success('Finished applying %d rules to %d inorganic groups and %d inorganic ids.' % (len(rules), len(groups), len(ids)))
    else:
        return pydwarf.failure('I was given no rules to follow.')

def noaquifers(df):
    # Do the removing
    aquifers = df.removeall('AQUIFER')
    # All done!
    if len(aquifers):
        return pydwarf.success('Removed %d AQUIFER tokens.' % len(aquifers))
    else:
        return pydwarf.failure('Found no AQUIFER tokens.')

def nograzers(raws):
    grazers = raws.all(exact_value='GRAZER')
    standardgrazers = raws.all('STANDARD_GRAZER')
    for grazer in grazers: grazer.remove()
    for grazer in standardgrazers: grazer.remove()
    if len(grazers) or len(standardgrazers):
        return pydwarf.success('Removed %d GRAZER and %d STANDARD_GRAZER tokens.' % (len(grazers), len(standardgrazers)))
    else:
        return pydwarf.failure('I found no grazer tokens to replace.')

def noexotic(df):
    pets = df.all('PET_EXOTIC')
    mounts = df.all('MOUNT_EXOTIC')
    for token in pets: token.value = 'PET'
    for token in mounts: token.value = 'MOUNT'
    if len(pets) or len(mounts):
        return pydwarf.success('Replaced %d PET_EXOTIC and %d MOUNT_EXOTIC tokens.' % (len(pets), len(mounts)))
    else:
        return pydwarf.failure('I found no PET_EXOTIC or MOUNT_EXOTIC tokens to replace.')

def deerappear(df, creature='DEER', tile="'d'", color=['6','0','1']):
    # Find the first token that looks like [CREATURE:DEER]
    deertoken = df.getobj('CREATURE', creature)
    if deertoken:
        # Find the first token, following [CREATURE:DEER], that looks like [CREATURE_TILE:'D']
        deertile = deertoken.getprop(exact_value='CREATURE_TILE', args_count=1)
        # Find the first token, following [CREATURE:DEER], that looks like [COLOR:6:0:0]
        deercolor = deertoken.getprop(exact_value='COLOR', args_count=3)
        if deertile and deercolor:
            # Change the token to look like [CREATURE_TILE:'d']
            deertile.args[0] = tile
            # Change the token to look like [COLOR:6:0:1]
            deercolor.args = color
            return pydwarf.success()
        else:
            return pydwarf.failure('Didn\'t find CREATURE_TILE and COLOR tokens as expected.')
    else:
        return pydwarf.failure('I couldn\'t find the deer token.')

def nograzers(df):
    # Do the removing
    grazers = df.removeall('GRAZER')
    standardgrazers = df.removeall('STANDARD_GRAZER')
    
    # All done!
    if len(grazers) or len(standardgrazers):
        return pydwarf.success('Removed %d GRAZER and %d STANDARD_GRAZER tokens.' % (len(grazers), len(standardgrazers)))
    else:
        return pydwarf.failure('I found no grazer tokens to remove.')