argf

README

argf

This is a small Go library that reads lines of text from either a file or files specified in os.Args, or, if none are given, from stdin. It's similar to Ruby's ARGF or Perl's diamond operator.

This is mainly intended for tiny script-like CLI tools. Note that multiple goroutines should not call its functions concurrently.

Here's how to write a simple version of cat using argf:

package main

import (
  "fmt"
  "github.com/cespare/argf"
  "os"
)

func main() {
  for argf.Scan() {
    fmt.Println(argf.String())
  }
  if err := argf.Error(); err != nil {
    fmt.Println(err)
    os.Exit(1)
  }
}

Documentation

Overview

Package argf provides a simple way of reading line-by-line from either files given as command-line arguments or, if none were given, from stdin.

The interface resembles bufio.Scanner.

This package provides a convenient way of handling input for command-line utilities. For instance, here is a simple implementation of the Unix utility 'cat':

for argf.Scan() {
  fmt.Println(argf.String())
}
if err := argf.Error(); err != nil {
  fmt.Println(err)
  os.Exit(1)
}

If flags are required, you can call Init(flag.Args()) after flag parsing but before any other argf calls to initialize argf with the non-flag arguments given in the command-line (presumably filenames).

Multiple goroutines should not call any of the functions in argf concurrently.

Index

• func Bytes() []byte
• func Error() error
• func Init(args []string)
• func Scan() bool
• func String() string

Functions

func Bytes

func Bytes() []byte

Bytes returns the current line as a []byte without the trailing newline. It panics unless preceeded by a call to Scan that returned true. Bytes may be called multiple times consecutively but returns the same line each time.

func Error

func Error() error

Error returns the error that caused Scan to return false, unless it was an io.EOF, in which case Error returns nil.

func Init

func Init(args []string)

Init initializes argf's state using some filename arguments. If args is empty, argf uses stdin instead of files. Without calling Init(), argf initializes itself the first time Scan is called, using os.Args[1:] (ignoring the program name).

func Scan

func Scan() bool

Scan reads the next line from either os.Stdin or the current file in os.Args, as described in the package documentation. If the current file has been exhausted, Scan attempts to open the next file in os.Args, if there is one. If there are no more lines to be read from os.Stdin or any files, or if Scan encounters an error, false is returned. Otherwise, true is returned and the line is available to be accessed by String or Bytes.

func String

func String() string

String returns the current line as a string without the trailing newline. It panics unless preceeded by a call to Scan that returned true. String may be called multiple times consecutively but returns the same line each time.