Файлы и кодирование

Объект PK предоставляет 10 методов для файлов и кодирования. Они меняют представление данных или передают байты через строку, но не шифруют содержимое и не защищают его от чтения.

Что выбрать

Текст, байты и их запись

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

decodeBase64 и baseEncodeDecode после восстановления байтов пытаются вернуть текст. hexToBase64 сохраняет сами байты и меняет только их печатную форму.

Простая пара Base64

const encoded = PK.base64("demo");
// encoded === "ZGVtbw=="

Значение внутри адреса

const query = PK.urlEncode("Data Export & Каталог");
const url = "https://example.com/search?q=" + query;

Исправить строку из системной кодировки

PK.ansiToUTF8(input)

Повторно преобразует строку через текущую системную кодовую страницу Windows. Метод нужен только для подтверждённого искажения, когда байты системной кодировки были прочитаны как другой текст.

const repaired = PK.ansiToUTF8("Êàòàëîã òîâàðîâ");
// На Windows с русской кодовой страницей: "Каталог товаров"

Результат зависит от кодовой страницы компьютера. Если преобразование даёт пустую строку или знак замены �, метод возвращает исходный текст, поэтому совпадение результата со входом не доказывает правильность исходной кодировки. Граница применения объяснена в справке по ANSITOUTF8.

Загрузить файл как Base64

PK.fileToBase64(input)

Отправляет запрос GET по переданному адресу через текущую прокси, загружает всё тело ответа в память и возвращает Base64 полученных байтов. Несмотря на старое описание параметра как пути, фактический метод работает с сетевым адресом, а не с локальным файлом.

const imageBase64 = PK.fileToBase64(
  "https://example.com/assets/logo.png"
);

Метод не обещает перенести свой внутренний ответ в PK.response, PK.headers или типизированные сетевые свойства, поэтому не используйте их как подтверждение этой загрузки. Он также не проверяет назначение тела: если сервер вернул страницу ошибки, её байты тоже могут стать корректной строкой Base64. Всё тело и увеличенная примерно на треть строка одновременно находятся в памяти, поэтому не применяйте метод к файлам неизвестного или неограниченного размера.

Сетевое поведение и расход памяти подробнее описаны в справке по FILETOBASE64.

Между Base64 и шестнадцатеричной записью

const encodedByte = PK.hexToBase64("A8");
// encodedByte === "qA=="

Несколько алфавитов

PK.baseEncodeDecode(input)

Принимает строку JSON, кодирует поле message выбранным алфавитом или декодирует его и читает восстановленные байты как UTF-8. Передавайте объект через JSON.stringify, чтобы кавычки и обратные косые черты значения были оформлены однозначно.

const source = "Привет";

const encoded = PK.baseEncodeDecode(JSON.stringify({
  algorithm: "Base64",
  action: "encode",
  message: source,
}));

const decoded = PK.baseEncodeDecode(JSON.stringify({
  algorithm: "Base64",
  action: "decode",
  message: encoded,
}));

if (decoded !== source) {
  throw new Error("Обратное преобразование не восстановило исходный текст");
}

Поля и алгоритмы

Имена полей, действий и алгоритмов чувствительны к регистру. Z85 принимает число исходных байтов, кратное четырём, а при декодировании — число знаков, кратное пяти. Ошибки возвращаются в том же строковом типе, что и успешный текст, поэтому произвольный результат, действительно начинающийся с Error: , неотличим от сообщения исполнителя. Не угадывайте успех по словам: проверяйте заранее известный формат или, как в примере выше, точное обратное преобразование.

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

Сохранить файл

PK.saveFile(input)

Сохраняет текст в UTF-8 или декодирует Base64 в байты. Относительный путь отсчитывается от каталога результатов текущего сеанса. Метод принимает одну строку с полями, разделёнными знаком |:

имя файла|действие|данные
имя файла|действие|text|данные
имя файла|действие|bytes|данные Base64

Текстовый файл:

const result = PK.saveFile(
  "reports\\result.txt|overwrite|text|Состояние: готово"
);

if (result !== "File saved successfully") {
  throw new Error(result);
}

Двоичный файл из Base64:

const result = PK.saveFile(
  "reports\\hello.bin|overwrite|bytes|SGVsbG8h"
);

if (result !== "File saved successfully") {
  throw new Error(result);
}

В hello.bin попадут байты Hello!, а не знаки SGVsbG8h. Для типа text перевод строки не добавляется автоматически. Если данные содержат |, все части после служебных полей снова соединяются, поэтому знак сохраняется:

const data = "left|right";
const result = PK.saveFile(
  "reports\\parts.txt|overwrite|text|" + data
);

Действия и результаты

Названия действий и типов не зависят от регистра. В студии файл не создаётся: после проверки параметров метод возвращает Success (in studio you can't save files). Эта строка подтверждает только проверку в студии, а не запись на диск.

Полный договор действий, путей, студии и строк ошибок приведён в справке по SAVEFILE.