caravel

README

Caravel

Utility library for Go

Introduction

Caravel is a general-purpose utility library for the Go programming language; it encompasses several aspects - from file system to networking, including zip archives and user settings.

Installation

The installation requires, as usual, go get:

go get github.com/giancosta86/caravel

Requirements

Caravel is for Go 1.5 and compatible versions.

Usage

First of all, import the library package into a source file:

import "github.com/giancosta86/caravel"

From now on, you can use the functions available in the caravel package.

Reference

The full GoDoc reference is available at this page.

Documentation

Overview

Package caravel is a general-purpose utility library for the Go programming language; it encompasses several aspects - from file system to networking, including zip archives and user settings.

Index

• func DirectoryExists(dirPath string) bool
• func ExtractZip(zipPath string, targetDir string) (err error)
• func ExtractZipSkipLevels(zipPath string, targetDir string, skippedLevels int) (err error)
• func FileExists(filePath string) bool
• func FormatFileName(fileName string) string
• func GetCommandOutputString(command *exec.Cmd) (outputString string, err error)
• func GetProcessOutputString(name string, arg ...string) (outputString string, err error)
• func GetUserDesktop() (desktopDir string, err error)
• func GetUserDirectory() (userDir string, err error)
• func GoInstall(relativePathInGoPath string) (programPath string, err error)
• func IsSecureURL(urlToCheck *url.URL) bool
• func RetrieveChunksFromURL(remoteURL *url.URL, outputWriter io.Writer, chunkSize int64, ...) (err error)
• func RetrieveFromURL(remoteURL *url.URL) (bytes []byte, err error)
• type RetrievalProgressCallback

Functions

func DirectoryExists

func DirectoryExists(dirPath string) bool

DirectoryExists returns true if "dirPath" exists and is a directory.

func ExtractZip

func ExtractZip(zipPath string, targetDir string) (err error)

ExtractZip extracts the zip file located at the given path to the given target directory, restoring the file-system permission bits for every entry.

Absolute entry paths in the zip file are not allowed.

The function returns nil on success, an error on failure.

func ExtractZipSkipLevels

func ExtractZipSkipLevels(zipPath string, targetDir string, skippedLevels int) (err error)

ExtractZipSkipLevels extracts the zip as ExtractZip does, but ignoring the first "skippedLevels" directory nodes in the tree. "skippedLevels" must be >= 0.

func FileExists

func FileExists(filePath string) bool

FileExists returns true if "filePath" exists and is a file.

func FormatFileName

func FormatFileName(fileName string) string

FormatFileName receives a file name and returns it with only letters, digits, '.', ' ' and '-', replacing every other rune with an underscore ('_'). Furthermore, each sequence of underscores is contracted into a single underscore, and trailing underscores are suppressed.

func GetCommandOutputString

func GetCommandOutputString(command *exec.Cmd) (outputString string, err error)

GetCommandOutputString runs the given command, returning its output as a string - or an error on failure.

func GetProcessOutputString

func GetProcessOutputString(name string, arg ...string) (outputString string, err error)

GetProcessOutputString runs the given program with the given arguments, returning its output as a string - or an error on failure.

func GetUserDesktop

func GetUserDesktop() (desktopDir string, err error)

GetUserDesktop returns the user's "Desktop" directory, or an error on failure.

func GetUserDirectory

func GetUserDirectory() (userDir string, err error)

GetUserDirectory returns the user's directory, or an error on failure. First it looks for a "HOME" environment variable; then it employs user.Current()

func GoInstall

func GoInstall(relativePathInGoPath string) (programPath string, err error)

GoInstall compiles and installs the given Go program - located at a relative path under GOPATH - into $GOPATH/bin by executing "go install".

Of course, the GOPATH environment variable must be set, and "go" must be accessible via the PATH environment variable.

It returns the path of the compiled program, or an error on failure.

func IsSecureURL

func IsSecureURL(urlToCheck *url.URL) bool

IsSecureURL returns true if the given url employs HTTPS.

func RetrieveChunksFromURL

func RetrieveChunksFromURL(
	remoteURL *url.URL,
	outputWriter io.Writer,
	chunkSize int64,
	progressCallback RetrievalProgressCallback) (err error)

RetrieveChunksFromURL reads the bytes located at the given remote URL as subsequent chunks having the passed size; whenever a chunk is retrieved, it is written to the given Writer, and "progressCallback" is called.

The function returns nil on success, an error on failure.

func RetrieveFromURL

func RetrieveFromURL(remoteURL *url.URL) (bytes []byte, err error)

RetrieveFromURL downloads and returns all the bytes from the given remote URL, returning an error on failure.

Types

type RetrievalProgressCallback

type RetrievalProgressCallback func(retrievedSize int64, totalSize int64)

RetrievalProgressCallback models a function receving 2 parameters: the number of bytes retrieved up to now and the total number of bytes to be retrieved.