gost

README

Gost

Filesystem abstraction layer for Golang, that works with Local filesystem and Amazon S3 with a unified API. You can even copy-paste files from different sources. FTP, Dropbox etc. will follow soon.

Quick Example

import "github.com/usmanhalalit/gost/s3"

// Initialize a filesystem
fs, err := s3.New(s3.Config{ your-aws-credentials })

// Read
note, err := fs.File("my-note.txt").ReadString()
//Write
err := fs.File("another-note.txt").WriteString("another note")

// Traverse naturally
movies := fs.Directory("movies")
files := movies.Files()
movies.File("Pirated-movie.mp4").Delete()

// Copy file from one source to another
localFile := lfs.File("photo.jpg")
s3Dir := fs.Directory("photos")
err := localFile.CopyTo(s3dir)

Initialize

Get the library:

go get github.com/usmanhalalit/gost

You just initialize the S3 and Local adapters differently, everything else in the API is same.

Amazon S3

import "github.com/usmanhalalit/gost/s3"

fs, err := s3.New(s3.Config{
	ID: "aws-id",
	Key: "aws-key",
	Region: "es-west-1",
	Bucket: "your-bucket",
})

Local

import "github.com/usmanhalalit/gost/local"

fs, err := local.New(local.Config{
	BasePath: "/home/user",
})

Read and Write

Read

Simple read, suitable for small files.

fileContent, err := fs.File("test.txt").ReadString()

Bytes read, compatible with io.Reader, so you can do buffered read.

b := make([]byte, 3)
n, err := fs.File("test.txt").Read(b)

Write

Simple write

fs.File("test.txt").WriteString("sample content")

Bytes write

n, err := file.Write(bytes)
// n == number of bytes written

Traversing

You can explore the filesystem like you in your desktop file explorer. File and directories are chained in a natural way.

dirs, err := fs.Directory("Parent").Directory("Child").Directories()
files, err := fs.Directory("Parent").Directory("Child").Files()

dirs, err := fs.Directory("Parent").Directory("Child").Files()

Listing

Get all files and loop through them

files, err := fs.Files()
for _, file := range files {
    fmt.Println(file.ReadString())
}

Get all directories and loop through them

dirs, err := fs.Directories()
for _, dir := range dirs {
    files := dir.Files()
    fmt.Println(files)
}

Get the directory which contains a file

dir := fs.File("test.txt").Directory()

Stat

Get file size and last modified timestamp:

stat, _ := fs.File("test.txt").Stat()
fmt.Println(stat.Size)
fmt.Println(stat.LastModified)

You can get stat of directories too, but it's not available on S3.

fs.Directory("Downloads").File("test.txt").GetPath()

Create and Delete

Delete a file and directory:

fs.File("test.txt").Delete()
// Delete an entire directory, beware please!
fs.Directory("Images").Delete()

Create a new directory:

fs.Directory("Images").Create()

To create a new file simply write something to it:

fs.File("non_existent_file").WriteString("")

Copy and Paste Between Different Sources

You can copy a file to any Directory, be it in in the same filesystem or not(local or S3)

localFile := lfs.File("photo.jpg")
s3Dir := s3fs.Directory("photos")
err := localFile.CopyTo(s3dir)

Fun, eh?

You can optionally provide a new filename too:

err := localFile.CopyTo(anotherDir, "copied_file.jpg")

Also there is a helper to copy file in the same Directory:

file.Copy("copied_file.jpg")

Custom Adapter

Yes, you can write one and it'll be appreciated if you contribute back. . gost.go file has all the interfaces defined. Basically you've to implement gost.File and gost.Directory interfaces. Check the local adapter to get an idea.

API Documentation

Please follow the Go Doc: https://godoc.org/github.com/usmanhalalit/gost

Also check the _test files here to get more idea about the usage.

---

You can follow me on Twitter 🙂

© Muhammad Usman. Licensed under MIT license.

Documentation

Overview

Filesystem abstraction layer for Golang, that works with Local file system and Amazon S3 with a unified API. You can even copy-paste files from different sources. FTP, Dropbox etc. will follow soon.

Full documentation: https://github.com/usmanhalalit/gost/blob/master/Readme.md

Index

• type Directory
• type File
• type FileInfo

Types

type Directory

type Directory interface {
	// Point to a file in directory
	File(path string) File
	// Get all files from the directory
	Files() ([]File, error)
	// Point to a directory in this directory
	Directory(path string) Directory
	// Get the the directory path
	GetPath() string
	// Delete the entire directory, no undo
	Delete() error
	// Check if directory exists
	Exists() bool
	// Create a directory
	Create() error
	// Get all directories in the directory
	Directories() ([]Directory, error)
	// Get directory metadata
	Stat() (FileInfo, error)
	// Helper to convert directory to a string, provide directory name
	fmt.Stringer
}

type File

type File interface {
	// Get all file content as string
	ReadString() (string, error)
	// Write string to the file
	WriteString(text string) error
	// Delete the file, no undo
	Delete() error
	// Check of file exists
	Exists() bool
	// Get file metadata
	Stat() (FileInfo, error)
	// Get the directory which contains the file
	Directory() Directory
	// Get the file path
	GetPath() string
	// Copy file to another directory
	CopyTo(dir Directory, newName ...string) error
	// Copy file to the current directory
	Copy(newName string) error
	// Read to file, write to file and close the file
	io.ReadWriteCloser
	// Helper to convert file to a string, provide file name
	fmt.Stringer
}

type FileInfo

type FileInfo struct {
	Size         int64
	LastModified time.Time
}