fs

README

fs, a file reader

This package implements a file system 'browser' for use in a web server. By specifying paths in the file system, it returns directories, files and part of files (specific types of files) that correspond to that path. The particularity of this package is that it allows navigation into either conventional or versioned file systems (such as Subversion or Git), and into data files (only OGDL at the moment). Use of file extensions is optional (if the file name is unique).

For now this is a read-only implementation. The content of a path is returned if found, but the file system cannot be modified.

When the path points to a directory that contains an index.* file it returnes this file along with the directory list. Presence of several index.* files is not supported except in special cases: index.nolist(= do not return directory list).

Main API

The two main functions of this package are New and Get.

fs := fs.New("/dir")
fe := fs.Get("path")

Implementation details

FileSystem

A file system is opened by giving a root location to New():

include "github.com/rveen/golib/fs"

fs := fs.New("/dir")

where fs is a FileSystem interface. Its root is per definition an ordinary directory.

Each FileSystem implements these functions:

type FileSystem interface {
    Root() string
    Info(path, rev string) (*types.FileEntry, error)
    Dir(path, rev string) ([]os.FileInfo, error)
    File(path, rev string) ([]byte, error)
    Revisions(path, rev string) (*ogdl.Graph, error)
    Type() string
    Get(path, rev string) (*types.FileEntry, error)
}

FileEntry

FileEntry is an interface that extends the standard os.FileInfo. It represents either a directory or a file.

type FileEntry struct {
    Name     string
    Size     int64
    Content  []byte
    Template *ogdl.Graph
    Data     *ogdl.Graph
    Info     *ogdl.Graph
    Typ      string
    Mime     string
    Time     time.Time
    Param    map[string]string
    Mode     os.FileMode
    Dir      []os.FileInfo
}

Documentation

Overview

This package implements a file system 'browser' for use in a web server. By specifying paths in the file system, it returns directories, files and part of files (specific types of files) that correspond to that path. The particularity of this package is that it allows navigation into either conventional or versioned file systems (Subversion at the moment), data files (OGDL at the moment) and markdown document.

Use of file extensions is optional (if the file name is unique).

For now this is a read-only implementation. The content of a path is returned if found, but the file system cannot be modified.

When the path points to a directory that contains an index.* file it returnes this file along with the directory list. Presence of several index.* files is not supported except in special cases: index.nolist(= do not return directory list).

Paths

Paths are a sequence of elements separated by slashes, following the Unix / Linux notation. Two special cases exist:

- @token is interpreted as a release or commit identifier, and removed from the path. Instead a "revision" parameter is added to fe.Param().

- If an element is not found in a directory but the directory contains a _token entry, that one is followed. A parameter is attached to fe.Params() with the token as name and the unfound element as value.

Example

The two main functions of this package are New and Get.

ff := fs.New("/dir")
fe, err := ff.Get("file")

Get returns a FileEntry object that implements the os.FileInfo interface and holds also the content (directoty list, file).

TODO: for what os.FileInfo ??

Templates

File extensions that are configured as OGDL templates are preprocessed as such, that is, they are parsed and converted into an OGDL object accessible through fe.Data. TODO: should this be done outside of this package?? (caching is a reason to do it here)

Navigating data files

Navigation within an OGDL file is handled over to the ogdl package (ogdl.Get).

Navigating documents

Markdown document navigation is handled by the document package (document.Get).

Database navigation

Not supported (done through templates).

Relation between path and template

Is this a fixed relation or can we specify a template for a path in an elegant way ? Or is it better to just write a template with the query or path inside ? Are we mixing functions?

Revision list

Obtained by ending the path with @.

Index

• func New(root string) *fileSystem
• type FileSystem

Functions

func New

func New(root string) *fileSystem

New creates the FileSystem object needed to operate with a file system. A path to an ordinary directory should be given.

Types

type FileSystem

type FileSystem interface {
	Root() string
	Info(path, rev string) (*types.FileEntry, error)
	Dir(path, rev string) ([]os.FileInfo, error)
	File(path, rev string) ([]byte, error)
	Revisions(path, rev string) (*ogdl.Graph, error)
	Type() string
	Get(path, rev string) (*types.FileEntry, error)
	GetRaw(path, rev string) (*types.FileEntry, error)
}