Пользовательские строки формата

Иногда полезно позволить пользователям и программам Lisp управлять тем, как генерируется определенный текст, с помощью пользовательских строк управления форматом. Например, строка формата может определять, как отображать имя, фамилию и адрес электронной почты человека. Используя функцию format, описанную в предыдущем разделе, строка формата может быть чем-то вроде "%s %s <%s>". Однако этот подход быстро становится непрактичным, так как непонятно, какой символ спецификации соответствует какому фрагменту информации.

Более удобной строкой формата в таких случаях будет что-то вроде "%f %l <%e>", где каждый символ спецификации несет больше семантической информации и может легко переставляться относительно других символов спецификации, что делает такие строки формата более настраиваемыми для пользователя.

Функция format-spec, описанная в этом разделе, выполняет функцию, аналогичную format, за исключением того, что она работает со строками управления форматом, которые используют произвольные символы спецификации.

Функция: format-spec шаблон spec-alist &optional ignore-missing split

Эта функция возвращает строку, созданную из строки формата шаблон в соответствии с преобразованиями, указанными в spec-alist, который является списком ассоциаций (см. Списки ассоциаций) вида (letter . replacement). Каждый символ спецификации %letter в шаблоне будет заменен заменой при форматировании результирующей строки.

Символы в шаблоне, отличные от спецификаций формата, копируются непосредственно в вывод, включая их свойства текста, если таковые имеются. Любые свойства текста спецификаций формата копируются в их замены.

Использование списка ассоциаций для указания преобразований приводит к некоторым полезным свойствам:

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

Необязательный аргумент ignore-missing указывает, как обрабатывать символы спецификаций в шаблоне, которых нет в spec-alist. Если он равен nil или опущен, функция сигнализирует об ошибке; если он равен ignore, эти спецификации формата оставляются дословно в выводе, включая их свойства текста, если таковые имеются; если он равен delete, эти спецификации формата удаляются из вывода; любое другое значение, отличное от nil, обрабатывается как ignore, но любые вхождения ‘%%’ также оставляются дословно в выводе.

Если необязательный аргумент split отличен от nil, вместо возвращения одной строки, format-spec разделит результат на список строк, исходя из того, где были выполнены подстановки. Например:

(format-spec "foo %b bar" '((?b . "zot")) nil t)
     ⇒ ("foo " "zot" " bar")

Синтаксис спецификаций формата, принимаемых format-spec, аналогичен, но не идентичен, синтаксису, принимаемому format. В обоих случаях спецификация формата представляет собой последовательность символов, начинающуюся с ‘%’ и заканчивающуюся буквой, например, ‘s’.

В отличие от format, которая присваивает определенные значения фиксированному набору символов спецификации, format-spec принимает произвольные символы спецификации и обрабатывает их одинаково. Например:

(setq my-site-info
      (list (cons ?s system-name)
            (cons ?t (symbol-name system-type))
            (cons ?c system-configuration)
            (cons ?v emacs-version)
            (cons ?e invocation-name)
            (cons ?p (number-to-string (emacs-pid)))
            (cons ?a user-mail-address)
            (cons ?n user-full-name)))

(format-spec "%e %v (%c)" my-site-info)
     ⇒ "emacs 27.1 (x86_64-pc-linux-gnu)"

(format-spec "%n <%a>" my-site-info)
     ⇒ "Emacs Developers <emacs-devel@gnu.org>"

Спецификация формата может включать любое количество следующих символов флагов сразу после ‘%’ для изменения аспектов подстановки.

‘0’

Этот флаг заставляет любое форматирование, заданное шириной, состоять из символов ‘0’ вместо пробелов.

‘-’

Этот флаг заставляет любое форматирование, заданное шириной, вставляться справа, а не слева.

‘<’

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

‘>’

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

‘^’

Этот флаг преобразует замененный текст в верхний регистр (см. Преобразование регистра).

‘_ (подчеркивание)’

Этот флаг преобразует замененный текст в нижний регистр (см. Преобразование регистра).

Результат использования противоречивых флагов (например, и верхнего, и нижнего регистра) не определен.

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

Если подстановка содержит меньше символов, чем ее заданная ширина, она дополняется слева:

(format-spec "%8a is padded on the left with spaces"
             '((?a . "alpha")))
     ⇒ "   alpha is padded on the left with spaces"

Если подстановка содержит больше символов, чем ее заданная точность, она обрезается справа:

(format-spec "%.2a is truncated on the right"
             '((?a . "alpha")))
     ⇒ "al is truncated on the right"

Вот более сложный пример, объединяющий несколько упомянутых функций:

(setq my-battery-info
      (list (cons ?p "73")      ; Percentage
            (cons ?L "Battery") ; Status
            (cons ?t "2:23")    ; Remaining time
            (cons ?c "24330")   ; Capacity
            (cons ?r "10.6")))  ; Rate of discharge

(format-spec "%>^-3L : %3p%% (%05t left)" my-battery-info)
     ⇒ "BAT :  73% (02:23 left)"

(format-spec "%>^-3L : %3p%% (%05t left)"
             (cons (cons ?L "AC")
                   my-battery-info))
     ⇒ "AC  :  73% (02:23 left)"

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