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 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 vegan(df, labors=default_labors, lua_file=default_lua_file, auto_run=False, entities=default_entities, add_to_file=default_file):
    # Add the reactions
    addreaction = pydwarf.urist.getfn('pineapple.utils.addobject')
    for reactionid, reactioncontent in vegan_reactions.iteritems():
        pydwarf.log.debug('Adding reaction %s.' % reactionid)
        response = addreaction(
            df,
            type = 'REACTION',
            id = reactionid,
            tokens = reactioncontent,
            add_to_file = add_to_file,
            permit_entities = entities
        )
        if not response.success: return response
    
    # Add the dfhack script
    if labors and lua_file:
        pydwarf.log.debug('Adding DFHack script %s.' % lua_file)
        pydwarf.urist.getfn('pineapple.utils.addhack')(
            df,
            name = lua_file,
            content = format_lua_content(lua_content, labors),
            auto_run = auto_run
        )
    
    # All done
    return pydwarf.success()

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 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 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 easypatch_dirpath(df, path, loc=None, **kwargs):
    for root, dirnames, filenames in os.walk(path):
        for filename in filenames:
            filepath = os.path.join(root, filename)
            response = easypatch_filepath(df, path=filepath, loc=loc, root=root, **kwargs)
            if not response: return response
    return pydwarf.success('Added files from directory %s.' % path)

def full(df, variety='24x24', properties=properties_path):
    pydwarf.log.info('Running dragondeplatino.gemset.twbt.')
    response = twbt(df, variety)
    if not response: return response
    
    pydwarf.log.info('Running dragondeplatino.gemset.graphics.')
    response = graphics(df, variety)
    if not response: return response
    
    pydwarf.log.info('Running dragondeplatino.gemset.font.')
    response = font(df, variety)
    if not response: return response
    
    pydwarf.log.info('Running dragondeplatino.gemset.art.')
    response = art(df, variety)
    if not response: return response
    
    pydwarf.log.info('Running dragondeplatino.gemset.hack.')
    response = hack(df)
    if not response: return response
    
    pydwarf.log.info('Running dragondeplatino.gemset.objects.')
    response = objects(df, properties)
    if not response: return response
    
    # All done
    return pydwarf.success()

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 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 font(df, variety='24x24'):
    # Copy over the font image
    mapfile = 'gemset_map.png'
    df.add(
        path = pydwarf.rel(gemset_dir, 'data/art/', variety, mapfile),
        loc = 'data/art',
        kind = raws.reffile
    )
    
    # Copy over the curses image
    cursesfile = 'gemset_curses_%s.png' % curses_resolutions.get(variety)
    df.add(
        path = pydwarf.rel(gemset_dir, 'data/art/', variety, cursesfile),
        loc = 'data/art',
        kind = raws.reffile
    )
    
    # Adjust init.txt settings accordingly
    init = df['data/init/init.txt'].raw()
    init.set(value='FONT', arg=cursesfile)
    init.set(value='FULLFONT', arg=cursesfile)
    init.set('GRAPHICS:YES')
    init.set(value='GRAPHICS_FONT', arg=mapfile)
    init.set(value='GRAPHICS_FULLFONT', arg=mapfile)
    init.set('PRINT_MODE:TWBT')
    init.set('BLACK_SPACE:YES')
    init.set('TRUETYPE:NO')
    
    # All done
    return pydwarf.success()

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 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 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.')