GCli

GitHub go.mod Go version

Простая и удобная библиотека для создания командных приложений на Go. Включает в себя выполнение команд, цветовые стили, отображение данных, отображение прогресса, методы взаимодействия и т. д.

Английская версия

Английское описание доступно по ссылке README

Примеры

app-cmd-list ## Основные функции

Простота и удобство использования, богатый функционал
Поддержка добавления нескольких команд и возможность задания псевдонимов для команд
Поддержка привязки опций команд к структурам
- Пример flag:"name=int0;shorts=i;required=true;desc=int option message"
Поддержка добавления многоуровневых команд, каждая из которых может иметь свои опции
option/flag быстрое и удобное добавление привязок опций (--long), поддержка добавления нескольких коротких опций (например: -s)
- Возможность задания обязательности опции Required
- Возможность задания валидатора для опции Validator
argument поддержка привязки параметров к определённым именам (параметры — это оставшиеся параметры после привязки флагов)
- Поддержка задания параметров как обязательных/необязательных Required, массива isArray
- Автоматическое обнаружение и сбор параметров при выполнении команды
colorable поддержка богатого цветного вывода, реализовано с помощью gookit/color
- Поддержка цветного вывода с использованием HTML-тегов, совместимо с Windows
- Внутренняя поддержка различных стилей, таких как info, error, success, danger и др.
interact встроенная поддержка методов взаимодействия с пользователем: ReadLine, Confirm, Select, MultiSelect и др.
progress встроенная поддержка методов отображения прогресса: Txt, Bar, Loading, RoundTrip, DynamicText и др.- При ошибке ввода команды будет выдано сообщение о похожих командах (включая псевдонимы)
Автоматическая обработка ошибок, error будет автоматически преобразован в сообщение об ошибке
Автоматическое создание справочной информации для команд и поддержка цветного отображения
Поддержка создания файлов с автозавершением команд для zsh и bash для текущего CLI приложения
Поддержка запуска отдельных команд как самостоятельных приложений

Документация GoDoc- godoc для gopkg

godoc для github

Установка

go get github.com/gookit/gcli/v3

Быстрый старт

Вот пример, где можно быстро написать CLI-приложение, импортировав текущий пакет:

package main

import (
    "runtime"
    "github.com/gookit/gcli/v3"
    "github.com/gookit/gcli/v3/_examples/cmd"
)

// Тестовый запуск: go run ./_examples/cliapp.go && ./cliapp
func main() {
    app := gcli.NewApp()
    app.Version = "1.0.3"
    app.Desc = "это мое CLI-приложение"
    // app.SetVerbose(gcli.VerbDebug)

    app.Add(cmd.Example)
    app.Add(&gcli.Command{
        Name: "demo",
        // разрешено использование цветовых тегов и {$cmd} будет заменено на 'demo'
        Desc: "это описание <info>сообщения</> для команды",
        Aliases: []string{"dm"},
        Func: func(cmd *gcli.Command, args []string) error {
            gcli.Println("привет, в команде demo")
            return nil
        },
    })

    // .... добавить больше ...

    app.Run(nil)
}

Инструкции по использованию

Сначала используйте примеры кода из этого проекта, чтобы создать небольшое CLI-приложение.

% go build ./_examples/cliapp.go

Вывод информации о версии

Вывод информации о версии, которую вы установили при создании CLI-приложения. Если вы также установили логотип, он также будет отображен.

% ./cliapp --version
# или используйте -V
% ./cliapp -V

app-version

Отображение справки по приложениюИспользуйте `./cliapp` или `./cliapp -h` для отображения справки по приложению, включая все доступные команды и некоторые глобальные опции.

Пример:

./cliapp
./cliapp -h # также можно использовать
./cliapp --help # также можно использовать

cmd-list

Отображение справки по команде

Отображение справки по конкретной команде.

Пример:

./cliapp {command} -h
./cliapp {command} --help
./cliapp help {command}

cmd-help

Подсказки по похожим командам

Если вы ввели неверную команду, но есть похожие по названию, будет показана подсказка.

cmd-tips

Запуск команды

Синтаксис:

./cliapp КОМАНДА [--ОПЦИЯ ЗНАЧЕНИЕ -S ЗНАЧЕНИЕ ...] [АРГУМЕНТ0 АРГУМЕНТ1 ...]

Пример

./cliapp ex -c some.txt -d ./dir --id 34 -n tom -n john val0 val1 val2 arrVal0 arrVal1 arrVal2

Можно заметить результат сборки опций и аргументов:

run-example

Создание скрипта автозавершения команд

