Crystal Programming. Введение на основе проекта в создание эффективных, безопасных и читаемых веб-приложений и приложений CLI - Джордж Дитрих

используя тот же ввод, что и раньше, фильтр .id | . + 1 выдаст результат 2. Обратите внимание, что в этом примере мы используем идентификационный фильтр для ссылки на выходное значение предыдущего фильтра, которое в этом примере было равно 1, которое изначально пришло из входного объекта.

Доступ к определенным значениям из входных данных — это только половина дела, когда дело доходит до преобразования данных. jq предоставляет способ создания новых объектов/массивов с использованием синтаксиса JSON. Используя проверенный входной объект, который мы использовали, фильтр {"new_id":(.id+2)} создает новый объект, который выглядит как {"new_id":3}. Аналогично, массив можно создать с помощью синтаксиса [] и [(.id), (.id*2), (.id)] создает массив [1, 2, 1]. В обоих последних примерах мы используем круглые скобки, чтобы контролировать порядок операций оценки фильтра.

Давайте объединим все эти функции в более сложный пример, учитывая следующие входные данные:

[

  {

    "id": 1,

    "author": {

        "name": "Jim"

    }

  },

  {

    "id": 2,

    "author": {

       "name": "Bob"

    }

  }

]

Мы можем использовать фильтр [.[] | {"id": (.id + 1), "name": .author.name}] для получения следующего вывода, полная команда — jq '[.[] | {"id": (.id + 1), "name": .author.name}]' input.json:

[

    {

        "id": 2,

        "name": "Jim"

    },

    {

        "id": 3,

        "name": "Bob"

    }

]

Если вы хотите узнать больше о возможностях jq, ознакомьтесь с его документацией по адресу https://stedolan.github.io/jq/manual, поскольку существует множество вариантов, методов и функций, выходящих за рамки этой книги.

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

Строительные леса проекта

Первое, что нам нужно сделать, это инициализировать новый проект, который будет содержать код приложения. Crystal предлагает простой способ сделать это с помощью команды crystal init. Эта команда создаст новую папку, создаст базовый набор файлов и инициализирует пустой репозиторий Git. Команда поддерживает создание проектов типа app и lib, с той лишь разницей, что в проектах библиотеки файл shard.lock также игнорируется через .gitignore, по той причине, что зависимости будут заблокированы через приложение, использующее проект. Учитывая, что у нас не будет никаких внешних общих зависимостей и в конечном итоге мы захотим разрешить включение проекта в другие проекты Crystal, мы собираемся создать проект lib.

Начните с запуска crystal init lib transform в вашем терминале. Это инициализирует проект библиотеки под названием Transform со следующей структурой каталогов (файлы, связанные с Git, опущены для краткости):

Давайте подробнее рассмотрим, что представляют собой эти файлы/каталоги:

• .editorconfig — файл https://editorconfig.org, который позволяет некоторым IDE (если они настроены правильно) автоматически применять стиль кода Crystal к файлам *.cr.

• LICENSE — лицензия, которую использует проект. По умолчанию используется MIT, и нас это устраивает.

См. https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/licensing-a-repository для получения дополнительной информации.

• README.md — следует использовать для общей документации по приложению, такой как установка, использование и предоставление информации.

• shard.yml — содержит метаданные об этом осколке Crystal. Подробнее об этом в Главе 8 «Использование внешних библиотек».

• spec/ — папка, в которой хранятся все спецификации (тесты), относящиеся к приложению. Подробнее об этом в Главе 14 «Тестирование».

• src/ — папка, в которой находится исходный код приложения.

• src/transform.cr — основная точка входа в приложение.

Хотя эта структура проекта является хорошей отправной точкой, мы собираемся внести несколько изменений, создав еще один файл: src/transform_cli.cr. Также добавьте в файл shard.yml следующее:

targets:

   transform:

      main: src/transform_cli.cr

Это позволит нам запустить run shards build, а также собрать двоичный файл CLI и вывести его в каталог ./bin.

Разбивать код на несколько файлов — хорошая практика как по организационным причинам, так и для предоставления более специализированных точек входа в ваше приложение. Например, проект преобразования можно использовать как через командную строку, так и в другом приложении Crystal. По этой причине мы можем использовать src/transform.cr в качестве основной точки входа, тогда как src/transform_cli.cr требует src/transform.cr, но также включает некоторую логику, специфичную для CLI. Мы вернемся к этому файлу позже в этой главе.

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

Написание базовой реализации

Прежде чем мы перейдем непосредственно к написанию кода, давайте потратим минуту на то, чтобы спланировать, что именно должен делать наш код. Целью нашего CLI является создание программы, позволяющей использовать YAML с jq. В конечном итоге это сводится к трем требованиям:

1. Преобразуйте входные данные YAML в JSON.

2. Передайте преобразованные данные в jq.

3. Преобразуйте выходные данные JSON в YAML.

Важно помнить, что конечной целью этого упражнения является демонстрация того, как различные концепции Crystal могут применяться для создания функционального и удобного приложения CLI. Таким образом, мы не собираемся уделять слишком много внимания попыткам сделать его на 100% надежным для каждого варианта использования, а вместо этого сосредоточимся больше на различных инструментах/концепциях, используемых в рамках реализации.

Имея это в виду, давайте перейдем к написанию первоначальной реализации, начав с чего-то простого и повторяя его, пока не получим полностью работающую реализацию. Начнем с самого простого случая: вызовите jq с жестко закодированными данными JSON, чтобы показать, как эта часть будет работать. К счастью для нас, стандартная библиотека Crystal включает тип https://crystal-lang.org/api/Process.html, который позволяет напрямую вызывать процесс jq, установленный в данный момент. Таким образом, мы можем использовать все его функции без необходимости переносить их в Crystal.

Откройте src/transform.cr в выбранной вами IDE и обновите его, чтобы он выглядел следующим образом:

module Transform

   VERSION = "0.1.0"

   # The same input data used in the example at the

  # beginning of the chapter.

   INPUT_DATA = %([{"id":1,"author":{"name":"Jim"}},{"id":2,

  "author":{"name":"Bob"}}])

   Process.run(

      "jq",

      [%([.[] | {"id": (.id + 1), "name": .author.name}])],

      input: IO::Memory.new(INPUT_DATA),

      output: :inherit

   )

end

Сначала мы определяем константу с входными данными, которые использовались в предыдущем примере. Process.run запускает процесс и ожидает его завершения. Затем мы вызываем его, используя jq в качестве команды вместе с массивом аргументов (в данном случае только фильтр).