Skip to content

Latest commit

 

History

History
218 lines (179 loc) · 16.4 KB

README.ru.md

File metadata and controls

218 lines (179 loc) · 16.4 KB

just-bun

Это позволяет использовать Bun Shell для сохранения и запуска команд, специфичных для проекта, по аналогии с just.
Главным преимуществом по сравнению с just является то, что Bun Shell бесшовно нанизывает shell-команды на сколь угодно изощренную логику, написанную на TypeScript с мощными средствами Bun-API, включающими в себя, в том числе, почти весь Node.js-API.

Содержание

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

Рецепты хранятся в файлах just_bun.ts в рукавах switch(recipeName) функции
export async function runRecipe(recipeName?: string, args = []).
Пример файла just_bun.ts:

import { $ } from "bun";

export async function runRecipe(recipeName?: string, args = []) {
    switch (recipeName) {
        case 'run':     // recipeName
        case 'r':       // recipeName alias
        case undefined: // default: for run without recipeName
            await $`cargo run`;
            break;
        case 'build_release':
        case 'b':
            await $`cargo build --release`;
            await $`echo "Result in: ${__dirname}/target/release"`;
            break;
        case 'test':
        case '# args: [filter] [-nThreads] // e.g.: -1 - in one thread': // comment for list
        case 't':
            await $`cargo test ${{raw: args.join(' ').replace('-', '-- --test-threads=')}}`;
            break;
        default:
            return console.log(`recipeName error: '${recipeName}'`);
    }
}

Теперь в рабочем каталоге содержащем этот just_bun.ts или его дочернем, команда в терминале jb -l выведет:

◇ List of recipes in ./just_bun.ts (<absolute path>/just_bun.ts):
  1. run | r | <default> 
  2. build_release | b 
  3. test | t # args: [filter] [-nThreads] // e.g.: -1 - in one thread
◇ Enter: ( <number> | <name> | <alias> ) [args]. Cancel: <Space>
> ▮

Ввод на приглашение 1 или run или r или просто <Enter> выполнит: cargo run.
А, например, ввод 3 -1 или t -1 выполнит: cargo test -- --test-threads=1.

Тот же результат можно получить без jb -l, вызвав в shell напрямую:
jb run или jb r или просто jb - для cargo run
или jb t -1 - для cargo test -- --test-threads=1.

Если вам удобнее, имя файла рецептов может иметь спереди точку и любой регистр букв до расширения. Например, Just_Bun.ts и .JUST_BUN.ts являются допустимыми именами.

Подробнее oб ограничениях синтаксиса function runRecipe() - далее.

Подробнее о ситнтаксисе и работе с Bun Shell - по ссылке.

Установка

  1. Установите Bun, если его ещё нет в вашей системе. Рекомендуемая версия Bun - не ниже 1.1.21
  2. Выполните в терминале в каталоге ~/.bun/ в bash: 
    $ mkdir jb_script; cd jb_script; bun i just-bun
