doc: move examples to godoc

Author: blang

README.md

@@ -16,22 +16,40 @@ import github.com/blang/vfs
 
 ```go
 // Create a vfs accessing the filesystem of the underlying OS
-fs := vfs.OS()
-fs.Mkdir("/tmp", 0777)
+var osfs vfs.Filesystem = vfs.OS()
+osfs.Mkdir("/tmp", 0777)
 
 // Make the filesystem read-only:
-fs = vfs.ReadOnly(fs) // Simply wrap filesystems to change its behaviour
+osfs = vfs.ReadOnly(osfs) // Simply wrap filesystems to change its behaviour
 
 // os.O_CREATE will fail and return vfs.ErrReadOnly
 // os.O_RDWR is supported but Write(..) on the file is disabled
-f, _ := fs.OpenFile("/tmp/example.txt", os.O_RDWR, 0)
+f, _ := osfs.OpenFile("/tmp/example.txt", os.O_RDWR, 0)
 
 // Return vfs.ErrReadOnly
 _, err := f.Write([]byte("Write on readonly fs?"))
+if err != nil {
+    fmt.Errorf("Filesystem is read only!\n")
+}
 
 // Create a fully writable filesystem in memory
-fs := memfs.Create()
-fs.Mkdir("/root")
+mfs := memfs.Create()
+mfs.Mkdir("/root", 0777)
+
+// Create a vfs supporting mounts
+// The root fs is accessing the filesystem of the underlying OS
+fs := mountfs.Create(osfs)
+
+// Mount a memfs inside /memfs
+// /memfs may not exist
+fs.Mount(mfs, "/memfs")
+
+// This will create /testdir inside the memfs
+fs.Mkdir("/memfs/testdir", 0777)
+
+// This would create /tmp/testdir inside your OS fs
+// But the rootfs `osfs` is read-only
+fs.Mkdir("/tmp/testdir", 0777)
 ```
 
 Check detailed examples below. Also check the [GoDocs](http://godoc.org/github.com/blang/vfs).
@@ -46,19 +64,14 @@ Why should I use this lib?
 - Compose/Wrap Filesystems `ReadOnly(OS())` and write simple Wrappers
 - Many features, see [GoDocs](http://godoc.org/github.com/blang/vfs) and examples below
 
-Example
------
-
-Have a look at full examples in [examples/](examples/)
-
-Features
+Features and Examples
 -----
 
-- OS Filesystem support
-- ReadOnly Wrapper 
-- DummyFS for quick mocking
-- MemFS full in-memory filesystem
-- MountFS - support mounts across filesystems
+- [OS Filesystem support](http://godoc.org/github.com/blang/vfs#example-OsFS)
+- [ReadOnly Wrapper](http://godoc.org/github.com/blang/vfs#example-RoFS)
+- [DummyFS for quick mocking](http://godoc.org/github.com/blang/vfs#example-DummyFS)
+- [MemFS - full in-memory filesystem](http://godoc.org/github.com/blang/vfs/memfs#example-MemFS)
+- [MountFS - support mounts across filesystems](http://godoc.org/github.com/blang/vfs/mountfs#example-MountFS)
 
 Current state: ALPHA
 -----

example_dummy_test.go

@@ -0,0 +1,41 @@
+package vfs_test
+
+import (
+	"errors"
+	"fmt"
+	"os"
+
+	"github.com/blang/vfs"
+)
+
+type myFS struct {
+	vfs.Filesystem // Embed the Filesystem interface and fill it with vfs.Dummy on creation
+}
+
+func MyFS() *myFS {
+	return &myFS{
+		vfs.Dummy(errors.New("Not implemented yet!")),
+	}
+}
+
+func (fs myFS) Mkdir(name string, perm os.FileMode) error {
+	// Create a directory
+	// ...
+	return nil
+}
+
+func ExampleDummyFS() {
+	// Simply bootstrap your filesystem
+	var fs vfs.Filesystem = MyFS()
+
+	// Your mkdir implementation
+	fs.Mkdir("/tmp", 0777)
+
+	// All necessary methods like OpenFile (therefor Create) are stubbed
+	// and return the dummys error
+	_, err := vfs.Create(fs, "/tmp/vfs/example.txt")
+	if err != nil {
+		fmt.Printf("Error will be: Not implemented yet!\n")
+	}
+
+}

example_os_test.go

@@ -0,0 +1,28 @@
+package vfs_test
+
+import (
+	"fmt"
+
+	"github.com/blang/vfs"
+)
+
+func ExampleOsFS() {
+
+	// Create a vfs accessing the filesystem of the underlying OS
+	osFS := vfs.OS()
+	err := osFS.Mkdir("/tmp/vfs_example", 0777)
+	if err != nil {
+		fmt.Printf("Error creating directory: %s\n", err)
+	}
+
+	// Convenience method
+	f, err := vfs.Create(osFS, "/tmp/vfs_example/example.txt")
+	// f, err := osFS.OpenFile("/tmp/vfs/example.txt", os.O_CREATE|os.O_RDWR, 0666)
+	if err != nil {
+		fmt.Printf("Could not create file: %s\n", err)
+	}
+	defer f.Close()
+	if _, err := f.Write([]byte("VFS working on your filesystem")); err != nil {
+		fmt.Printf("Error writing to file: %s\n", err)
+	}
+}

examples/example_wrapping.go example_readonly_test.go

@@ -1,34 +1,39 @@
-package examples
+package vfs_test
 
 import (
+	"fmt"
 	"os"
 
 	"github.com/blang/vfs"
 )
 
 // Every vfs.Filesystem could be easily wrapped
-func ExampleReadOnlyOS() {
+func ExampleRoFS() {
 	// Create a readonly vfs accessing the filesystem of the underlying OS
 	roFS := vfs.ReadOnly(vfs.OS())
 
 	// Mkdir is disabled on ReadOnly vfs, will return vfs.ErrReadOnly
 	// See vfs.ReadOnly for all disabled operations
-	err := roFS.Mkdir("/tmp/vfs", 0777)
+	err := roFS.Mkdir("/tmp/vfs_example", 0777)
 	if err != nil {
-		fatal("Error creating directory: %s\n", err)
+		fmt.Printf("Error creating directory: %s\n", err)
+		return
 	}
 
 	// OpenFile is controlled to support read-only functionality. os.O_CREATE or os.O_APPEND will fail.
 	// Flags like os.O_RDWR are supported but the returned file is protected e.g. from Write(..).
-	f, err := roFS.OpenFile("/tmp/vfs/example.txt", os.O_RDWR, 0)
+	f, err := roFS.OpenFile("/tmp/vfs_example/example.txt", os.O_RDWR, 0)
 	if err != nil {
-		fatal("Could not create file: %s\n", err)
+		fmt.Printf("Could not create file: %s\n", err)
+		return
+
 	}
 	defer f.Close()
 
 	// Will fail and return vfs.ErrReadOnly
 	_, err = f.Write([]byte("VFS working on your filesystem"))
 	if err != nil {
-		fatal("Could not write file on read only filesystem: %s", err)
+		fmt.Printf("Could not write file on read only filesystem: %s", err)
+		return
 	}
 }

example_test.go

@@ -0,0 +1,47 @@
+package vfs_test
+
+import (
+	"fmt"
+	"github.com/blang/vfs"
+	"github.com/blang/vfs/memfs"
+	"github.com/blang/vfs/mountfs"
+	"os"
+)
+
+func Example() {
+	// Create a vfs accessing the filesystem of the underlying OS
+	var osfs vfs.Filesystem = vfs.OS()
+	osfs.Mkdir("/tmp", 0777)
+
+	// Make the filesystem read-only:
+	osfs = vfs.ReadOnly(osfs) // Simply wrap filesystems to change its behaviour
+
+	// os.O_CREATE will fail and return vfs.ErrReadOnly
+	// os.O_RDWR is supported but Write(..) on the file is disabled
+	f, _ := osfs.OpenFile("/tmp/example.txt", os.O_RDWR, 0)
+
+	// Return vfs.ErrReadOnly
+	_, err := f.Write([]byte("Write on readonly fs?"))
+	if err != nil {
+		fmt.Errorf("Filesystem is read only!\n")
+	}
+
+	// Create a fully writable filesystem in memory
+	mfs := memfs.Create()
+	mfs.Mkdir("/root", 0777)
+
+	// Create a vfs supporting mounts
+	// The root fs is accessing the filesystem of the underlying OS
+	fs := mountfs.Create(osfs)
+
+	// Mount a memfs inside /memfs
+	// /memfs may not exist
+	fs.Mount(mfs, "/memfs")
+
+	// This will create /testdir inside the memfs
+	fs.Mkdir("/memfs/testdir", 0777)
+
+	// This would create /tmp/testdir inside your OS fs
+	// But the rootfs `osfs` is read-only
+	fs.Mkdir("/tmp/testdir", 0777)
+}

examples/example_mywrapper.go example_wrapping_test.go

@@ -1,7 +1,8 @@
-package examples
+package vfs_test
 
 import (
 	"errors"
+	"fmt"
 	"os"
 
 	"github.com/blang/vfs"
@@ -11,7 +12,7 @@ type noNewDirs struct {
 	vfs.Filesystem
 }
 
-func NoNewDirs(fs vfs.Filesystem) vfs.Filesystem {
+func NoNewDirs(fs vfs.Filesystem) *noNewDirs {
 	return &noNewDirs{fs}
 }
 
@@ -20,13 +21,13 @@ func (fs *noNewDirs) Mkdir(name string, perm os.FileMode) error {
 	return errors.New("Mkdir disabled!")
 }
 
-func ExampleMyWrapper() {
+func ExampleOsFS_myWrapper() {
 
 	// Disable Mkdirs on the OS Filesystem
 	var fs vfs.Filesystem = NoNewDirs(vfs.OS())
 
 	err := fs.Mkdir("/tmp", 0777)
 	if err != nil {
-		fatal("Mkdir disabled!")
+		fmt.Printf("Mkdir disabled!\n")
 	}
 }

examples/example_myfs.go

@@ -1,6 +1,8 @@
-package examples
+package memfs_test
 
-import "github.com/blang/vfs/memfs"
+import (
+	"github.com/blang/vfs/memfs"
+)
 
 func ExampleMemFS() {
 	// Create a fully writable filesystem in memory

examples/example_os.go

@@ -1,4 +1,4 @@
-package examples
+package mountfs_test
 
 import (
 	"github.com/blang/vfs"
@@ -11,7 +11,8 @@ func ExampleMountFS() {
 	// The root fs is accessing the filesystem of the underlying OS
 	fs := mountfs.Create(vfs.OS())
 
-	// Mount a memfs inside
+	// Mount a memfs inside /memfs
+	// /memfs may not exist
 	fs.Mount(memfs.Create(), "/memfs")
 
 	// This will create /testdir inside the memfs