Merge branch 'develop' for v1.0.2

Conflicts:
	docs/tutorial.md
	readme.md

Author: pineapplemachine

changelog.txt

@@ -1,10 +1,38 @@
+v1.0.2: Magma Forge
+
+Fixed the vagueness of most exceptions in the raws and pydwarf packages, most of them should now be reasonably forthcoming about what went wrong and why.
+Fixed bug in raws.token.add which was arising from a dumb typo and really should have been caught long before.
+Renamed raws.dir.addfile to raws.dir.add and raws.dir.setfile to raws.dir.set.
+Renamed raws.file to raws.rawfile to make things less confusing in light of some other additions.
+Renamed stal.armourypack to stal.armoury because why not.
+Removed pineapple.utils.addreaction, which has been superseded by the newer and shinier pineapple.utils.addobject.
+Added a great deal of functionality to the raws.dir object, which is now capable of tracking an entire DF directory as opposed to just its raw/objects subdirectory.
+Added three new file classes: raws.basefile, raws.reffile, and raws.binfile.
+Added more documentation and tutorials, big surprise. (Also added and neglected to document a bunch of new functionality while I was at it, he he he.)
+Added a number of handy new operator overloads and fiddled a few existing ones while I was at it.
+Added methods like raws.queryable.removefirst, raws.queryable.removeall, and quite a few more.
+Added script pkdawson.vegan, a port of df-vegan.
+Added scripts underneath omniclasm.decay, a port of State of Decay.
+Added scripts umiman.smallthings.threats and umiman.smallthings.nofamily, ports of parts of smallthings that PyDwarf couldn't support until now.
+Added scripts pineapple.easypatch, pineapple.utils.addobject, pineapple.utils.addobjects, pineapple.utils.permitobject, pineapple.utils.permitobjects, and pineapple.utils.addhack.
+Added raws.objects module which helps with knowing some things about how raws files are supposed to be structured.
+Added a very nifty raws.tokenlist.each method which did great wonders for terseness of some mods.
+Improved general flow and structure of manager code against pydwarf.session code, moved things around and generally tidied up.
+Improved the __getitem__ method for raws.queryable objects so that now it can handle ellipses and slices and some other stuff too.
+Improved the way token arguments are internally handled, and made a few changes to pertinent token methods.
+Improved pineapple.utils.addentity and made a pretty big change to how it accepts arguments in the process.
+Improved raws.queryable.getobj and raws.queryable.allobj methods, now they can do even more stuff than before.
+Improved the raws.tokenfilter constructor, which is now decent enough to handle passing a single tuple/whatever to exact_arg, re_arg, or arg_in rather than an iterable of them.
+Improved stal.armoury, putnam.materialsplus, putnam.microreduce, shukaro.higherlearning, and shukaro.creationforge by rewriting each of them entirely.
+Tweaked almost every script in some way, really, mostly in the interest of utilizing newer and more awesome functionality.
+
 v1.0.1: Strange Mood
 
 Fixed pineapple.boneflux reaction by being less bad at string formatting
 Fixed pineapple.utils.addreaction not adding an OBJECT:REACTION token to created files
 Fixed new grasses in pineapple.cavegrass not being recognized by DF
 Fixed a small issue with logging in pineapple.cavegrass
-Fixed non-raws file from input directory not being written to output
+Fixed non-raws files from input directory not being written to output
 Fixed pydwarf.response casting to string always returning a string starting with "SUCCESS" even when unsuccessful
 Added a lot more documentation
 Added a shitty WIP tool for outputting docstrings as more readable html

config.json

@@ -2,11 +2,14 @@
 
     "comment":  "This is an example file! Before running the manager you will need to change the provided paths to better suit your particular setup.",
 
-    "input":    "E:/Sophie/Desktop/Files/Games/Dwarf Fortress/df_40_24_win/rawvanilla/objects",
-    "output":   "E:/Sophie/Desktop/Files/Games/Dwarf Fortress/df_40_24_win/raw/objects",
-    "backup":   "E:/Sophie/Desktop/Files/Games/Dwarf Fortress/df_40_24_win/rawbak/",
+    "input":    "E:/Sophie/Desktop/Files/Games/Dwarf Fortress/df_40_24_win/",
+    "output":   "E:/Sophie/Desktop/Files/Games/Dwarf Fortress/df_40_24_win/pydwarf_output",
+    "backup":   "E:/Sophie/Desktop/Files/Games/Dwarf Fortress/df_40_24_win/pydwarf_backup",
+    
+    "paths": "auto",
 
     "version":  "auto",
