Package dgamevfs on DUB

To use this package, run the following command in your project's root directory:

<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" /> <title>D:GameVFS 0.2</title> <style type="text/css">

/* :Author: David Goodger ([email protected]) :Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $ :Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to customize this style sheet. */

/ used to remove borders from tables and images / .borderless, table.borderless td, table.borderless th { border: 0 }

table.borderless td, table.borderless th { /* Override padding for "table.docutils td" with "! important".

 The right padding separates the table cells. */

padding: 0 0.5em 0 0 ! important }

.first { / Override more specific margin styles with "! important". / margin-top: 0 ! important }

.last, .with-subtitle { margin-bottom: 0 ! important }

.hidden { display: none }

a.toc-backref { text-decoration: none ; color: black }

blockquote.epigraph { margin: 2em 5em ; }

dl.docutils dd { margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { overflow: hidden; }

/ Uncomment (and remove this text!) to get bold-faced definition list terms dl.docutils dt { font-weight: bold } /

div.abstract { margin: 2em 5em }

div.abstract p.topic-title { font-weight: bold ; text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error, div.hint, div.important, div.note, div.tip, div.warning { margin: 2em ; border: medium outset ; padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title, div.important p.admonition-title, div.note p.admonition-title, div.tip p.admonition-title { font-weight: bold ; font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title, div.danger p.admonition-title, div.error p.admonition-title, div.warning p.admonition-title, .code .error { color: red ; font-weight: bold ; font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in compound paragraphs. div.compound .compound-first, div.compound .compound-middle { margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle { margin-top: 0.5em } */

div.dedication { margin: 2em 5em ; text-align: center ; font-style: italic }

div.dedication p.topic-title { font-weight: bold ; font-style: normal }

div.figure { margin-left: 2em ; margin-right: 2em }

div.footer, div.header { clear: both; font-size: smaller }

div.line-block { display: block ; margin-top: 1em ; margin-bottom: 1em }

div.line-block div.line-block { margin-top: 0 ; margin-bottom: 0 ; margin-left: 1.5em }

div.sidebar { margin: 0 0 0.5em 1em ; border: medium outset ; padding: 1em ; background-color: #ffffee ; width: 40% ; float: right ; clear: right }

div.sidebar p.rubric { font-family: sans-serif ; font-size: medium }

div.system-messages { margin: 5em }

div.system-messages h1 { color: red }

div.system-message { border: medium outset ; padding: 1em }

div.system-message p.system-message-title { color: red ; font-weight: bold }

div.topic { margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { margin-top: 0.4em }

h1.title { text-align: center }

h2.subtitle { text-align: center }

hr.docutils { width: 75% }

img.align-left, .figure.align-left, object.align-left { clear: left ; float: left ; margin-right: 1em }

img.align-right, .figure.align-right, object.align-right { clear: right ; float: right ; margin-left: 1em }

img.align-center, .figure.align-center, object.align-center { display: block; margin-left: auto; margin-right: auto; }

.align-left { text-align: left }

.align-center { clear: both ; text-align: center }

.align-right { text-align: right }

/ reset inner alignment in figures / div.align-right { text-align: inherit }

/ div.align-center { / / text-align: left } */

ol.simple, ul.simple { margin-bottom: 1em }

ol.arabic { list-style: decimal }

ol.loweralpha { list-style: lower-alpha }

ol.upperalpha { list-style: upper-alpha }

ol.lowerroman { list-style: lower-roman }

ol.upperroman { list-style: upper-roman }

p.attribution { text-align: right ; margin-left: 50% }

p.caption { font-style: italic }

p.credits { font-style: italic ; font-size: smaller }

p.label { white-space: nowrap }

p.rubric { font-weight: bold ; font-size: larger ; color: maroon ; text-align: center }

p.sidebar-title { font-family: sans-serif ; font-weight: bold ; font-size: larger }

p.sidebar-subtitle { font-family: sans-serif ; font-weight: bold }

p.topic-title { font-weight: bold }

pre.address { margin-bottom: 0 ; margin-top: 0 ; font: inherit }

pre.literal-block, pre.doctest-block, pre.math, pre.code { margin-left: 2em ; margin-right: 2em }

pre.code .ln { color: grey; } / line numbers / pre.code, code { background-color: #eeeeee } pre.code .comment, code .comment { color: #5C6576 } pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } pre.code .literal.string, code .literal.string { color: #0C5404 } pre.code .name.builtin, code .name.builtin { color: #352B84 } pre.code .deleted, code .deleted { background-color: #DEB0A1} pre.code .inserted, code .inserted { background-color: #A3D289}

span.classifier { font-family: sans-serif ; font-style: oblique }

span.classifier-delimiter { font-family: sans-serif ; font-weight: bold }

span.interpreted { font-family: sans-serif }

span.option { white-space: nowrap }

span.pre { white-space: pre }

span.problematic { color: red }

span.section-subtitle { / font-size relative to parent (h1..h6 element) / font-size: 80% }

table.citation { border-left: solid 1px gray; margin-left: 1px }

table.docinfo { margin: 2em 4em }

table.docutils { margin-top: 0.5em ; margin-bottom: 0.5em }

table.footnote { border-left: solid 1px black; margin-left: 1px }

table.docutils td, table.docutils th, table.docinfo td, table.docinfo th { padding-left: 0.5em ; padding-right: 0.5em ; vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name { font-weight: bold ; text-align: left ; white-space: nowrap ; padding-left: 0 }

/ "booktabs" style (no vertical lines) / table.docutils.booktabs { border: 0px; border-top: 2px solid; border-bottom: 2px solid; border-collapse: collapse; } table.docutils.booktabs * { border: 0px; } table.docutils.booktabs th { border-bottom: thin solid; text-align: left; }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { font-size: 100% }

ul.auto-toc { list-style-type: none }

</style> </head> <body> <div class="document" id="d-gamevfs-0-2"> <h1 class="title">D:GameVFS 0.2</h1>

<img alt="https://travis-ci.org/kiith-sa/D-GameVFS.svg?branch=master" src="https://travis-ci.org/kiith-sa/D-GameVFS.svg?branch=master" /> <a class="reference external image-reference" href="http://code.dlang.org"><img alt="https://raw.githubusercontent.com/kiith-sa/D-GameVFS/master/code.dlang.org-shield.png" src="https://raw.githubusercontent.com/kiith-sa/D-GameVFS/master/code.dlang.org-shield.png" /></a> <div class="section" id="introduction"> <h1>Introduction</h1> D:GameVFS is a minimalist open source virtual file system library for the D programming language oriented at game developers. Provided functionality is very basic - files and directories can be created, read and written, but not deleted. There are no security features - e.g. D:GameVFS can't handle a situation when a file it's working with is deleted outside the program. Only files in a physical file system are supported at the moment. There is no archive support right now. D:GameVFS is a work in progress and its API is not stable. There might be compatibility breaking changes in future versions. </div> <div class="section" id="features"> <h1>Features</h1> <ul class="simple"> <li>File system independent, easy to use API for file/directory manipulation.</li> <li>Detailed <a class="reference external" href="http://ddocs.org/dgamevfs/latest/index.html">API documentation</a> (a <a class="reference external" href="http://ddocs.org">DDocs.org</a>) with code examples.</li> <li>No external dependencies.</li> <li>Seamless access to multiple directories as if they were a single directory.</li> <li>Easy to extend with custom file system backend.</li> <li>There is no support for ZIP or similar archive formats at the moment.</li> <li>There is no support for deleting files/directories, and none is planned.</li> <li>There are no security features and none are planned.</li> </ul> </div> <div class="section" id="directory-structure"> <h1>Directory structure</h1> <table border="1" class="docutils"> <colgroup> <col width="17%" /> <col width="83%" /> </colgroup> <thead valign="bottom"> <tr><th class="head">Directory</th> <th class="head">Contents</th> </tr> </thead> <tbody valign="top"> <tr><td><tt class="docutils literal">./</tt></td> <td>This README file, utility scripts.</td> </tr> <tr><td><tt class="docutils literal">./doc</tt></td> <td>API documentation, also found <a class="reference external" href="http://defenestrate.eu/docs/dgamevfs">online</a></td> </tr> <tr><td><tt class="docutils literal">./source</tt></td> <td>Source code.</td> </tr> <tr><td><tt class="docutils literal">./examples</tt></td> <td>Code examples.</td> </tr> </tbody> </table> </div> <div class="section" id="getting-started"> <h1>Getting started</h1> <div class="section" id="install-the-dmd-compiler"> <h2>Install the DMD compiler</h2> Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its newest version <a class="reference external" href="http://dlang.org/download.html">here</a>. Download the version of DMD for your operating system and install it. <div class="note"> Note Other D compilers exist, such as <a class="reference external" href="http://gdcproject.org/">GDC</a> and <a class="reference external" href="http://bitbucket.org/goshawk/gdc/wiki/Home">LDC</a>. </div> </div> <div class="section" id="install-dub"> <h2>Install dub</h2> <a class="reference external" href="http://code.dlang.org/about">dub</a> is a build system and package manager for D. It is the standard way to manage D projects and their dependencies, compilation and so on. DMD may include DUB in future releases, but at this point we need to install it separately. See <a class="reference external" href="https://github.com/D-Programming-Language/dub#installation">installation instructions</a>. </div> <div class="section" id="simple-d-gamevfs-project"> <h2>Simple D:GameVFS project</h2> Create a directory for your project. To have something for D:GameVFS to work with, create subdirectories <tt class="docutils literal">maindata and userdata</tt> in the project directory. In these directories, create some random files or subdirectories. Create a file called <tt class="docutils literal">main.d</tt> in your project directory. Paste the following code into the file: <pre class="code d literal-block"> import std.stdio; import std.typecons; import dgamevfs._;

void main() { // Two filesystem directories, one read-only and the other read-write. auto main = new FSDir("main", "main_data/", No.writable); auto user = new FSDir("user", "user_data/", Yes.writable); // Stack directory where "user" overrides "main". auto stack = new StackDir("root"); stack.mount(main); stack.mount(user); // Iterate over all files recursively, printing their VFS paths. foreach(file; stack.files(Yes.deep)) { writeln(file.path); } VFSFile file = stack.file("new_file.txt"); // Creates "new_file" in "user" (which is on top of "main" in the stack). file.output.write(cast(const void[])"Hello World!"); // Read what we've written. auto buffer = new char[file.bytes]; file.input.read(cast(void[]) buffer); writeln(buffer);

} </pre> Code for this example can be found in the <tt class="docutils literal">examples/gettingstarted directory.

See the API documentation in the doc/html/ directory (in particular, the dgamevfs.vfs module) for more code examples.

Explanation of the code

We start by importing dgamevfs. which imports all needed D:GameVFS modules. D:GameVFS uses the Flag template instead of booleans for more descriptive parameters (such as <tt class="docutils literal">Yes.writable</tt> instead of <tt class="docutils literal">true</tt>). You need to import std.typecons to use Flag. We create two FSDirs - physical file system directory objects, which will be called <tt class="docutils literal">main</tt> and <tt class="docutils literal">user</tt> in the VFS and will represent the <tt class="docutils literal">maindata and userdata</tt> directories which we've created in our project directory. We construct <tt class="docutils literal">main</tt> as a non-writable directory - it's read-only for the VFS. Next, we create a StackDir and mount() our directories to it. StackDir works with mounted directories as if they were a single directory - for instance, reading <tt class="docutils literal">file.txt</tt> from the StackDir, will first try to read <tt class="docutils literal">userdata/file.txt, and if that file does not exist, maindata/file.txt</tt>. Files in directories mounted later take precedence over those mounted earlier. StackDir makes it possible, for example, to have a main game directory with common files and a mod directory overriding some of those files. Then we iterate over all files in the StackDir recursively (using the <tt class="docutils literal">Yes.deep</tt> argument) - including files in subdirectories. Path of each file in the VFS is printed. You should see in the output that the files' paths specify <tt class="docutils literal">stack</tt> as their parent since <tt class="docutils literal">main</tt> and <tt class="docutils literal">user</tt> are mounted to <tt class="docutils literal">stack</tt>. (Note that the paths will refer to <tt class="docutils literal">stack</tt> as parent even if iterating over <tt class="docutils literal">main</tt> and <tt class="docutils literal">user</tt> - as those are now mounted to <tt class="docutils literal">stack</tt>.) Then we get a VFSFile - D:GameVFS file object - from the <tt class="docutils literal">stack</tt> directory. This file does not exist yet (unless you created it). It will be created when we write to it. To obtain writing access, we get the VFSFileOutput struct using the VFSFile.output() method. VFSFileOutput provides basic output functionality. It uses reference counting to automatically close the file when you are done with it. Since we just want to write some simple text, we call its write() method directly. VFSFileOutput.write() writes a raw buffer of data to the file, similarly to fwrite() from the C standard library. Note that we're working on a file from a StackDir. StackDir decides where to actually write the data. In our case, the newest mounted directory is <tt class="docutils literal">user</tt>, which is also writable, so the data is written to <tt class="docutils literal">userdata/newfile.txt</tt>. In the end, we read the data back using the VFSFileInput class - input analog of VFSFileOutput - which we get with the VFSFile.input() method. We read with the VFSFileInput.read() method, which reads data to provided buffer, up to the buffer length. We determine how large buffer we need to read the entire file with the VFSFile.bytes() method. The buffer might also be larger than the file - read() reads as much data as available and returns the part of the buffer containing the read data. For more details about D:GameVFS API, see the <a class="reference external" href="http://defenestrate.eu/docs/dgamevfs">documentation</a>. </div> <div class="section" id="compiling"> <h2>Compiling</h2> We're going to use dub, which we installed at the beginning, to compile our project. Create a file called <tt class="docutils literal">dub.json</tt> with the following contents: <pre class="code json literal-block"> {
"name": "getting-started", "targetType": "executable", "sourceFiles": ["main.d"], "mainSourceFile": "main.d", "dependencies": { "dgamevfs": { "version" : "~>0.2.0" }, }, } </pre> This file tells dub that we're building an executable called <tt class="docutils literal">getting-started</tt> from a D source file <tt class="docutils literal">main.d</tt>, and that our project depends on D:GameVFS 0.5.0 or any newer, bugfix release of D:GameVFS 0.5 . DUB will automatically find and download the correct version of D:YAML when the project is built. Now run the following command in your project's directory: <pre class="literal-block"> dub build </pre> dub will automatically download D:GameVFS and compile it, and then then it will compile our program. This will generate an executable called <tt class="docutils literal">getting-started</tt> or <tt class="docutils literal">getting-started.exe</tt> in your directory. </div> </div> <div class="section" id="license"> <h1>License</h1> D:GameVFS is released under the terms of the <a class="reference external" href="http://www.boost.org/LICENSE10.txt">Boost Software License 1.0</a>. This license allows you to use the source code in your own projects, open source or proprietary, and to modify it to suit your needs. However, in source distributions, you have to preserve the license headers in the source code and the accompanying license file. Full text of the license can be found in file <tt class="docutils literal">LICENSE10.txt</tt> and is also displayed here: <pre class="literal-block"> Boost Software License - Version 1.0 - August 17th, 2003 Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following: The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. </pre> </div> <div class="section" id="credits"> <h1>Credits</h1> D:GameVFS was created by Ferdinand Majerech aka Kiith-Sa kiithsacmp[AT]gmail.com . The API was inspired the VFS API of the <a class="reference external" href="http://www.dsource.org/projects/tango/">Tango library</a>. D:GameVFS was created using Vim and DMD on Debian, Ubuntu and Linux Mint as a VFS library in the <a class="reference external" href="http://www.d-programming-language.org">D programming language</a>. </div> </div> </body> </html>

0.2.0	2014-Aug-07
~master	2015-Feb-21

dgamevfs ~master

Explanation of the code