Merge pull request #1 from atomicgo/feat/implement-ansi

.github/settings.yml

@@ -4,10 +4,10 @@ repository:
   # See https://developer.github.com/v3/repos/#edit for all available settings.
 
   # A short description of the repository that will show up on GitHub
-  description: 🔹 Golang module
+  description: 🔹 Golang module to move the terminal cursor in any direction on every operating system.
 
   # A comma-separated list of topics to set on the repository
-  topics: atomicgo, go, golang, golang-library
+  topics: atomicgo, go, golang, golang-library, terminal, cursor, tui
 
   # Either `true` to make the repository private, or `false` to make it public.
   #  private: false

.gitignore

@@ -28,3 +28,4 @@ gen
 ### macOS
 # General
 .DS_Store
+experimenting

README.md

@@ -1,25 +1,25 @@
-<h1 align="center">AtomicGo | template</h1>
+<h1 align="center">AtomicGo | cursor</h1>
 
 <p align="center">
 
-<a href="https://github.com/atomicgo/template/releases">
-<img src="https://img.shields.io/github/v/release/atomicgo/template?style=flat-square" alt="Latest Release">
+<a href="https://github.com/atomicgo/cursor/releases">
+<img src="https://img.shields.io/github/v/release/atomicgo/cursor?style=flat-square" alt="Latest Release">
 </a>
 
-<a href="https://codecov.io/gh/atomicgo/template" target="_blank">
-<img src="https://img.shields.io/github/workflow/status/atomicgo/template/Go?label=tests&style=flat-square" alt="Tests">
+<a href="https://codecov.io/gh/atomicgo/cursor" target="_blank">
+<img src="https://img.shields.io/github/workflow/status/atomicgo/cursor/Go?label=tests&style=flat-square" alt="Tests">
 </a>
 
-<a href="https://codecov.io/gh/atomicgo/template" target="_blank">
-<img src="https://img.shields.io/codecov/c/gh/atomicgo/template?color=magenta&logo=codecov&style=flat-square" alt="Coverage">
+<a href="https://codecov.io/gh/atomicgo/cursor" target="_blank">
+<img src="https://img.shields.io/codecov/c/gh/atomicgo/cursor?color=magenta&logo=codecov&style=flat-square" alt="Coverage">
 </a>
 
-<a href="https://codecov.io/gh/atomicgo/template">
-<!-- unittestcount:start --><img src="https://img.shields.io/badge/Unit_Tests-1-magenta?style=flat-square" alt="Unit test count"><!-- unittestcount:end -->
+<a href="https://codecov.io/gh/atomicgo/cursor">
+<!-- unittestcount:start --><img src="https://img.shields.io/badge/Unit_Tests-2-magenta?style=flat-square" alt="Unit test count"><!-- unittestcount:end -->
 </a>
 
-<a href="https://github.com/atomicgo/template/issues">
-<img src="https://img.shields.io/github/issues/atomicgo/template.svg?style=flat-square" alt="Issues">
+<a href="https://github.com/atomicgo/cursor/issues">
+<img src="https://img.shields.io/github/issues/atomicgo/cursor.svg?style=flat-square" alt="Issues">
 </a>
 
 <a href="https://opensource.org/licenses/MIT" target="_blank">
@@ -33,7 +33,7 @@
 <p align="center">
 <strong><a href="#install">Get The Module</a></strong>
 |
-<strong><a href="https://pkg.go.dev/github.com/atomicgo/template" target="_blank">Documentation</a></strong>
+<strong><a href="https://pkg.go.dev/github.com/atomicgo/cursor" target="_blank">Documentation</a></strong>
 |
 <strong><a href="https://github.com/atomicgo/atomicgo/blob/main/CONTRIBUTING.md" target="_blank">Contributing</a></strong>
 |
@@ -48,33 +48,140 @@
 
 ## Description
 
-Package template is used to generate new AtomicGo repositories.
+Package cursor contains cross-platform methods to move the terminal cursor in
+different directions. This package can be used to create interactive CLI tools
+and games, live charts, algorithm visualizations and other updatable output of
+any kind.
 
-Write the description of the module here. You can use **markdown**! This
-description should clearly explain what the package does.
-
-Example description: https://golang.org/src/encoding/gob/doc.go
+Special thanks to github.com/k0kubun/go-ansi which this project is based on.
 
 ## Install
 
 ```console
 # Execute this command inside your project
-go get -u github.com/atomicgo/template
+go get -u github.com/atomicgo/cursor
 ```
 
 ```go
 // Add this to your imports
-import "github.com/atomicgo/template"
+import "github.com/atomicgo/cursor"
 ```
 
 ## Usage
 