$ mv -f -t ./ ./node_modules/just-bun/jb_script/**
    или в PowerShell: 
    PS> mkdir jb_script; cd jb_script; bun i just-bun
PS> mv -force ./node_modules/just-bun/jb_script/** ./
    Это создаст папку jb_script c скриптом запуска main.js, подпапкой пользовательских настроек settings и установленным в node_modules just-bun.
  3. Создайте короткий удобный alias для команды
    bun <absolute path to jb_script>/main.js в вашей основной оболочке. Здесь этот alias я буду обозначать jb.
    Если в вашей системе установлен Rust, то вместо создания alias'ов в ваших оболочках, можете скомпелировать исполняемый файл jb (jb.exe для Windows) из папки bun_script_alias репозитария и поместить его в папку ~/.bun/bin/ Единственное, что он делает - вызывает
    bun ~/.bun/jb_script/main.js с переданными ему аргументами.
    При желани, можете синхронно переименовать runner-файл и папку в более удобное для вызова имя, например - в j (j.exe для Windows) и j_script/ соответственно.
  4. На этом этапе уже всё работает, но вашему редактору кода требуются объявления @types/bun для автодополнений и контроля типов из Bun-API при редактировании файлов рецептов.
    Для этого перейдите в терминале в корневой каталог проектов, в которых вы будете использовать файлы рецептов и введите jb -@. Это создаст / обновит здесь папку node_modules/ с объявлениями @types/bun.

Формат и флаги командной строки

Этот раздел так же можно прочитать по команде jb -h или jb --help

Варианты командной строки:

  • jb [-g] [<recipeName> [args]] # основное использование
  • jb -f <path/to/recipe/file>.ts [<recipeName> [args]]
  • jb -t [<templateSearchLine>]
  • jb -lf <path/to/recipe/file>.ts
  • jb <flag>

Флаги:

  • -g запускает рецепт из глобального файла рецептов, находяшегося в папке settings. Без флага -g файл рецепта ищется в текущем каталоге и вверх по цепочке родительских каталогов
  • -f запускает рецепт из любого ts-файла, указанного в <path/to/recipe/file>
  • -t создает в текущей папке новый файл рецептов на основе шаблона, найденного по первым символам, указанным в <templateSearchLine>
  • -l показывает путь и нумерованный список рецептов для текущей папки и предлагает запустить рецепт, указав его номер | имя | псевдоним и [args]
  • -L то же, что и -l, но для глобального файла рецептов
  • -lf то же, что и -l, но для файла <path/to/recipe/file>.ts
  • -о открывает актуальный файл рецептов в редакторе
  • -O открывает глобальный файл рецептов в редакторе
  • -p выводит относительный и абсолютный пути к актуальному файлу рецептов
  • -P выводит абсолютный путь к глобальному файлу рецептов
  • -@ устанавливает/обновляет node_modules/ c @types/bun в папке текущего файла рецептов, если не находит, то - в текущей папке
  • -i проверяет и исправляет абсолютный путь импорта к funcs.ts в текущем файле рецептов и во всех файлах рецептов, расположенных в текущем и в дочерних каталогах
  • -u обновить just-bun до последней версии
  • -h, --help выводит справку по формату и флагам командной строки

Ограничения синтаксиса function runRecipe()

Эти ограничения наложены исключительно для корректного отображения списка рецептов, выводимого по флагам -l, -L, -lf:

Список рецептов формируется по тексту первой инструкции switch от recipeName: switch (recipeName) {...} и ограничения касаются только этой инструкции:

  1. Все выражения case должны быть строковыми литералами без переносов строк. Допускается один case на инструкцию с литералoм undefined для рецепта по умолчанию.

  2. Цепочка из нескольких case перед общим рукавом операций представляет собой:

    • необязательные комментарии рецепта: case, начинающиеся с "#"
    • обязательное имя рецепта: первый case- не комментарий
    • необязательные псевдонимы рецепта

    case- комментарии могут быть в любом месте цепочки.
    В список такой рецепт выводится в одну строку: в начале - имя рецепта и его псевдонимы через |, а в конце - первый комментарий рецепта (если есть). Остальные комментарии рецепта, если есть, выводятся дополнительными строками в столбце первого комментария.
    case с значением undefined выводится в список как <default> и может быть как псевдонимом, так и первым или единственным в цепочке case.

Содержание папки jb_script/settings/

just_bun.ts

Это файл глобальных рецептов, вызываемый из любого рабочего каталога флагами -g, -L, -O, -P. Используется для пользовательских рецептов, общих для всех проектов.
В отличие от текущих файлов рецептов, его имя должно быть строго "just_bun.ts": без точки в начале имени и в нижнем регистре.

settings.json

Это необязательный файл пользовательских настроек, отличных от значений по умолчанию:

  • notUpdate - false по умолчанию: отключает обновленеие по случайтому вводу флага -u
  • раздел editor:
    • fileOpen - командная строка открытия файла в редакторе (по умолчанию - для VS Code: "code --goto %file%").
      Если требуется вообще запретить открытие файлов по флагам -о, -O и вновь созданных из шаблонов по флагу -t, значение этого параметра следует установить в "none".
    • fileOpenReport - надо ли объявлять в консоли о переданной команде на открытие файла либо о запрете fileOpen = "none" (по умолчанию - false).

funcs.ts

Это модуль, содержащий экспортируемые пользовательские константы и функции, используемые в любых файлах рецептов. Изначально прописанные в нём экспортируемые функции используются в стартовых шаблонах файлов рецептов из папки templates-just_bun/.

Каталог templates-just_bun/

Содержит пользовательские шаблоны файлов рецептов. Они будут вызываться по первым символам имени командой jb -t [<templateSearchLine>]. Если аргумент не передан - будет использован шаблон _.ts

Если требуется чтобы вновь создаваемые по шаблонам файлы рецептов имели в начале имени точку или отличный от нижнего регистр, замените окончание имени этого каталога "just_bun" на требуемое (например, для создания файлов .JUST_BUN.ts имя каталога должно быть "templates-.JUST_BUN").

Для переносимости, шаблоны импортируют funcs.ts по относительному пути. Но в вновь создаваемых по ним файлах рецептов этот путь будет заменяться на фактический абсолютный.

Неприятные особенности Bun Shell и способы их обхода

В $`...` отсутствует опция вывода в консоль интерполированной команды

bun Issue #13129
У основной функции Bun Shell $ нет опции предварительного вывода в консоль интерполированной команды, которую часто желательно видеть при запуске рецептов.

Решение:
Можно использовать пользовательскую функцию в funcs.ts, декорирующую $`...` соответствующим образом. Именно этой цели служит изначально записанная в funcs.ts function p$(), которая вызывается так же: p$`...` , печатает близкую к $ интерполяцию команды и далее передает вызов в $. Примеры использования p$ можно найти в шаблонах.

Авто-кодирование в \uXXXX не ASCII символов параметров и путей, введенных в $`...`

bun Issue #12225
Например команда
await $`echo "▶ - play, ■ - stop"` выведет в консоль:
\u25B6 - play, \u25A0 - stop

Решение:
Передавать содержащие не ASCII символы параметры и пути в виде переменных и выражений на интерполяцию:
await $`echo ${"▶ - play, ■ - stop"}` выведет в консоль:
▶ - play, ■ - stop