DmitriyTat Jun 23 2020 at 10:06

Todo-лист для командной строки на Deno

11 min

5.9K

FUNCORP corporate blogJavaScript*TypeScript*Programming*

Tutorial

Вы уже наверняка слышали про Deno и, скорее всего, прочитали пару-тройку обзоров. В рамках своей статьи я предлагаю испытать Deno на практике, написав приложение для командной строки, попутно размышляя о преимуществах и возможных способах его применения.

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

Основные преимущества, такие как безопасность, TypeScript «из коробки», встроенные инструменты, обширная стандартная библиотека, а также возможность импортировать и запускать скрипты по URL, выгодно отличают Deno от Node и Bash. С помощью Deno мы можем написать скрипт, залить на GitHub Gist и запускать при необходимости командой deno run https://path.to/script.ts, не заботясь о зависимостях и настройке окружения.

Для начала работы нужно только установить Deno одним из предложенных способов https://deno.land/#installation.

Todo для Todo

Todo-лист должен уметь:

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

Аргументы командной строки

Практически любая консольная утилита управляется с помощью передаваемых при запуске аргументов. В Deno они лежат массивом в Deno.args. А, к примеру, в Node мы бы использовали process.argv, в котором помимо аргументов находятся строки node и путь к скрипту.

// deno run args.ts first second

console.log(Deno.args) // [ "first", "second" ]

В простых случаях Deno.args будет достаточно, а в более сложных можно воспользоваться парсером из стандартной библиотеки: https://deno.land/std/flags или любым другим на выбор.

Итак, начнём…

Реализуем первую команду – вывод информации.

Создадим главный файл нашего приложения – todo.ts. Лучше назвать файл осмысленно, так как в будущем он понадобится нам для запуска и установки.

Далее создадим файл /src/ui.ts, в котором будем хранить элементы «пользовательского интерфейса». Добавим константу help, содержащую информационный текст.

export const help = `todo help - to show available commands`;

В todo.ts напишем свитч для обработки команд и выведем справку с помощью console.log().

#!/usr/bin/env deno run

import { help } from "./src/ui.ts";

const [command, ...args] = Deno.args;

switch (command) {
  case "help":
    console.log(help);
}

Проверим работу команды:

deno run todo.ts help

Для того, чтобы при каждом запуске не писать deno run, добавим шебанг #!.

#!/usr/bin/env deno run

Разрешим запуск файла:

chmod +x todo.ts

Теперь для вывода справки можно использовать:

./todo.ts help

Стандартный вывод

В листинге выше мы использовали console.log(), но, мне кажется, идеологически log – это инструмент разработчика, и реализовать с его помощью полноценный интерфейс не получится.

В Deno за стандартный вывод отвечает Deno.stdout, за ввод, соответственно, Deno.stdin.

/** A handle for `stdin`. */
export const stdin: Reader & ReaderSync & Closer & { rid: number };
/** A handle for `stdout`. */
export const stdout: Writer & WriterSync & Closer & { rid: number };

И stdin, и stdout типизированы пересечением интерфейсов и объекта, содержащего rid, – идентификатор ресурса.

Более подробно рассмотрим stdout и выведем «Hello world!» в консоль.

const textEncoder = new TextEncoder();

const message: string = "Hello world!\n";
const encodedMessage: Uint8Array = textEncoder.encode(message);

await Deno.stdout.write(encodedMessage);

Запустим скрипт hello.ts:

deno run hello.ts

На экране появляется наш «Hello world!».

export interface Writer {
  write(p: Uint8Array): Promise<number>;
}

Функция Deno.stdout.write принимает на вход массив байтов и возвращает количество записанных байтов. Deno.stdout.writeSync работает точно так же, только синхронно.

Строку необходимо предварительно закодировать с помощью объекта TextEncoder.
Можно не создавать TextEncoder, а импортировать функцию encode из стандартной библиотеки, которая делает то же самое, точно так же.

import { encode } from 'https://deno.land/std/encoding/utf8.ts';

Воспользуемся полученными знаниями и создадим файл terminal.ts с двумя функциями print и printLines. Последняя выводит строку и переводит каретку.

import { encode } from "https://deno.land/std/encoding/utf8.ts";

export async function print(message: string) {
  await Deno.stdout.write(encode(message));
}

export async function printLines(message: string) {
  await print(message + "\n");
}

Заменим console.log на printLines.

#!/usr/bin/env deno run

import { help } from "./src/ui.ts";
import { printLines } from "./src/Terminal.ts";

const [command, ...args] = Deno.args;

switch (command) {
  case "help":
    await printLines(help);
}

Чтение и запись файла