import  "github.com/gookit/gcli/v3/builtin"

    // ...
    // Добавление встроенных команд для генерации
    app.Add(builtin.GenAutoComplete())

Сборка и запуск команды для генерации (после успешного выполнения команду можно удалить):

% go build ./_examples/cliapp.go && ./cliapp genac -h // Показать справку
% go build ./_examples/cliapp.go && ./cliapp genac // Начать генерацию, вы увидите подобное сообщение
INFO: 
  {shell:zsh binName:cliapp output:auto-completion.zsh}

Теперь, будет создан файл auto-completion.zsh
Продолжить? [yes|no](по умолчанию yes): y
```OK, файл автозавершения создан успешно

После запуска в текущей директории будет создан файл auto-completion.{zsh|bash}, имя оболочки берется автоматически. Конечно, вы можете указать его вручную при запуске.

Сгенерированный файл скрипта оболочки можно посмотреть здесь:

для bash auto-completion.bash
для zsh auto-completion.zsh

Пример вывода:

auto-complete-tips

Создание команд

Простое использование

app.Add(&gcli.Command{
    Name: "demo",
    // разрешение на использование цветовых тегов и {$cmd} будет заменено на 'demo'
    Desc: "это описание <info>сообщение</> для команды", 
    Aliases: []string{"dm"},
    Func: func (cmd *gcli.Command, args []string) error {
        gcli.Print("привет, в команде demo\n")
        return nil
    },
})

Использование отдельного файла

исходный файл находится по адресу: example.go

package cmd

import (
	"fmt"

	"github.com/gookit/color"
	"github.com/gookit/gcli/v3"
)// опции для команды
var exampleOpts = struct {
	id  int
	c   string
	dir string
	opt string
	names gcli.Strings
}{}// Определение команды ExampleCommand
var ExampleCommand = &gcli.Command{
	Name:        "example",
	Desc: "это описание команды",
	Aliases:     []string{"exp", "ex"}, // альтернативные названия команды
	// {$binName} {$cmd} - переменные помощи. '{$cmd}' будет заменен на 'example'
	Examples: `{$binName} {$cmd} --id 12 -c val ag0 ag1
<cyan>{$fullCmd} --names tom --names john -n c</> test use special option`,
	Config: func(c *gcli.Command) {
		// привязка информации о параметрах команды
		c.IntOpt(&exampleOpts.id, "id", "", 2, "параметр id")
		c.StrOpt(&exampleOpts.c, "config", "c", "value", "параметр конфигурации")
		// обратите внимание, что `DIRECTORY` будет заменено на тип значения параметра
		c.StrOpt(&exampleOpts.dir, "dir", "d", "", "параметр DIRECTORY")
		// поддержка установки коротких названий параметров
		c.StrOpt(&exampleOpts.opt, "opt", "o", "", "сообщение параметра")
		// поддержка привязки пользовательских переменных, но они должны реализовать интерфейс flag.Value
		c.VarOpt(&exampleOpts.names, "names", "n", "сообщение параметра")
	}
}		// Привязка информации о параметрах команды, привязка по позиции параметров
	c.AddArg("arg0", "первый обязательный параметр", true)
	c.AddArg("arg1", "второй обязательный параметр", true)
	c.AddArg("arg2", "необязательный параметр")
	c.AddArg("arrArg", "массивный параметр, является массивом", false, true)
},
	Func:  exampleExecute,
}// Основная логика выполнения команды
// Пример запуска:
// 	go run ./_examples/cliapp.go ex -c some.txt -d ./dir --id 34 -n tom -n john val0 val1 val2 arrVal0 arrVal1 arrVal2
func exampleExecute(c *gcli.Command, args []string) error {
	fmt.Print("Привет, в команде example\n")

	magentaln := color.Magenta.Println

	magentaln("Все опции:")
	fmt.Printf("%+v\n", exampleOpts)
	magentaln("Исходные аргументы:")
	fmt.Printf("%v\n", args)

	magentaln("Получение аргумента по имени:")
	arr := c.Arg("arrArg")
	fmt.Printf("именованный массивный аргумент '%s', значение: %v\n", arr.Name, arr.Value)

	magentaln("Все именованные аргументы:")
	for _, arg := range c.Args() {
		fmt.Printf("именованный аргумент '%s': %+v\n", arg.Name, *arg)
	}

	return nil
}

Просмотрите справочную информацию для этой команды:

go build ./_examples/cliapp.go && ./cliapp example -h

Справочная информация уже сгенерирована и отображена

cmd-help

Добавление опций

Методы для добавления опций:

BoolOpt(p *bool, name, shorts string, defValue bool, desc string)
BoolVar(p *bool, meta FlagMeta)
Float64Opt(p *float64, name, shorts string, defValue float64, desc string)
Float64Var(p *float64, meta FlagMeta)
Int64Opt(p *int64, name, shorts string, defValue int64, desc string)
Int64Var(p *int64, meta FlagMeta)
IntOpt(p *int, name, shorts string, defValue int, desc string)
IntVar(p *int, meta FlagMeta)
StrOpt(p *string, name, shorts, defValue, desc string)
StrVar(p *string, meta FlagMeta)
Uint64Opt(p *uint64, name, shorts string, defValue uint64, desc string)
Uint64Var(p *uint64, meta FlagMeta)
UintOpt(p *uint, name, shorts string, defValue uint, desc string)
UintVar(p *uint, meta FlagMeta)
Var(p flag.Value, meta FlagMeta)
VarOpt(p flag.Value, name, shorts, desc string)

Примеры использования:```go var id int var b bool var opt, dir string var f1 float64 var names gcli.Strings

