godo

README

GoDo

An entirely unnecessary go SDK for todo.txt add-ons.

Motivation

Making add-ons for todo.txt is fairly easy. It has a fairly simple structured text format and only a few files and settings. Whilst that means you don't really need an SDK for it, there is fun and good practice to be had in making one.

Getting started

TODO

Documentation

Index

• Constants
• func CLI(cli interface{}, name, description string, options ...kong.Option) *kong.Context
• type Config
  • func NewConfig(env Env) *Config
  • func (c *Config) AddTask(t *Task) (err error)
  • func (c *Config) Delete(ids []int, archiveFile bool) (err error)
  • func (c *Config) DeleteTasks(tasks []*Task, archiveFile bool) (err error)
  • func (c *Config) DoTask(task *Task, archive bool) error
  • func (c *Config) DoTasks(tasks []*Task, archive bool) error
  • func (c *Config) DoneTasks() (tasks []*Task, err error)
  • func (c *Config) Donetxt() (*os.File, error)
  • func (c *Config) Tasks() (tasks []*Task, err error)
  • func (c *Config) Todotxt() (*os.File, error)
  • func (c *Config) UpdateTask(t *Task) (err error)
  • func (c *Config) UpdateTasks(tasks []*Task) (err error)
• type Env
• type Task
  • func Parse(raw string) (*Task, error)
  • func SortTasks(tasks []*Task) []*Task
  • func (t *Task) Description() string
  • func (t *Task) GetTagValue(tag string) (string, bool)
  • func (t *Task) MarkDone()
  • func (t *Task) Position() int
  • func (t *Task) Render(showPos, color bool) string
  • func (t *Task) String() string
  • func (t *Task) Style() termenv.Style
  • func (t *Task) UpdateDescription(description string)
  • func (t *Task) UpdateTag(key, newValue string) bool

Constants

const (
	// DateFormat The format used for dates on disk
	DateFormat = "2006-01-02"
)

Functions

func CLI

func CLI(cli interface{}, name, description string, options ...kong.Option) *kong.Context

CLI calls kong.Parse creating a *kong.Context. It handles the usage sub command, printing out the usage message and exiting if found. Example usage:

 var CLI struct {
	 godo.Env
	 TaskNumbers bool `default:"true" help:"show tasks position in the file" short:"i"`
 }

 func main() {
	 _ = godo.CLI(&CLI, "did", "See tasks in the archive file")
	 cfg := godo.NewConfig(CLI.Env)
  ...
 }

Types

type Config

type Config struct {
	Env
}

Config allows for interaction with the users TODOTXT files. Use NewConfig to create TODO Allow configuration of preserving priority on task completion

func NewConfig

func NewConfig(env Env) *Config

NewConfig creates a new Config with the provided env options

func (*Config) AddTask

func (c *Config) AddTask(t *Task) (err error)

AddTask appends a Task to the todotxt, creating the file in Env.TODODir if it does not exist. Ignores any position value that might exist in t

func (*Config) Delete

func (c *Config) Delete(ids []int, archiveFile bool) (err error)

Delete remove tasks by position from either the todotxt or, if archiveFile is true, from the donetxt

func (*Config) DeleteTasks

func (c *Config) DeleteTasks(tasks []*Task, archiveFile bool) (err error)

DeleteTasks removes the given tasks from either the todotxt or, if archiveFile is true, from the donetxt

func (*Config) DoTask

func (c *Config) DoTask(task *Task, archive bool) error

func (*Config) DoTasks

func (c *Config) DoTasks(tasks []*Task, archive bool) error

func (*Config) DoneTasks

func (c *Config) DoneTasks() (tasks []*Task, err error)

DoneTasks returns all tasks from the donetxt

func (*Config) Donetxt

func (c *Config) Donetxt() (*os.File, error)

Donetxt provides a file handle to the users done.txt or an error. It creates the file in Env.TODODir if it does not exist. It is the callers' responsibility to close the file after use

func (*Config) Tasks

func (c *Config) Tasks() (tasks []*Task, err error)

Tasks returns all tasks from the todotxt

func (*Config) Todotxt

func (c *Config) Todotxt() (*os.File, error)

Todotxt provides a file handle to the users todotxt file or an error. It creates the file in Env.TODODir if it does not exist. It is the callers' responsibility to close the file after use

func (*Config) UpdateTask

func (c *Config) UpdateTask(t *Task) (err error)

