221 lines
8.1 KiB
Markdown
221 lines
8.1 KiB
Markdown
# rubric
|
||
|
||
Интерактивный терминальный справочник для разработчика. Цветной вывод, структурированные разделы с примерами кода, быстрый доступ по ключам.
|
||
|
||
```
|
||
./rubric
|
||
```
|
||
|
||
```
|
||
╔════════════════════════════════════════════════════════════╗
|
||
║ rubric — интерактивный справочник ║
|
||
╚════════════════════════════════════════════════════════════╝
|
||
|
||
Доступные справочники:
|
||
|
||
1. go Справочник по языку Go
|
||
Установка, синтаксис, типы, функции, горутины...
|
||
```
|
||
|
||
---
|
||
|
||
## Установка
|
||
|
||
**Требования:** Go 1.21+
|
||
|
||
```bash
|
||
git clone https://github.com/user/rubric
|
||
cd rubric
|
||
go build -o rubric .
|
||
```
|
||
|
||
Или сразу установить глобально:
|
||
|
||
```bash
|
||
go install github.com/user/rubric@latest
|
||
```
|
||
|
||
---
|
||
|
||
## Использование
|
||
|
||
### Интерактивный режим
|
||
|
||
```bash
|
||
./rubric
|
||
```
|
||
|
||
Открывается главное меню со списком справочников. Навигация двухуровневая:
|
||
|
||
```
|
||
rubric → выбор справочника → выбор раздела
|
||
```
|
||
|
||
Вводить можно **номер** или **ключ**:
|
||
|
||
```
|
||
Выберите справочник: 1
|
||
Выберите справочник: go
|
||
```
|
||
|
||
Внутри справочника:
|
||
|
||
```
|
||
Раздел: 2
|
||
Раздел: structs
|
||
Раздел: s ← сокращённый алиас
|
||
```
|
||
|
||
Для возврата на уровень выше — `b`. Для выхода — `q`.
|
||
|
||
### Быстрый доступ (без меню)
|
||
|
||
```bash
|
||
# Открыть справочник Go
|
||
./rubric -book go
|
||
|
||
# Открыть конкретный раздел сразу
|
||
./rubric -book go -topic basics
|
||
./rubric -book go -topic structs
|
||
|
||
# По алиасу
|
||
./rubric -book g -topic s
|
||
```
|
||
|
||
### Вспомогательные флаги
|
||
|
||
```bash
|
||
./rubric -list # список всех справочников
|
||
./rubric -help # справка по флагам и ключам
|
||
```
|
||
|
||
---
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
rubric/
|
||
├── go.mod
|
||
├── main.go # точка входа, разбор флагов
|
||
├── utils/
|
||
│ └── display.go # цвета, форматирование вывода
|
||
├── catalog/
|
||
│ ├── catalog.go # главное меню, реестр справочников
|
||
│ └── gobook.go # справочник Go: меню и навигация
|
||
└── modules/
|
||
└── gomodules/
|
||
├── registry.go # реестр разделов Go
|
||
├── basics.go # раздел: установка и команды
|
||
└── structures.go # раздел: структура программы
|
||
```
|
||
|
||
Каждый **справочник** — отдельный файл в `catalog/`. Каждый **раздел** внутри справочника — отдельный файл в соответствующем подпакете `modules/`.
|
||
|
||
---
|
||
|
||
## Справочники и разделы
|
||
|
||
### go — Язык Go
|
||
|
||
| Ключ | Алиасы | Раздел |
|
||
|------|--------|--------|
|
||
| `basics` | `b`, `base`, `install` | Установка и основные команды |
|
||
| `structs` | `s`, `struct`, `vars`, `types` | Структура программы |
|
||
|
||
#### basics — Установка и основные команды
|
||
|
||
- Установка Go на Linux / macOS / Windows
|
||
- Структура проекта, `go mod init`
|
||
- `go build` — сборка и кросс-компиляция
|
||
- `go run` — запуск без сборки
|
||
- `go test` — тесты, покрытие, бенчмарки, race-детектор
|
||
- `go fmt`, `go vet`, `golangci-lint` — форматирование и анализ
|
||
- `go doc` — документация
|
||
- `go get`, `go mod tidy` — управление зависимостями
|
||
- `go env`, `go clean`, `go install` — окружение и утилиты
|
||
|
||
#### structs — Структура программы
|
||
|
||
- Имена, ключевые слова, предопределённые идентификаторы
|
||
- Четыре вида объявлений: `const`, `type`, `var`, `func`
|
||
- Переменные: `var`, `:=`, нулевые значения, `var`-блоки
|
||
- Указатели: `&`, `*`, nil, сравнение адресов
|
||
- Функция `new` и когда её использовать
|
||
- Время жизни переменных, escape analysis
|
||
- Присваивания: простые, составные, tuple assignment, `_`
|
||
- Объявления типов, алиасы, конверсии
|
||
- Пакеты, файлы, все формы импорта
|
||
- Инициализация пакетов, функция `init()`
|
||
- Область видимости, затенение (shadowing)
|
||
|
||
---
|
||
|
||
## Как добавить новый раздел в справочник Go
|
||
|
||
1. Создать файл `modules/gomodules/mymodule.go`:
|
||
|
||
```go
|
||
package gomodules
|
||
|
||
import "rubric/utils"
|
||
|
||
var MyModule = Module{
|
||
Key: "mykey",
|
||
Aliases: []string{"mk"},
|
||
Title: "Название раздела",
|
||
Description: "Краткое описание",
|
||
Run: showMyModule,
|
||
}
|
||
|
||
func showMyModule() {
|
||
utils.Header("Заголовок")
|
||
utils.Section("Подраздел")
|
||
utils.Code(`// пример кода`)
|
||
utils.Note("Важное замечание")
|
||
utils.Footer()
|
||
}
|
||
```
|
||
|
||
2. Добавить в `modules/gomodules/registry.go` в срез `All`:
|
||
|
||
```go
|
||
var All = []Module{
|
||
BasicsModule,
|
||
StructuresModule,
|
||
MyModule, // ← добавить сюда
|
||
}
|
||
```
|
||
|
||
Больше ничего не требуется — модуль автоматически появится в меню, поиске и навигации.
|
||
|
||
## Как добавить новый справочник (например, linux)
|
||
|
||
1. Создать `catalog/linuxbook.go` по образцу `catalog/gobook.go`
|
||
2. Создать `modules/linuxmodules/` с нужными разделами
|
||
3. Добавить `LinuxBook` в срез `catalog.All` в `catalog/catalog.go`
|
||
4. При необходимости расширить `switch *book` в `main.go` для флага `-book linux -topic ...`
|
||
|
||
---
|
||
|
||
## Вспомогательные функции форматирования
|
||
|
||
Все модули используют пакет `utils` для единообразного вывода:
|
||
|
||
| Функция | Описание |
|
||
|---------|----------|
|
||
| `utils.Header(title)` | Заголовок раздела в рамке |
|
||
| `utils.Section(title)` | Подзаголовок с линией |
|
||
| `utils.Code(code)` | Блок кода в рамке |
|
||
| `utils.Command(cmd, desc)` | Команда с описанием |
|
||
| `utils.Note(text)` | Замечание с иконкой 💡 |
|
||
| `utils.Info(label, value)` | Пара ключ — значение |
|
||
| `utils.Println(text)` | Обычная строка с отступом |
|
||
| `utils.Footer()` | Нижняя линия раздела |
|
||
|
||
---
|
||
|
||
## Цветовой вывод
|
||
|
||
Использует ANSI escape-коды. Работает в большинстве современных терминалов: iTerm2, Terminal.app, GNOME Terminal, Windows Terminal, tmux и других.
|
||
|
||
В средах без поддержки цвета (например, при перенаправлении вывода в файл) escape-коды будут видны как есть. При необходимости отключения цвета — установите переменную `NO_COLOR=1` перед запуском или реализуйте проверку `os.Getenv("NO_COLOR")` в `utils/display.go`.
|