cmd.IntOpt(&id, "id", "", 2, "опция id")
cmd.BoolOpt(&b, "bl", "b", false, "логическая опция")
// обратите внимание, что `DIRECTORY` будет заменено на значение опции типа
cmd.StrOpt(&dir, "dir", "d", "", "опция `DIRECTORY`")
// установка имени опции и короткого имени опции
cmd.StrOpt(&opt, "opt", "o", "", "сообщение опции")
// установка специальной переменной опции, которая должна реализовывать интерфейс flag.Value
cmd.VarOpt(&names, "names", "n", "сообщение опции")### Привязка параметров
```О параметрах определения:

- **Обязательные** параметры не могут быть определены после **необязательных** параметров.
- Разрешено определение только одного массивного параметра (с несколькими значениями).
- Массивный параметр может быть определен только в конце.

Методы для привязки параметров:

```go
Add(arg Argument) *Argument
AddArg(name, desc string, requiredAndArrayed ...bool) *Argument
AddArgument(arg *Argument) *Argument
BindArg(arg Argument) *Argument

Примеры использования:

cmd.AddArg("arg0", "первый обязательный параметр", true)
cmd.AddArg("arg1", "второй обязательный параметр", true)
cmd.AddArg("arg2", "необязательный параметр")
cmd.AddArg("arrArg", "массивный параметр", false, true)

Также можно использовать Add()/BindArg():

cmd.Add("arg0", gcli.Argument{
	Name: "ag0",
	Desc: "первый обязательный параметр",
	Require: true,
})
cmd.BindArg("arg2", gcli.Argument{
	Name: "ag0",
	Desc: "третий необязательный параметр",
})
cmd.BindArg("arrArg", gcli.Argument{
	Name: "arrArg",
	Desc: "третий массивный параметр",
	Arrayed: true,
})

Получение параметров

Параметры можно получить с помощью c.Arg(name string) *gcli.Argument. С помощью встроенных методов параметры могут быть преобразованы в обычные типы данных.

var MyCommand = &gcli.Command{
	Name: "example",
	Desc: "пример команды",
	Config: func(c *gcli.Command) {
		cmd.BindArg("arg0", gcli.Argument{
			Name: "ag0",
			Desc: "первый обязательный параметр",
			Require: true,
		})
		cmd.Add("arg1", gcli.Argument{
			Name: "ag1",
			Desc: "второй необязательный параметр",
		})
	},
	Func: func(c *gcli.Command, args []string) error {
		arg0 := c.Arg("arg0").String()
		arg1 := c.Arg("arg1").Int()
		fmt.Println(arg0, arg1)
		return nil
	},
}
```## Отображение прогресса

- `progress.Bar` — универсальный прогресс-бар.

Пример: `./cliapp prog bar`

![prog-bar](_examples/images/progress/prog-bar.svg)

- `progress.Txt` — текстовый прогресс-бар.

Пример: `./cliapp prog txt`

![prog-txt](_examples/images/progress/prog-txt.svg)

- `progress.LoadBar` — загрузка.

![prog-demo](_examples/images/progress/prog-spinner.jpg)

- `progress.Counter` — счетчик.
- `progress.RoundTrip` — прогресс-бар, который перемещается туда и обратно.

```text
[===     ] -> [    === ] -> [ ===    ]
```![prog-rt](_examples/images/progress/prog-rt.jpg)

- `progress.DynamicText` — динамическое сообщение, которое отображает разные сообщения при достижении различных процентов выполнения.

Пример:

```go
package main

import "time"
import "github.com/gookit/gcli/v3/progress"