UpdateTask updates a task in position in the todotxt. Use UpdateTasks for efficient updates to multiple tasks. See UpdateTasks for more details

func (*Config) UpdateTasks

func (c *Config) UpdateTasks(tasks []*Task) (err error)

UpdateTasks updates each task in the provided array in place in the todotxt This function is atomic. It steams tasks out to a temporary file and moves replaces the todotxt at the end.

type Env

type Env struct {
	// PreserveLineNumbers leaves a blank line when a TODOTXT entry is deleted
	PreserveLineNumbers bool `env:"TODOTXT_PRESERVE_LINE_NUMBERS" hidden:"" default:"false"`
	// Verbose enables verbose log output
	Verbose bool `env:"TODOTXT_VERBOSE" hidden:"" default:"false"`
	// Plain disables color output
	Plain bool `env:"TODOTXT_PLAIN" hidden:"" default:"false"`
	// AutoArchive signifies completed todos should be moved to the archive file
	AutoArchive bool `env:"TODOTXT_AUTO_ARCHIVE" hidden:"" default:"false"`
	// Force disables confirmation messages
	Force bool `env:"TODOTXT_FORCE" hidden:"" default:"false"`
	// DateOnAdd means prepend the current date to a task when it's added
	DateOnAdd bool `env:"TODOTXT_DATE_ON_ADD" hidden:"" default:"false"`

	// Sh name of the todosh script, use in the usage message
	Sh string `env:"TODO_SH" hidden:""`
	// FullSh complete path to calling todosh script, use for invoking todosh
	FullSh string `env:"TODO_FULL_SH" hidden:""`
	// ConfigFile is the path to the users configuration file
	ConfigFile string `env:"TODOTXT_CFG_FILE" hidden:""`
	// TODODir is the directory containing the config file. Defaults to "./testdata/" for testing outside of the TODOTXT
	// runtime
	TODODir string `env:"TODO_DIR" hidden:"" default:"./testdata/" type:"existingdir"`
}

Env is a kong compatible struct that can be included in a CLI configuration to account for the environment variables provided by todotxt. Use the CLI function to handle construction and usage message printing when the "usage" command is passed.

Note: TODODir is set to "./testdata/" by default to aid in testing during development, but the todotxt CLI sets this variable

type Task

type Task struct {
	// The completion status of a Task. True if the task is marked as complete.
	Complete bool
	// The priority of the task. A to Z uppercase. Optional
	Priority string
	// The date the task was completed on. Format of DateFormat. Optional
	CompletionDate string
	// The date the task was created on. Format of DateFormat. Optional unless completion date is set
	CreationDate string
	// contains filtered or unexported fields
}

Task represents a single entry of a TODOTXT. The description part is not directly exposed. Use UpdateDescription and Description instead.

func Parse

func Parse(raw string) (*Task, error)

Parse marshals a TODOTXT string into a struct

func SortTasks

func SortTasks(tasks []*Task) []*Task

SortTasks provides a default sorting for a slice of tasks. Tasks with a priority will be at the start of the slice beginning with "A"s. Matching priority will sort on position. All tasks without a priority will follow, sorted by position.

func (*Task) Description

func (t *Task) Description() string

Description retrieves the currently set description as a string

func (*Task) GetTagValue

func (t *Task) GetTagValue(tag string) (string, bool)

GetTagValue returns a value of a tag and true if the tag is present in the description of a Task or an empty string false

func (*Task) MarkDone

func (t *Task) MarkDone()

MarkDone sets Complete to true and sets the CompletionDate to today's date, if it is not already set

func (*Task) Position

func (t *Task) Position() int

Position retrieves the current position of the task in the todotxt

func (*Task) Render

func (t *Task) Render(showPos, color bool) string

Render provides a default rendering including task number if showPos is true and colors if color is true

func (*Task) String

func (t *Task) String() string

String render the Task as a string as it would be represented in the TODODir

func (*Task) Style

func (t *Task) Style() termenv.Style

Style provides a termenv.Style that would be used to render this task

func (*Task) UpdateDescription

func (t *Task) UpdateDescription(description string)

UpdateDescription allows changes the description part of a Task

func (*Task) UpdateTag

func (t *Task) UpdateTag(key, newValue string) bool

UpdateTag updates the value of a tag in the description. Returns true if it was able to update the tag. False if not e.g. it was missing