Commits

zzzeek  committed 2e67fb7

docs

  • Participants
  • Parent commits 8b33121

Comments (0)

Files changed (2)

 Synopsis
 ========
 
-nbt2yaml presents a Python parser/writer for Minecraft NBT files.   It then includes a system that can marshal
-this format to/from Yaml files.   Finally, it provides simple shell commands to provide these transformations,
-including ``editnbt``, which will shell out the Yaml version of the file to your editor of choice, allowing
-easy command-line editing of NBT files.
+nbt2yaml presents a command line interface for reading and editing Minecraft NBT files using a
+custom YAML format.   It also includes a Python API for parsing and writing NBT files to/from
+a simple Python data structure.
+
+The key tool is ``nbtedit``, a command line utility that will shell out the 
+YAML version of the target NBT file to your editor of choice, allowing
+relatively easy editing of NBT data.   When the editing session is closed,
+the saved file is parsed back into NBT, and if changes have occurred, the original
+file is updated; a copy of the previous version is saved as well.
 
 NBT format:  http://www.minecraft.net/docs/NBT.txt
 
-Yaml: http://www.yaml.org/
+YAML: http://www.yaml.org/
 
 Installation
 ============
 
-Install via pip is easiest::
+Install via ``pip`` or ``easy_install`` is easiest::
 
     pip install http://bitbucket.org/zzzeek/nbt2yaml
 
 nbtedit
 --------
 
-Edits an nbt file in-place, allowing Yaml format within the editor.
+Edits an nbt file in-place, allowing YAML format within the editor.
 
 The script uses the standard ``EDITOR`` environment variable to determine which
 text editor should be invoked.
 
+The program detects if changes were made when the editing session is closed;
+if so, the existing nbt file is copied to a backup unconditionally, and the new
+data is written to the file in place.
+
 Synopsis::
 
     usage: nbtedit [-h] [-n] filename
 nbt2yaml
 --------
 
-Dumps an nbt file as yaml to standard output::
+Dumps an nbt file as YAML to standard output::
 
     usage: nbt2yaml [-h] [-n] filename
 
 yaml2nbt
 --------
 
-Dumps a yaml file generated by nbt2yaml as nbt to standard output::
+Dumps a YAML file generated by nbt2yaml as nbt to standard output::
 
     usage: yaml2nbt [-h] [-n] filename
 
       -h, --help     show this help message and exit
       -n, --no-gzip  Don't use gzip
 
+Format
+======
+
+The specifics of how NBT is mapped to YAML is of course a
+decision this program has to make, as there are any
+number of ways to do it. The goal here is to have a YAML
+format that is as minimal and readable as possible, while
+still maintaining the ability to write the identical nbt
+file as the one parsed; for this reason, many datatypes
+have explicit directives (i.e. short, long, double, byte)
+which will result in the appropriate nbt tag (i.e.
+TAG_Short, TAG_Long, TAG_Double, TAG_Byte). The default
+for ``int``, ``str`` and ``float`` Python types are
+TAG_Int, TAG_String, and TAG_Float, respectively.
+
+When editing a YAML file, it's important to keep the
+formatting **exactly** the same! nbt2yaml can only handle
+structures that are in the form in which it generates;
+see the example below to see all of these forms.
+
+While nbt2yaml can handle any kind of data provided the
+format is correct, it's expected that the normal use of
+this tool is just to change individual values without
+changing the document structure.
+
+A current dump of the Minecraft reference file
+``bigtest.nbt`` in YAML format is below. Suggestions on
+improving this format are welcome !
+
+::
+
+    Level:
+    - longTest: !long "9223372036854775807L"
+    - shortTest: !short "32767"
+    - stringTest: !!python/str "HELLO WORLD THIS IS A TEST STRING \xC5\xC4\xD6!"
+    - floatTest: 0.4982314705848694
+    - intTest: 2147483647
+    - nested compound test:
+      - ham:
+        - name: Hampus
+        - value: 0.75
+      - egg:
+        - name: Eggbert
+        - value: 0.5
+    - listTest (long):
+      - !long "11"
+      - !long "12"
+      - !long "13"
+      - !long "14"
+      - !long "15"
+    - listTest (compound):
+      - - name: 'Compound tag #0'
+        - created-on: !long "1264099775885L"
+      - - name: 'Compound tag #1'
+        - created-on: !long "1264099775885L"
+    - byteTest: !byte "127"
+    - byteArrayTest (the first 1000 values of (n*n*255+n*7)%100, starting with n=0 (0, 62, 34, 16, 8, ...)): !byte_array "\0\
+        >\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1C\
+        P*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16\
+        ^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10\
+        :\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\
+        \x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\
+        \x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1A\
+        D\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\
+        \x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E\
+        `XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04\
+        $N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\n\
+        H,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\
+        \x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\
+        \x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1A\
+        D\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\
+        \x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E\
+        `XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04\
+        $N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\n\
+        H,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\
+        \x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\
+        \x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1A\
+        D\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\
+        \x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E\
+        `XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04\
+        $N\x1E\\@.&(4J\x060"
+    - doubleTest: !double "0.4931287132182315"
+
+

File nbt2yaml/main.py

 import os
 
 def nbtedit():
-    parser = argparse.ArgumentParser(description="Edit an nbt file in-place in Yaml format.")
+    parser = argparse.ArgumentParser(description="Edit an nbt file in-place in yaml format.")
     parser.add_argument("filename", type=str, help="filename")
     parser.add_argument("-n", "--no-gzip", 
                         action="store_true",