func main() {
	speed := 100
	maxSteps := 110
	p := progress.Bar(maxSteps)
	p.Start()

	for i := 0; i < maxSteps; i++ {
		time.Sleep(time.Duration(speed) * time.Millisecond)
		p.Advance()
	}

	p.Finish()
}

Для более подробных примеров и использования, см. progress_demo.go

Запуск примера:

go run ./_examples/cliapp.go prog txt
go run ./_examples/cliapp.go prog bar
go run ./_examples/cliapp.go prog roundTrip

prog-other

Интерактивные методы

Методы для взаимодействия с пользователем в консоли, включая чтение ввода, подтверждение, одиночный выбор, множественный выбор, вопросы и т.д.

interact.ReadInput
interact.ReadLine
interact.ReadFirst
interact.Confirm
interact.Select/Choice
interact.MultiSelect/Checkbox
interact.Question/Ask
interact.ReadPassword

Пример:

package main

import (
	"fmt"

	"github.com/gookit/gcli/v3/interact"
)func main() {
	username, _ := interact.ReadLine("Your name?")
	password := interact.ReadPassword("Your password?")
	
	ok := interact.Confirm("Confirm continuation?")
	if !ok {
		// execute something...
	}
    
	fmt.Printf("name: %s, password: %s\n", username, password)
}
```### Чтение ввода

```go
ans, _ := interact.ReadLine("Ваше имя? ")

if ans != "" {
    color.Println("Ваш ввод: ", ans)
} else {
    color.Cyan.Println("Нет ввода!")
}

interact-read

Одиночный выбор

ans := interact.SelectOne(
    "Ваш город (используйте массив)?",
    []string{"chengdu", "beijing", "shanghai"},
    "",
)
color.Comment.Println("ваш выбор: ", ans)

interact-select

Множественный выбор

ans := interact.MultiSelect(
    "Ваши города (используйте массив)?",
    []string{"chengdu", "beijing", "shanghai"},
    nil,
)
color.Comment.Println("ваши выбор: ", ans)

interact-select

Подтверждение

if interact.Confirm("Подтвердите продолжение") {
    fmt.Println(emoji.Render(":smile: Подтверждено"))
} else {
    color.Warn.Println("Не подтверждено")
}

interact-confirm

Чтение пароля

pwd := interact.ReadPassword()

color.Comment.Println("ваш введенный пароль: ", pwd)

interact-passwd

Дополнительные примеры и использование см. в interact_demo.go

Использование цветного вывода

Цветной вывод использует gookit/color, поддерживает работу в окружении Windows cmd.exe PowerShell

Примеры цветного вывода

colored-demo

Как использовать

package main

import (
    "github.com/gookit/color"
)

func main() {
	// Простое использование
	color.Cyan.Printf("Просто использовать %s\n", "цвет")
}
```	// Внутренние темы/стили:
	color.Info.Tips("указание")
	color.Info.Prompt("указание")
	color.Info.Println("сообщение")
	color.Warn.Println("предупреждение")
	color.Error.Println("ошибка")
	
	// Пользовательский цвет
	color.New(color.FgWhite, color.BgBlack).Println("пользовательский стиль цвета")	// Также можно:
	color.Style{color.FgCyan, color.OpBold}.Println("пользовательский стиль цвета")
	
	// Использование определенного цветного тега
	color.Print("использование цветного тега: <suc>he</><comment>llo</>, <cyan>wel</><red>come</>\n")

	// Использование пользовательского цветного тега
	color.Print("пользовательский цветной тег: <fg=yellow;bg=black;op=underscore;>hello, welcome</>\n")

	// Установка стиля тега
	color.Tag("info").Println("текст стиля info")

	// Вывод сообщений в стиле prompt
	color.Info.Prompt("сообщение стиля prompt")
	color.Warn.Prompt("сообщение стиля prompt")

	// Вывод сообщений в стиле tips
	color.Info.Tips("сообщение стиля tips")
	color.Warn.Tips("сообщение стиля tips")
}

Строим стили

// Установка только фона
color.BgRed.Printf("Просто использовать %s\n", "цвет")
// Установка только переднего плана
color.FgCyan.Printf("Просто использовать %s\n", "цвет")

// Полная настройка переднего плана, фона и опций
style := color.New(color.FgWhite, color.BgBlack, color.OpBold)
style.Println("пользовательский стиль цвета")

// Также можно:
color.Style{color.FgCyan, color.OpBold}.Println("пользовательский стиль цвета")

Использование встроенных стилей

color.Bold.Println("жирное сообщение")
color.Yellow.Println("желтое сообщение")

Расширение темы стилей:

color.Info.Println("сообщение info")
color.Success.Println("сообщение success")

Использование цветных HTML-тегов

Также поддерживается использование цветных тегов в окружении Windows cmd.exe PowerShell. Использование цветовых меток позволяет очень удобно и просто создавать любой необходимый формат.```go // Использование встроенных цветовых меток color.Print("he</>llo</>, wel</>come</>") color.Println("hello</>") color.Println("hello</>") color.Println("hello</>")