В Deno для чтения файла используется функция Deno.readFile и её синхронный аналог Deno.readFileSync.

function Deno.readFile(path: string | URL): Promise<Uint8Array>

const decoder = new TextDecoder("utf-8");
const data = await Deno.readFile("hello.txt");
console.log(decoder.decode(data));

Для записи в файл соответственно используются Deno.writeFile и Deno.writeFileSync.

function Deno.writeFile(path: string | URL, data: Uint8Array, options?: WriteFileOptions): Promise<void>

const encoder = new TextEncoder();
const data = encoder.encode("Hello world\n");
await Deno.writeFile("hello1.txt", data);  // overwrite "hello1.txt" or create it

В стандартной библиотеке Deno содержатся функции, позволяющие упростить взаимодействие с файловой системой: https://deno.land/std/fs. Например, код выше можно заменить вызовами функций readFileStr и writeFileStr.

Создадим интерфейс Task в src/Task.ts

export interface Task { 
  title: string;
  isDone: boolean;
}

и класс Todo в файле src/Todo.ts.

import {
  writeJsonSync,
  readJsonSync, 
} from "https://deno.land/std/fs/mod.ts"; 
import { Task } from "./Task.ts";

export class Todo {
  tasks: Task[] = [];

  constructor(private file: string = "tasks.json") {
    this.open();
  }

  open() {
    try {
      this.tasks = readJsonSync(this.file) as Task[];
    } catch (e) {
      console.log(e);
      this.tasks = [];
    }
  }

  save() {
    writeJsonSync(this.file, this.tasks, { spaces: 2 });
  }
}

Как можно заметить, для чтения и записи данных я использовал специальные функции из стандартной библиотеки для работы с json-файлами.

Добавление задачи в список

Для реализации команды todo add "implement add command" добавляем в класс Todo метод add.

add(title: string) {
    const task: Task = {
        title,
        isDone: false
    };

    this.tasks.push(task);
    this.save();
}

Так как мы добавили чтение и запись в файл, необходимо добавить права --allow-read --allow-write.

#!/usr/bin/env deno run --allow-read --allow-write 

import { help } from "./src/ui.ts";
import { printLines } from "./src/terminal.ts";
import { Todo } from "./src/Todo.ts";

const [command, ...args] = Deno.args;

const todo = new Todo();

switch (command) {
  case "help":
    await printLines(help);
    break;

  case "add":
    todo.add(args[0]);
}

Вывод списка задач

В файл src/ui.ts добавляем функцию для форматирования списка задач.

import { Task } from "./Task.ts";
import { green, red, yellow, bold } from "https://deno.land/std/fmt/colors.ts";

export function formatTaskList(tasks: Task[]): string {
  const title = `${bold("TODO LIST:")}`;

  const list = tasks.map((task, index) => {
    const number = yellow(index.toString());
    const checkbox = task.isDone ? green("[*]") : red("[ ]");

    return `${number} ${checkbox} ${task.title}`;
  });

  const lines = [
    title,
    ...list,
  ];

  return lines.join("\n");
}

Для задания стиля и цвета текста используем функции форматирования из https://deno.land/std/fmt/colors.ts.

Добавляем метод list в класс Todo и команду ls в свитч.

async list() {
  await printLines(formatTaskList(this.tasks));
}

case "ls":
  await todo.list();
  break;

Таким же образом добавляем остальные методы и команды.

done(index: number): void {
  const task = this.tasks[index];

  if (task) {
    task.isDone = true;
    this.save();
  }
}

undone(index: number): void {
  const task = this.tasks[index];

  if (task) {
    task.isDone = false;
    this.save();
  }
}

edit(index: number, title: string) {
  const task = this.tasks[index];

  if (task) {
    task.title = title;
    this.save();
  }
}

remove(index: number) {
  this.tasks.splice(index);
  this.save();
}

case "edit": // todo edit 1 "edit second task"
  await todo.edit(parseInt(args[0], 10), args[1]);
  break;

case "done" : // todo done 1
  todo.done(parseInt(args[0], 10));
  break;

case "undone" : // todo undone 1
  todo.undone(parseInt(args[0], 10));
  break;

case "remove" : // todo remove 1
  todo.remove(parseInt(args[0], 10));
  break;

Реализованные команды отвечают первым трём пунктам наших требований.

Работа в интерактивном режиме

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

Создадим в свитче кейс по умолчанию,

default:
  await todo.interactive();

а в классе Todo асинхронный метод interactive.

async interactive() {
  while (true) {
    // show list
    // read keypress

    // do action
  }
}

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

