From ee5b4a43f1a402154211b8f02744d111887e06ff Mon Sep 17 00:00:00 2001 From: "kayos@tcp.direct" Date: Wed, 8 Dec 2021 20:05:05 -0800 Subject: [PATCH] Add: _example, Update: README.md --- README.md | 142 ++++++++++++++++++++++++++++++++++++----------- _example/go.mod | 7 +++ _example/go.sum | 8 +++ _example/main.go | 76 +++++++++++++++++++++++++ go.mod | 2 +- go.sum | 4 +- 6 files changed, 204 insertions(+), 35 deletions(-) create mode 100644 _example/go.mod create mode 100644 _example/go.sum create mode 100644 _example/main.go diff --git a/README.md b/README.md index 182a813..e125625 100644 --- a/README.md +++ b/README.md @@ -2,41 +2,114 @@ [![GoDoc](https://godoc.org/git.tcp.direct/kayos/sendkeys?status.svg)](https://godoc.org/git.tcp.direct/kayos/sendkeys) [![Go Report Card](https://goreportcard.com/badge/github.com/yunginnanet/sendkeys)](https://goreportcard.com/report/github.com/yunginnanet/sendkeys) -### sendkeys is a cross-platform usability wrapper for the [keybd_event](https://github.com/micmonay/keybd_event) Go library. - - --- - - - ### Summary - Use this library to turn full strings into simulated keyboard events with ease; - along with some neat features like **optionally randomized delays**. - - --- - -### Improvements -* Optimized map lookups +## Summary -* Negative integer -> abs inversion to determine shift key necessity + sendkeys is a cross-platform usability wrapper for the [keybd_event](https://github.com/micmonay/keybd_event) Go library. - - -* Only send one key at a time, clear state in between + Use this library to turn full strings into simulated keyboard events with ease. This library was created after a noVNC instance I was using had a broken clipboard feature. -This appears to provide a *faster*, *more reliable*, and *easier to use* interface to the functionality of [keybd_event](https://github.com/micmonay/keybd_event). - + I have successfully used the [example](./_example/main.go) to send a very long password into a NoVNC instance that had all kinds of varying case alphanumeric characters along with many symbols. - -#### See [my test results](#test) below and compare this wrapper with [keybd_event](https://github.com/micmonay/keybd_event) alone. - ---- - -![GoDoc image](https://tcp.ac/i/baROs) +## Features -### Usage - -#### Check the [unit test](./sendkeys_test.go) and the [docs](https://godoc.org/git.tcp.direct/kayos/sendkeys). +* Optionally randomized delays between keypresses. -### Status +* Optimized map lookups should provide very high performance. + +* Negative integer -> abs inversion to determine when to send the shift key event. + +* Only send one key at a time, and clear the state inbetween keys for reliable functionality. + +* Appears to provide a *faster*, *more reliable*, and *easier to use* way for humans to access to the functionality of [keybd_event](https://github.com/micmonay/keybd_event). + +## Documentation + +#### For simple usage, take a look at [the example](./_example/main.go). + +
+ GoDoc + +#### type KBOpt + +```go +type KBOpt uint8 +``` + +KBOpt[s] are options for our wrapper + +```go +const ( + // Stubborn will cause our sequences to continue despite errors. + // Otherwise, we will stop if our error count is over 0. + Stubborn KBOpt = iota + // Noisy will cause all errors to be printed to stdout. + Noisy + // Random will use random sleeps throughout the typing process. + // Otherwise, a static 10 milliseconds will be used. + Random + // NoDelay will bypass the 2 second delay for linux, mostly for testing. + NoDelay +) +``` + +#### type KBWrap + +```go +type KBWrap struct { + // There are unexported fields +} +``` + +KBWrap is a wrapper for the keybd_event library for convenience + +#### func NewKBWrapWithOptions + +```go +func NewKBWrapWithOptions(opts ...KBOpt) (kbw *KBWrap, err error) +``` +NewKBWrapWithOptions creates a new keyboard wrapper with the given options. As +of writing, those options include: Stubborn Noisy and Random. The defaults are +all false. + +#### func (*KBWrap) BackSpace + +```go +func (kb *KBWrap) BackSpace() +``` +BackSpace presses the backspace key. All other keys will be cleared. + +#### func (*KBWrap) Enter + +```go +func (kb *KBWrap) Enter() +``` +Enter presses the enter key. All other keys will be cleared. + +#### func (*KBWrap) Escape + +```go +func (kb *KBWrap) Escape() +``` +Escape presses the escape key. All other keys will be cleared. + +#### func (*KBWrap) Tab + +```go +func (kb *KBWrap) Tab() +``` +Tab presses the tab key. All other keys will be cleared. + +#### func (*KBWrap) Type + +```go +func (kb *KBWrap) Type(s string) error +``` +Type types out a string by simulating keystrokes. Check the exported Symbol map +for non-alphanumeric keys. + +
+ +## Status sendkeys is in early development. tests pass on a real machine, but I'm done trying to make github actions work for this one. @@ -183,10 +256,15 @@ ok git.tcp.direct/kayos/sendkeys 8.139s -### Compatibility +## Compatibility -sendkeys has only been tested in Linux so far, however the underlying library seemingly has support for all Go platforms. This should be cross platform. +~~sendkeys has only been tested in Linux so far~~ + +the underlying library seemingly has support for all Go platforms. This should be cross platform. + +Recently briefly tested in windows, I'm not sure that the shift key trigger is working or not. Needs to be tested further. + +## Credits -### Credits * ##### [micmonay](https://github.com/micmonay) of course, for creating [keybd_event](https://github.com/micmonay/keybd_event). * ##### [Christopher Latham Sholes](https://en.wikipedia.org/wiki/Christopher_Latham_Sholes) for his work on the QWERTY keyboard. diff --git a/_example/go.mod b/_example/go.mod new file mode 100644 index 0000000..2a13660 --- /dev/null +++ b/_example/go.mod @@ -0,0 +1,7 @@ +module chatsend + +go 1.17 + +require git.tcp.direct/kayos/sendkeys v0.0.0-20211205165836-9dbc5b7ef7f8 + +require github.com/micmonay/keybd_event v1.1.1 // indirect diff --git a/_example/go.sum b/_example/go.sum new file mode 100644 index 0000000..cb1bdc0 --- /dev/null +++ b/_example/go.sum @@ -0,0 +1,8 @@ +git.tcp.direct/kayos/sendkeys v0.0.0-20211205165836-9dbc5b7ef7f8 h1:MLok7dkRnVSNxOi14WF8z9m5tydrCn5wVTCV/ThQ9cs= +git.tcp.direct/kayos/sendkeys v0.0.0-20211205165836-9dbc5b7ef7f8/go.mod h1:edjLKQfay4hUSVqDbZ7JoYg1PwM2BbUQ+rcoh9pz9qQ= +github.com/eiannone/keyboard v0.0.0-20200508000154-caf4b762e807 h1:jdjd5e68T4R/j4PWxfZqcKY8KtT9oo8IPNVuV4bSXDQ= +github.com/eiannone/keyboard v0.0.0-20200508000154-caf4b762e807/go.mod h1:Xoiu5VdKMvbRgHuY7+z64lhu/7lvax/22nzASF6GrO8= +github.com/micmonay/keybd_event v1.1.1 h1:rv7omwXWYL9Lgf3PUq6uBgJI2k1yGkL/GD6dxc6nmSs= +github.com/micmonay/keybd_event v1.1.1/go.mod h1:CGMWMDNgsfPljzrAWoybUOSKafQPZpv+rLigt2LzNGI= +golang.org/x/sys v0.0.0-20211124211545-fe61309f8881 h1:TyHqChC80pFkXWraUUf6RuB5IqFdQieMLwwCJokV2pc= +golang.org/x/sys v0.0.0-20211124211545-fe61309f8881/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= diff --git a/_example/main.go b/_example/main.go new file mode 100644 index 0000000..bc8da1c --- /dev/null +++ b/_example/main.go @@ -0,0 +1,76 @@ +package main + +import ( + "bufio" + "fmt" + "os" + "strconv" + "time" + + "git.tcp.direct/kayos/sendkeys" +) + +var ( + sleeptime = 10 + random = false + textlines []string +) + +func init() { + parseArgs() + + scanner := bufio.NewScanner(os.Stdin) + for scanner.Scan() { + textlines = append(textlines, scanner.Text()) + } + fmt.Printf("\ngot %d lines from standard input\n", len(textlines)) +} + +func parseArgs() { + for i, arg := range os.Args { + if arg == "" { + continue + } + if arg == "-n" && len(os.Args) >= i { + sleep, err := strconv.Atoi(os.Args[i+1]) + if err == nil { + sleeptime = sleep + os.Args[i+1] = "" + } + } + if arg == "-r" { + random = true + } + + if arg == "-h" || arg == "--help" { + println("Sendkeys example: pipe text into here, and it will type it out after a delay, will press enter for each line") + println("Example: uname -a | " + os.Args[0]) + println("Flags: -n (wait this many seconds before sending text)") + } + + } +} + +func main() { + opts := []sendkeys.KBOpt{sendkeys.Noisy} + if random { + opts = append(opts, sendkeys.Random) + println("entropy enabled") + } + k, err := sendkeys.NewKBWrapWithOptions(sendkeys.Noisy) + if err != nil { + println(err.Error()) + return + } + fmt.Printf("\nSleeping for %d seconds", sleeptime) + for n := 0; n != sleeptime; n++ { + time.Sleep(1 * time.Second) + print(".") + } + println("Sending keys!") + for _, line := range textlines { + k.Type(line) + k.Enter() + } + println("\ndone!") +} diff --git a/go.mod b/go.mod index d3de6ca..8130dbb 100644 --- a/go.mod +++ b/go.mod @@ -7,4 +7,4 @@ require ( github.com/micmonay/keybd_event v1.1.1 ) -require golang.org/x/sys v0.0.0-20211124211545-fe61309f8881 // indirect +require golang.org/x/sys v0.0.0-20211205182925-97ca703d548d // indirect diff --git a/go.sum b/go.sum index c771e5e..5853241 100644 --- a/go.sum +++ b/go.sum @@ -2,5 +2,5 @@ github.com/eiannone/keyboard v0.0.0-20200508000154-caf4b762e807 h1:jdjd5e68T4R/j github.com/eiannone/keyboard v0.0.0-20200508000154-caf4b762e807/go.mod h1:Xoiu5VdKMvbRgHuY7+z64lhu/7lvax/22nzASF6GrO8= github.com/micmonay/keybd_event v1.1.1 h1:rv7omwXWYL9Lgf3PUq6uBgJI2k1yGkL/GD6dxc6nmSs= github.com/micmonay/keybd_event v1.1.1/go.mod h1:CGMWMDNgsfPljzrAWoybUOSKafQPZpv+rLigt2LzNGI= -golang.org/x/sys v0.0.0-20211124211545-fe61309f8881 h1:TyHqChC80pFkXWraUUf6RuB5IqFdQieMLwwCJokV2pc= -golang.org/x/sys v0.0.0-20211124211545-fe61309f8881/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20211205182925-97ca703d548d h1:FjkYO/PPp4Wi0EAUOVLxePm7qVW4r4ctbWpURyuOD0E= +golang.org/x/sys v0.0.0-20211205182925-97ca703d548d/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=