// Настройка пользовательских цветовых атрибутов color.Print("<fg=yellow;bg=black;op=underscore;>hello, welcome</>\n")


> **Для получения дополнительной информации о использовании библиотеки цветов посетите [gookit/color](https://github.com/gookit/color)**

## Инструменты Gookit- [gookit/ini](https://github.com/gookit/ini) Управление конфигурациями INI, поддержка загрузки нескольких файлов, слияние данных, парсинг переменных ENV, парсинг ссылок на переменные
 - [gookit/rux](https://github.com/gookit/rux) Простой и быстрый маршрутизатор запросов для HTTP в Go
 - [gookit/gcli](https://github.com/gookit/gcli) Библиотека для создания командных линейных приложений на Go, поддержка цветов в командной строке, пользовательского взаимодействия, отображения прогресса, форматированного отображения данных
 - [gookit/event](https://github.com/gookit/event) Легковесная библиотека для управления событиями и планирования задач на Go, поддержка настройки приоритета слушателей, слушателей групп событий
 - [gookit/cache](https://github.com/gookit/cache) Общая библиотека для использования кэша, предоставляющая унифицированный API для различных драйверов
 - [gookit/config](https://github.com/gookit/config) Управление конфигурациями Go, поддержка различных форматов (JSON, YAML, TOML, INI, HCL, ENV, Flags), загрузка нескольких файлов, загрузка удаленных файлов, слияние данных
 - [gookit/color](https://github.com/gookit/color) Библиотека для рендеринга цветов в командной строке, имеет простой API, поддерживает 16 цветов, 256 цветов, RGB цвета
 - [gookit/filter](https://github.com/gookit/filter) Фильтрация, очистка и преобразование данных Go
 - [gookit/validate](https://github.com/gookit/validate) Общая библиотека для валидации и фильтрации данных Go, простое использование, включает большинство стандартных валидаторов и фильтров
 - [gookit/goutil](https://github.com/gookit/goutil)com/gookit/goutil) Набор утилит Go, включая форматирование, специальные обработчики, получение информации и т. д.
- Для получения дополнительной информации посетите https://github.com/gookit## Ссылки на проекты

- `issue9/term` https://github.com/issue9/term
- `beego/bee` https://github.com/beego/bee
- `inhere/console` https://github/inhere/php-console
- [ANSI Escape Codes](https://ru.wikipedia.org/wiki/ANSI_Escape_Codes)
- [Standard ANSI color map](https://conemu.github.io/en/AnsiEscapeCodes.html#Standard_ANSI_color_map)
- go package: `golang.org/x/crypto/ssh/terminal`

## Лицензия

MIT

OSCHINA-MIRROR/gookit-gcli

GCli

Английская версия

Примеры

Документация GoDoc- godoc для gopkg

Установка

Быстрый старт

Инструкции по использованию

Вывод информации о версии

Отображение справки по приложениюИспользуйте `./cliapp` или `./cliapp -h` для отображения справки по приложению, включая все доступные команды и некоторые глобальные опции.

Отображение справки по команде

Подсказки по похожим командам

Запуск команды

Создание скрипта автозавершения команд

Создание команд

Простое использование

Использование отдельного файла

Добавление опций

Получение параметров

Интерактивные методы

Одиночный выбор

Множественный выбор

Подтверждение

Чтение пароля

Использование цветного вывода

Как использовать

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/gookit-gcli .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

GCli

Английская версия

Примеры

Документация GoDoc- godoc для gopkg

Установка

Быстрый старт

Инструкции по использованию

Вывод информации о версии

Отображение справки по приложениюИспользуйте ./cliapp или ./cliapp -h для отображения справки по приложению, включая все доступные команды и некоторые глобальные опции.

Отображение справки по команде

Подсказки по похожим командам

Запуск команды

Создание скрипта автозавершения команд

Создание команд

Простое использование

Использование отдельного файла

Добавление опций

Получение параметров

Интерактивные методы

Одиночный выбор

Множественный выбор

Подтверждение

Чтение пароля

Использование цветного вывода

Как использовать

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/gookit-gcli