Для управления курсором в интерактивном режиме необходимо импортировать функции из библиотеки cursor.
Добавляем права для доступа к энвайронменту, так как библиотека проверяет, в каком окружении программа запущена --allow-env.

import { clearDown, goUp, goLeft } from "https://denopkg.com/iamnathanj/cursor@v2.0.0/mod.ts";

В файле terminal.ts создадим функцию printInteractive.

export async function printInteractive(message: string) {
  const lines = message.split("\n");
  const numberOfLines = lines.length;
  const lengthOfLastLine = lines[numberOfLines - 1].length;

  await clearDown();
  await print(message);
  await goLeft(lengthOfLastLine);

  if (numberOfLines > 1) {
    await goUp(numberOfLines - 1);
  }
}

Она выводит текст на экран и возвращает курсор в начало. При следующем вызове всё стирается и печатается заново. Для того чтобы квадрат курсора не мешался, его можно скрыть функцией hideCursor.

Добавим в файл ui.ts константу toolbar, в которой будут перечислены доступные действия.

const toolbar = `${yellow("d")}one ${yellow("a")}dd ${yellow("e")}dit ${yellow("r")}emove`;

В функцию formatTaskList добавляем параметр showToolbar:

export function formatTaskList(tasks: Task[], showToolbar: boolean): string {
// ...
if (showToolbar) {
  lines.push(toolbar);
}

В зависимости от флага showToolbar мы будем показывать или скрывать подсказку.

Дорабатываем метод list:

async list(interactive: boolean = false) {
  if (interactive) {
    await printInteractive(formatTaskList(this.tasks, true));
  } else {
    await printLines(formatTaskList(this.tasks, false));
  }
}

Вывод реализован, перейдём к вводу.

Стандартный ввод

Интерфейс ввода, аналогично выводу работает с Uint8Array, поэтому для декодирования используется TextDecoder.

const textDecoder = new TextDecoder();
const buffer: Uint8Array = new Uint8Array(1024);

const n: number = <number>await Deno.stdin.read(buffer);
const message: string = textDecoder.decode(buffer.subarray(0, n));

Создаём буфер размером, например, в 1024 байта. Передаём его в функцию Deno.stdin.read и ждём пока пользователь закончит ввод. Как только будет нажата клавиша enter, функция наполнит буфер и вернёт количество прочитанных байтов. Стоит отметить, что перевод строки «\n» будет в конце прочитанной последовательности. Обрезаем лишнее и декодируем полученную строку. Синхронная функция Deno.stdin.readSync работает аналогично.

Обработка клавиш

Для того чтобы получить информацию о нажатии клавиш, необходимо воспользоваться функцией Deno.setRaw. На текущий момент она доступна под флагом --unstable. setRaw и позволяет получить символы по одному, без обработки. В функцию необходимо передать идентификатор ресурса и флаг. Как только мы воспользовались этим режимом, нажатие CTRL+C перестаёт приводить к закрытию программы, и это поведение нужно реализовать самостоятельно.

Deno.setRaw(Deno.stdin.rid, true);
const length = <number> await Deno.stdin.read(buffer);
Deno.setRaw(Deno.stdin.rid, false);

В файл terminal.ts добавляем функцию readKeypress:

export async function readKeypress(): Promise<string> {
  const buffer = new Uint8Array(1024);
  Deno.setRaw(Deno.stdin.rid, true);
  const length = <number> await Deno.stdin.read(buffer);
  Deno.setRaw(Deno.stdin.rid, false);

  return decode(buffer.subarray(0, length));
}

В метод interactive добавляем возможность выйти из приложения.

async interactive() {
  while (true) {
    await this.list(true);
    const key = await readKeypress();

    if (key == "\u0003") { // ctrl-c
      Deno.exit();
    }
  }
}

Не отходя далеко от ввода текста, реализуем добавление задачи в интерактивном режиме.

В файл terminal.ts добавляем 2 функции:

export async function readLine(): Promise<string> {
  const buffer = new Uint8Array(1024);
  const length = <number> await Deno.stdin.read(buffer);
  return decode(buffer.subarray(0, length - 1));
}

export async function prompt(question: string): Promise<string> {
  await clearDown();
  await print(question);
  const answer = await readLine();
  await goLeft(question.length + answer.length);
  await goUp(1);

  return answer;
}

Функция readLine позволяет прочитать одну строку, исключая последний символ, – перевод строки.

Функция prompt очищает экран, печатает вопрос, читает ввод пользователя, а затем перемещает курсор в начало, аналогично функции printInteractive.

В метод interactive добавляем обработку клавиши «а»:

if (key === "a") {
  const title = await prompt("Add task: ");

  if (title) {
    await this.add(title);
  }
}

Перемещение по списку задач

Добавим поддержку стрелок клавиатуры. Для того чтобы понимать, какой элемент сейчас выбран, добавляем свойство currentIndex в класс Todo:

  private currentIndex: number = 0;

А в функции formatTaskList активную строку выделяем жирным и красим в жёлтый:

export function formatTaskList(
  tasks: Task[],
  showToolbar: boolean = false,
  activeIndex?: number,
): string {
  const title = `${bold("TODO LIST:")}`;

  const list = tasks.map((task, index) => {
    // ...
    const isActive = activeIndex === index;
    const title = isActive ? bold(yellow(task.title)) : task.title;

    return `${number} ${checkbox} ${title}`;
  });

  // ...
}

В Todo создаём методы, которые будут изменять currentIndex:

up() {
  this.currentIndex = this.currentIndex === 0
    ? this.tasks.length - 1
    : this.currentIndex - 1;
}

down() {
  this.currentIndex = this.currentIndex === this.tasks.length - 1
    ? 0
    : this.currentIndex + 1;
}

В метод interactive добавляем обработку стрелок:

if (key === "\u001B\u005B\u0041" || key === "\u001B\u005B\u0044") { // вверх или влево
  this.up();
} else if (key === "\u001B\u005B\u0042" || key === "\u001B\u005B\u0043") { // вниз или вправо
  this.down();
}

Аналогичным образом добавляем возможность отмечать выполненные задачи:

toggle(index: number = this.currentIndex) {
  const task = this.tasks[index];

  if (task) {
    task.isDone = !task.isDone;
    this.save();
  }
}

if (key === "d" || key === " ") {
    this.toggle();
} else if ('0' <= key && key <= '9') {
    this.toggle(parseInt(key, 10));
}

Дорабатываем удаление:

remove(index: number = this.currentIndex) {
  if (index === this.tasks.length - 1) {
    this.up();
  }

  this.tasks.splice(index, 1);
  this.save();
}

if (key === "r") {
    this.remove();
}

И, наконец, редактирование:

if (key === "e") {
  if (!this.tasks[this.currentIndex]) {
    return;
  }

  const title = await prompt("Edit task (" + this.tasks[this.currentIndex].title + "): ");

  if (title) {
    this.edit(this.currentIndex, title);
  }
}

Проверяем работу приложения:

deno run --allow-read --allow-write --allow-env --unstable ./todo.ts

или

./todo.ts

Установка

Для того что бы наша программа была доступна в терминале, воспользуемся замечательной командой deno install.

deno install --allow-read --allow-write --allow-env --unstable ./todo.ts

Установка, так же как и запуск, может производиться по URL.

deno install --allow-read --allow-write --allow-env --unstable  https://raw.githubusercontent.com/dmitriytat/todo/master/todo.ts

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

После чего todo можно использовать в командной строке.

Импорт зависимостей

Последняя фича, которую мы использовали, но ещё не обсудили – импорт зависимостей. В отличие от Node, в Deno подход к импортированию несколько иной: предполагается, что зависимости импортируются по URL. В этом подходе, на мой взгляд, есть как достоинства, так и недостатки.

При разработке однофайловых скриптов, возможность импортировать по URL является огромным плюсом, но как только мы разработаем что-то большее, уследить за версиями станет труднее.

Для управления сложностью существует два основных решения: файл dep.ts и файл с картой импортов.

В первом случае мы делаем реэкспорт библиотек, собирая все импорты в одном месте.

export { green, red, yellow, bold } from "https://deno.land/std@0.55.0/fmt/colors.ts";
export { decode, encode } from "https://deno.land/std@v0.55.0/encoding/utf8.ts";
export { clearDown, goUp, goLeft } from "https://denopkg.com/iamnathanj/cursor@v2.0.0/mod.ts";

Во втором случае в JSON файле мы пишем alias:

import_map.json

{
   "imports": {
      "fmt/": "https://deno.land/std@0.55.0/fmt/"
   }
}

color.ts

import { red } from "fmt/colors.ts";

console.log(red("hello world"));

При запуске программы указываем путь до карты и флаг --unstable, так как фича не готова для продакшена.

deno run --importmap=import_map.json --unstable color.ts.

Резюме

В целом, работой Deno я доволен. Новый инструмент позволяет не тратить время на настройку окружения и сразу приступать к написанию кода, что оказалось очень удобно.
Таким образом, я могу рекомендовать Deno для написания небольших скриптов и программ, упрощающих жизнь разработчика, но пока воздержался бы от использования Deno для создания продакшен-приложений.

Tags:

Hubs: