jim

README

Jim

Jim is a task runner, similiar to https://github.com/markbates/grift.

Requirements

• Go 1.13+
• Modules

Installation

$ go get github.com/markbates/jim/cmd/jim

---

Usage

To create a new task that you can run with jim. You need to create a package level function with the following API in your module:

func <name>(ctx context.Context, args []string) error {
	return nil
}

You can place these functions anywhere in your application in any package. You don't need to follow any naming conventions or use any special build tags. Your function need only take a context#Context and a slice of string, and return an error.

See the ./examples/ref application for the full code.

.
├── db
│   ├── seed
│   │   └── users.go
│   └── seed.go
├── go.mod
├── go.sum
├── ref.go
└── task
    └── task.go

3 directories, 6 files

The go.mod file:

module ref

go 1.13

Example task ref/db/seed/users.go

package seed

import (
	"context"
	"fmt"
)

// Users puts all of the users into all of the databases
func Users(ctx context.Context, args []string) error {
	fmt.Println("loading users", args)
	return nil
}

Running a Task via CLI

To run the above mentioned task we can use the jim command:

$ jim db/seed:Users 1 2 3 4

loading users [1 2 3 4]

Let's break down the db/seed:Users bit, shall we? The last part, Users is the name of the function that will be run. This MUST match capitalization.

The db/seed part is converted to the package <module path>/db/seed which, hopefully, contains a Users function that matches the correct API.

Running a Task via API

To run your task via the API in your application, give it a context.Context, some arguments, and you're good to go. :)

Getting Task Help

The jim -h flag, followed by the task will print the GoDoc for that function.

$ jim -h db/seed:Users

package seed // import "ref/db/seed"

func Users(ctx context.Context, args []string) error
    Users puts all of the users into all of the databases

Listing Available Tasks

$ jim list

ref/db/seed:Users
ref/db:Seed
ref/task:Another
ref/task:Something

Documentation

Index

• Variables
• func Help(t *Task) (string, error)
• func Jim(ctx context.Context, args []string) error
• func Run(ctx context.Context, t *Task) error
• func Stderr(ctx context.Context) io.Writer
• func Stdin(ctx context.Context) io.Reader
• func Stdout(ctx context.Context) io.Writer
• type Erry
• type Iny
• type Outy
• type Task
  • func List(root string) ([]*Task, error)
  • func New(args []string) (*Task, error)
  • func (t Task) String() string

Variables

var Version = ""

Version of jim

Functions

func Help

func Help(t *Task) (string, error)

func Jim

func Jim(ctx context.Context, args []string) error

func Run

func Run(ctx context.Context, t *Task) error

func Stderr

func Stderr(ctx context.Context) io.Writer

Stderr retuns an io.Writer representing the stderr. If the ctx implements Erry that is returned. If the ctx.Value("stderr") is present, and an io.Writer, that is returned. If no other io.Writer is found, then os.Stderr is returned.

func Stdin

func Stdin(ctx context.Context) io.Reader

Stdin retuns an io.Reader representing the stdin. If the ctx implements Iny that is returned. If the ctx.Value("stdin") is present, and an io.Reader, that is returned. If no other io.Reader is found, then os.Stdin is returned.

func Stdout

func Stdout(ctx context.Context) io.Writer

Stdout retuns an io.Writer representing the stdout. If the ctx implements Outy that is returned. If the ctx.Value("stdout") is present, and an io.Writer, that is returned. If no other io.Writer is found, then os.Stdout is returned.

Types

type Erry

type Erry interface {
	Stderr() io.Writer
}

Erry returns an io.Writer that represents the stderr

type Iny

type Iny interface {
	Stdin() io.Reader
}

Iny returns an io.Reader that represents the stdin

type Outy

type Outy interface {
	Stdout() io.Writer
}

Outy returns an io.Writer that represents the stdout

type Task

type Task struct {
	here.Info
	BuildArgs []string // -tags foo -v
	Args      []string
	Pkg       string // github.com/foo/bar
	Sel       string // bar
	Name      string // Something
}

func List

func List(root string) ([]*Task, error)

List parses the AST at, and below, the given root looking for Jim tasks.

func New

func New(args []string) (*Task, error)

func (Task) String

func (t Task) String() string