Опции командной строки

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

• --smart — smart mode (мудрый режим) — обработка входного файла и генерация новых c- и h-файлов производится только в случае, если содержимое исходного файла изменилось;

• --q — quiet mode (молчаливый режим); на консоль не выводится никаких сообщений. (В будущих версиях опция будет скорректирована в соответствии со стандартом де-факто: необходимо будет использовать -q или --quiet).

• --warnings — если при обработке текста будут обнаружены некритические ошибки (предупреждения), то информация о них не только будет выведена на консоль, но еще и код, возвращаемый утилитой, будет равен 1. Этот режим включен по умолчанию. (В будущих версиях опция будет удалена).

• --nowarnings — принудительно устанавливает код, возвращаемый утилитой, равным 0. Даже если при обработке текста были предупреждения.

  Заметьте, что если задан ключ --q, то он только подавляет вывод сообщений на консоль, но никак не влияет на возвращаемый код.

Получение справки о синтаксисе вызова утилиты

Краткую справку о синтаксисе вызова утилиты можно получить, вызвав утилиту без параметров или с опцией --help:

pylcdstr.exe --help

Использование утилиты в виде скрипт-программы на языке Python

Утилита pyLCDstring распространяется в виде консольной программы для Windows и в виде скрипт-программы на языке Python. Запуск Python-скрипта аналогичен запуску exe-файла:

python pylcdstring.py [options] source.lcd

Указание кодировки русских букв

В настоящее время активно используется 5 различных кодировок русских букв — фактически на каждой платформе используется своя кодировка. По умолчанию утилита использует кодировку cp1251 (Windows) для обработки русских букв. Вы можете явно указать другую кодировку, используя директиву Coding:

//// Coding = тип_кодировки

Где тип_кодировки может быть следующим:

• win2lcd — для перекодировки русских букв в кодировке Windows cp1251 в кодировку символьных ЖКИ;
• koi2lcd — для перекодировки русских букв в кодировке КОИ-8 в кодировку символьных ЖКИ;
• dos2lcd — для перекодировки русских букв в кодировке ДОС cp866 в кодировку символьных ЖКИ;
• mac2lcd — для перекодировки русских букв в кодировке Macintosh в кодировку символьных ЖКИ;
• iso2lcd — для перекодировки русских букв в кодировке ISO 8859-5 в кодировку символьных ЖКИ;
• none — отсутствие любой перекодировки; все символы остаются сами собой;
• keil — все русские буквы из кодировки cp1251 остаются сами собой за исключением букв "ю" и "я" (0xFD и 0xFF), которые перекодируются в соответствующие восьмеричные коды (\375 и \377);
• win2dos — для перекодировки русских букв из кодировки cp1251 (Windows) в cp866 (DOS);
• dos2win — для перекодировки русских букв из кодировки cp866 (DOS) в cp1251 (Windows);
• koi2win — для перекодировки русских букв из кодировки КОИ-8 в cp1251 (Windows).
• iso2win — для перекодировки русских букв из кодировки ISO 8859-5 в cp1251 (Windows).

Настройка ключевых слов в определении строковых констант

Многие Си-компиляторы для микроконтроллеров имеют специфические расширения синтаксиса языка в плане определений строковых констант, что позволяет задавать область памяти размещения константных строк. Если вас не устраивает декларация строки как char[], то вы можете указать утилите желаемую форму декларации.

Для этого в начале исходного lcd-файла необходимо указать следующее объявление:

//// Declaration = желаемая_декларация_строки

Например:

//// Declaration = char code
//// Declaration = char __flash

Настройка выравнивания строк

Вы можете для каждой строки (или для диапазона строк) задать выравнивание. Это может облегчить вам жизнь в случаях, когда необходимо, чтобы текст полностью занимал все пространство одной строки ЖКИ. Допускается выравнивать по левому или правому краю, а также по центру.