-#### func  HelloWorld
+#### func  Bottom
+
+```go
+func Bottom()
+```
+Bottom moves the cursor to the bottom of the terminal. This is done by
+calculating how many lines were moved by Up and Down.
+
+#### func  ClearLine
+
+```go
+func ClearLine()
+```
+ClearLine clears the current line and moves the cursor to it's start position.
+
+#### func  Down
+
+```go
+func Down(n int)
+```
+Down moves the cursor n lines down relative to the current position.
+
+#### func  DownAndClear
+
+```go
+func DownAndClear(n int)
+```
+DownAndClear moves the cursor down by n lines, then clears the line.
+
+#### func  Hide
+
+```go
+func Hide()
+```
+Hide the cursor. Don't forget to show the cursor at least at the end of your
+application with Show. Otherwise the user might have a terminal with a
+permanently hidden cursor, until he reopens the terminal.
+
+#### func  HorizontalAbsolute
+
+```go
+func HorizontalAbsolute(n int)
+```
+HorizontalAbsolute moves the cursor to n horizontally. The position n is
+absolute to the start of the line.
+
+#### func  Left
+
+```go
+func Left(n int)
+```
+Left moves the cursor n characters to the left relative to the current position.
+
+#### func  Move
+
+```go
+func Move(x, y int)
+```
+Move moves the cursor relative by x and y.
+
+#### func  Right
+
+```go
+func Right(n int)
+```
+Right moves the cursor n characters to the right relative to the current
+position.
+
+#### func  Show
+
+```go
+func Show()
+```
+Show the cursor if it was hidden previously. Don't forget to show the cursor at
+least at the end of your application. Otherwise the user might have a terminal
+with a permanently hidden cursor, until he reopens the terminal.
+
+#### func  StartOfLine
+
+```go
+func StartOfLine()
+```
+StartOfLine moves the cursor to the start of the current line.
+
+#### func  StartOfLineDown
+
+```go
+func StartOfLineDown(n int)
+```
+StartOfLineDown moves the cursor down by n lines, then moves to cursor to the
+start of the line.
+
+#### func  StartOfLineUp
+
+```go
+func StartOfLineUp(n int)
+```
+StartOfLineUp moves the cursor up by n lines, then moves to cursor to the start
+of the line.
+
+#### func  Up
+
+```go
+func Up(n int)
+```
+Up moves the cursor n lines up relative to the current position.
+
+#### func  UpAndClear
 
 ```go
-func HelloWorld() string
+func UpAndClear(n int)
 ```
-HelloWorld returns `Hello, World!`.
+UpAndClear moves the cursor up by n lines, then clears the line.
 
 ---
 

cursor.go

@@ -0,0 +1,59 @@
+// +build !windows
+
+package cursor
+
+import (
+	"fmt"
+)
+
+// Up moves the cursor n lines up relative to the current position.
+func Up(n int) {
+	fmt.Printf("\x1b[%dA", n)
+	height += n
+}
+
+// Down moves the cursor n lines down relative to the current position.
+func Down(n int) {
+	fmt.Printf("\x1b[%dB", n)
+	if height-n < 0 {
+		height = 0
+	} else {
+		height -= n
+	}
+}
+
+// Right moves the cursor n characters to the right relative to the current position.
+func Right(n int) {
+	fmt.Printf("\x1b[%dC", n)
+}
+
+// Left moves the cursor n characters to the left relative to the current position.
+func Left(n int) {
+	fmt.Printf("\x1b[%dD", n)
+}
+
+// HorizontalAbsolute moves the cursor to n horizontally.
+// The position n is absolute to the start of the line.
+func HorizontalAbsolute(n int) {
+	n += 1 // Moves the line to the character after n
+	fmt.Printf("\x1b[%dG", n)
+}
+
+// Show the cursor if it was hidden previously.
+// Don't forget to show the cursor at least at the end of your application.
+// Otherwise the user might have a terminal with a permanently hidden cursor, until he reopens the terminal.
+func Show() {
+	fmt.Print("\x1b[?25h")
+}
+
+// Hide the cursor.
+// Don't forget to show the cursor at least at the end of your application with Show.
+// Otherwise the user might have a terminal with a permanently hidden cursor, until he reopens the terminal.
+func Hide() {
+	fmt.Print("\x1b[?25l")
+}
+
+// ClearLine clears the current line and moves the cursor to it's start position.
+func ClearLine() {
+	fmt.Print("\x1b[2K")
+}

cursor_test.go

@@ -0,0 +1,27 @@
+package cursor
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestHeightChanges(t *testing.T) {
+	for i := 0; i < 4; i++ {
+		fmt.Println()
+	}
+	Up(3)
+	if height != 3 {
+		t.Errorf("height should be 3 but is %d", height)
+	}
+	Down(3)
+	if height != 0 {
+		t.Errorf("height should be 0 but is %d", height)
+	}
+}
+
+func TestHeightCannotBeNegative(t *testing.T) {
+	Down(10)
+	if height < 0 {
+		t.Errorf("height is negative: %d", height)
+	}
+}