+    "hackversion": "auto",
 
     "scripts": [
         {

config/__init__.py

@@ -13,7 +13,9 @@
         'input': os.path.join(dfdir, 'vanillaraw/objects'),
         'output': 'output',
         'backup': 'backup',
+        'paths': 'auto',
         'version': 'auto',
+        'hackversion': 'auto',
         'scripts': [
             {
                 'name': 'pineapple.deerappear',
@@ -36,3 +38,4 @@
 else:
 
     export = {}
+

config/config.py

@@ -3,14 +3,14 @@
 import sys
 import os
 
-sys.path.append(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..'))
+sys.path.append(os.path.join(os.path.dirname(os.path.abspath(__file__)), '../..'))
 
 import inspect
 
 import raws
 import pydwarf
 
-output = 'index.html'
+output = '../index.html'
 
 items = {
     'raws.token': raws.token,

config_override.py

@@ -0,0 +1,2 @@
+cd ../../
+python manager.py --meta --metaformat "md" --writedoc "docs/scripts.md"

docs/build.py docs/bin/build.pydocs/build.py renamed to docs/bin/build.py

@@ -0,0 +1,2 @@
+cd ../../
+python manager.py --meta --metaformat "md" --writedoc "docs/scripts.md"

docs/bin/scripts.bat

@@ -0,0 +1,27 @@
+# Configuring PyDwarf
+
+The steps given here are specifically for Windows, but the procedure on other operating systems will be almost identical.
+
+- First thing, ensure that [Python 2.7](https://www.python.org/download/releases/2.7.8/) is installed on your computer. If you have another version of Python already installed this can be a little complicated but there are lots of [helpful resources](http://stackoverflow.com/questions/4583367/how-to-run-multiple-python-version-on-windows) available to guide you through it.
+
+- In order to keep everything working as smoothly as possible, you should copy your Dwarf Fortress directory to another location before messing about with PyDwarf. Navigate to the directory containing your Dwarf Fortress folder, copy it, and paste it somewhere. It may be easiest to place the copy in the same location and append `_original` to the end of the directory's name. After doing this you might, for example, have a folder at `C:/df_40_24_win` and another at `C:/df_40_24_win_original`.
+
+- If you haven't already, you'll need to download PyDwarf and extract the archive somewhere. It much doesn't matter where, though I recommend you *don't* put it inside your Dwarf Fortress directory. The most important files located in here are named `manager.py`, which is for actually running PyDwarf, and `config.json`, for telling it precisely what to do when it runs.
+
+- You'll want to open the `config.json` file, located in PyDwarf's root directory, with a text editor such as Notepad. And then you'll be looking at a JSON file. It assigns several parameters in the format of `"name": value,` and the most important ones right now are the ones named `input`, `output`, `backup`, and `scripts`. You can see that most of the values are text information enclosed within quotes, but `scripts` in particular is assigned a list of values contained within square brackets.
+
+- Set the value for `input`, which is a file path, to the location of that copy of Dwarf Fortress you made in a previous step. This tells PyDwarf where to read your files from so that they can be worked upon by various mods. For example, this file path might be something like `C:/df_40_24_win_original`.
+
+- And set the value for `output`, which is also a file path, to the location of the Dwarf Fortress folder that you play with. This is where PyDwarf will write your files to when it's finished modifying them. This path might look like `C:/df_40_24_win`.
+
+- As well as the value for `backup`, another file path, to somewhere for the Dwarf Fortress files to be backed up to. This could be something like the name of the `input` folder with `_backup` appended. This helps to ensure that if something weird goes wrong - and don't worry, it really shouldn't - you'll still have a copy of your original files lying around somewhere. The path might look like `C:/df_40_24_win_backup`.
+
+- And the really fun part is the `scripts` parameter. Here names of scripts are given in the order that they should be run. It's also possible to pass arguments to scripts here, which change the way it behaves. One way to get a list of the available scripts is to run `python manager.py --list`, and one way to see documentation regarding one of these scripts to describe its purpose and usage is to run `python manager.py --meta script.name`.
+
+- For the sake of example, you can try adding an item to the end of the `scripts` list, the text (including quotes) `"pineapple.subplants"`. In doing so, be sure to add a comma to the end of the previous line, these commas serve to separate items in the list.
+
+- Installing new mods for PyDwarf is really simple, if you want to use one that didn't come packaged with it. Simply place the uncompressed files, which should include at least one with a name like `pydwarf.scriptname.py`, anywhere in the `scripts` directory located within PyDwarf's root directory. If you had installed a mod named `this.is.a.script`, for example, you could tell PyDwarf to include it by adding it in the same way as the previous script: In the `scripts` list of `config.json`, you'd need to add a line to the list that looks like `"this.is.a.script"`.
+
+- And finally, to actually run PyDwarf and apply the mods, run `python manager.py`. It will helpfully tell you if anything went wrong and, if so, what exactly happened. But PyDwarf is a piece of work and sometimes those errors may be hard to understand. If you're not sure how to fix it, you can always post in the [GitHub issue tracker](https://github.com/pineapplemachine/PyDwarf/issues) or the [Bay12 forum topic](http://www.bay12forums.com/smf/index.php?topic=150857.msg6239158#msg6239158) to ask for help.
+
+- After running `manager.py`, if everything went smoothly, you're all done! Now you can run Dwarf Fortress and generate a new world to see the changes take effect.