Для одиночной строки выравнивание задается в виде префикса при записи строки. Используются следующие префиксы (регистр букв значения не имеет):

• lNN, LNN — выравнивание по левому краю внутри поля NN символов
• rNN, RNN — выравнивание по правому краю внутри поля NN символов
• cNN, CNN — выравнивание по центру внутри поля NN символов
• mNN, MNN — выравнивание по центру внутри поля NN символов, с отбрасыванием пробелов справа ("полуцентрирование")
• #NN — не производить выравнивание, только контролировать длину строки

При выравнивании строка дополняется пробелами до указанной длины поля. Если ширина поля выравнивания задана нулем (т.е. #0 или L0, C0, R0), то никакой обработки выравнивания производится не будет.

Примечание: Разница между префиксами C и M заключается в том, что в первом случае строка будет выравнена по центру указанного поля и дополнена пробелами с обеих сторон. Во втором же случае строка также будет выравнена по центру поля, но пробелы справа (в конце строки) будут отброшены.

Если исходная строка длиннее заданного размера поля, то выравнивание не производится. Кроме того, программа выдает предупреждение на консоль и в выходной Си-файл об этом факте в виде следующей строки:

String too long for field size=NN (MM)

где

• NN — заданная ширина поля в символах,
• MM — реальная длина строки.

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

Примеры указания выравнивания:

name1 = L16"Строка1"
name2 = R16"Строка2"
name3 = C16"Строка3"
name5 = M16"Строка5"

name4 = #8"Очень длинная строка"

В результате обработки получится:

char name1[] = "Строка1         ";      /* L16"Строка1" */
char name2[] = "         Строка2";      /* R16"Строка2" */
char name3[] = "    Строка3     ";      /* C16"Строка3" */
char name5[] = "    Строка5";           /* M16"Строка5" */

/* String too long for field size=8 ! */
char name4[] = "Очень длинная строка"   /* #8"Очень длинная строка" */

//// Align = префикс_выравнивания

//// Align = none
//// Align = None

Изменение правил перекодировки символов

В отдельных случаях вам может понадобиться задать свои правила по перекодировке некоторых символов. Это можно сделать, указав соответствующее объявление в своем исходном lcd-файле:

//// Map = карта_перекодировки

где карта_перекодировки задается ввиде списка пар символов. Пары разделяются запятыми, элементы внутри каждой пары — двоеточием:

'оригинальный_символ':'во_что_перекодировать'

Допускается использовать указание символов в виде символьных констант ('a'), в десятичном (65) или шестнадцатеричном представлении (0x4F).

Пример:

//// Map = 'a':'b', 'b':65, 97:0x30

Генерация массива указателей на строки

Для автоматического построения массива указателей на строки, можно воспользоваться следующим синтаксисом:

array = [
     "string1",
     "string2",
     ]

Здесь:

• array — имя результирующего массива; в строке с именем массива должен находиться знак равенства и открывающая квадратная скобка;
• строка с закрывающей квадратной скобкой означает конец описания массива;
• все строки, находящиеся между квадратными скобками, представляют собой список элементов-массива. Эти строки будут обработаны по всем правилам утилитой, для них будут сгенерированы специальные определения строковых переменных.

Имена таких переменных генерируются автоматически по следующему принципу:

'_' + имя массива + '_' + порядковый номер строки (с нуля).

В декларациях строк, содержащихся в массиве, допускается использовать префиксы яного выравнивания.

//// Array_ptr  = желаемая_декларация

//// Array_ptr  = unsigned char code* code
//// Array_ptr  = char __flash *

Предупреждения

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

Предупреждения выдаются в форме следующей строки:

Имя_исходного_файла (номер_строки_в_исходном_файле): тип_предупреждения: исходная_строка

По умолчанию, при возникновении предупреждений утилита возвращает код 1. Если же при вызове утилиты указать опцию --nowarnings, то даже при возникновении предупреждений всегда будет возвращаться код 0. Если предупреждения не возникали, то всегда возвращается код 0.

Ошибки

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

Комментарии в исходном файле

Обработка исходного файла подчиняется строгим правилам, описанным выше. Все строки исходного файла с точки зрения утилиты pyLCDstring делятся на:

• определение строкового литерала, который необходимо перекодировать и поместить в выходной файл;
• указание специальной управляющей директивы (Align, Coding, Declaration, Map), которая влияет на обработку исходного файла; строка со специальной директивой в выходной файл никак не переносится;
• и всех остальных строк, которые без изменений переносятся в выходной файл.

Поскольку последний вид строк переносится без малейших изменений в выходной *.c и *.h файл, то позаботьтесь, чтобы эти строки были корректно восприняты вашим Си-компилятором.

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

Подробнее об управляющих директивах

Специальные управляющие директивы (Align, Coding, Declaration, Map) могут встречаться в исходном тексте любое число раз в любом месте — никаких ограничений на это не накладывается. Действие каждой директивы простирается до тех пор, пока не будет встречена эта же директива с другими параметрами. Наиболее актуально это для директивы Align, которая позволяет задать выравнивание по умолчанию для группы строк, перед которыми она объявлена.

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

Отдельное замечание касается директивы Map: каждый раз при обработке параметров директивы Map словарь перекодировки обновляется в соответствии с указанной картой перекодировки. Это значит, что для двух групп строк одни и те же символы могут быть перекодированы по разным правилам. Опять же, старайтесь пользоваться этим мудро, иначе вы можете получить не тот результат, на который рассчитывали.

Контроль длины строки при помощи директивы Align

В утилиту заложен механизм контроля длины исходной строки. Это свойство очень полезно при подготовке набора строк для вывода на ЖКИ с малым размером строки.

Если вы хотите, чтобы ваша строка полностью уместилась в одной строке индикатора 16*2, то воспользовавшись механизмом проверки длины строки вы сможете облегчить себе работу. Вы можете избавиться от необходимости ручного подсчета длины каждой строки, чтобы проверить "умещается или нет". Просто задайте директивой Align один из префиксов выравнивания с длиной строки вашего индикатора. При обработке lcd-файла утилитой все строки будут проверены по длине автоматически, и для очень длинных строк будут выведены предупреждающие сообщения.

name = LN""

Обработка строк, содержащих комбинации форматирования %...

В версии 2.4 добавлена корректная обработка строк, в которых содержатся комбинации форматирования, начинающиеся со знака процента (%). Эти комбинации форматирования используются при формировании строк при помощи printf/sprintf.

Если в комбинациях форматирования явно задана ширина поля для вывода данных (например, %5d), то именно эта ширина будет использоваться при подсчете длины результирующей строки при операциях выравнивания строк. Если же ширина поля для вывода данных не задана (например, %d), то никаких предположений о длине не делается.

Кодировка none

Кодировка none — в действительно это совсем не кодировка. Скорее ее следует рассматривать, как указание утилите pyLCDstring на то, что все правила перекодировок необходимо отменить. В результате обработки директивы //// Coding = none будет проведена полная очистка словаря перекодировки.

Это значит, что если вы ранее задали свои правила перекодировки при помощи директивы Map, а затем указали Coding = none, то результаты вашей директивы Map будут утрачены после очистки словаря перекодировки.

Поддержка украинского и белорусского языков

На сегодняшнем рынке символьных ЖКИ западные производители предлагают модели только с русским знакогенератором (хотя и называют это кириллицей). Однако, в этом знакогенераторе отсутствуют символы ґ, є, ї и ў, которые используются в украинском и белорусском языках. Единственным решением остается загрузка своих шрифтов в соответствующую область памяти контроллера и последующее использование соответствующих кодов.

Для задания соответствия между этими символами и кодами контроллера используйте директиву Map. О тонкостях использования этой директивы см. пункт Словарь перекодировки символов.