Trol Mobile Studio

Директива #define name [=value] служит для создания макроопределения. Она определяет макрос с именем name и присваивает ему значение value. Если последнее не указано, будет определен «пустое макроопределение». Если макроопределение с таким именем уже существует, его значение будет изменено на указанное. Далее при обработке строк исходного файла препроцессор будет заменять встречающееся макроопределение на его значение

Директива #undefine name удаляет определение макроса с именем name.

  #macro  name(a, b, c)
     ...
     тело макрофункции
     ...
  #endmacro

определяет макрофункцию с именем name и тремя параметрами a, b и c. В дальнейшем, встретив это имя с таким же числом аргументов скобках, препроцессор выполнит его замену на код, указанный в теле функции. В теле функции можно ссылаться на аргументы a, b и c. Имеется перегрузка по количеству параметров. В теле функций можно вызывать другие макросы. Но использование вложенных макросов при вызове невозможно, код macro1(macro2()) работать не будет.

Директивы #defineblock begin и #defineblock end открывают и, соответственно, закрывают блок макрокода, содержимое которого не будет включаться в результирующий текст программы. В этом блоке, например, могут быть определения макроконстант, макрофункций и комментарии для них.

Для простого включения заголовочного файла используется директива вида #include "file.h". Она вставляет все содержимое файла file.h в текст программы, начиная с текущей строки.

Директива вида #include<a\b\c> будет преобразована препроцессором в код подключения java-пакета import a.b.c

Директива вида #uselibrary "lib.jpl" включает в код программы макроопределения, макрофункции, процедуры и переменные, содержащиеся в библиотечном файле lib.jpl. При этом будут вставлены только те процедуры и переменные библиотеки, которые используются программой, т.е., на которые есть ссылка в коде.

Объявления функций и переменных библиотеки включаются в "скобки" маркерами #func #end и #var #end соответственно, как показано в примере ниже:

#var     // объявление переменной
	int var_name = var_value;
#end

#func	 // объявление функции
	String func_name(int iarg_1, String arg_2) {
		return (arg_1 + arg_2);
	}
#end
				

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

#ifdef DEFINE_NAME_1
	...
#endif
	
#ifnotdef DEFINE_NAME_2
	...
#elseif DEFINE_NAME_3
	...
#elseifnot DEFINE_NAME_4
	...
#else
	...
#endif

Встроенные макрофункции imagewidth() и imageheight() получают в качестве своего единственного аргумента имя файла изображения (поддерживаются только формат png) и подставляют ширину и выстоу изображения соответственно.

Эти функции можно использовать как при определении макроконстанты, при этом двойные кавычки могут быть опущены, так и просто в любом месте программы.
#define SPRITE_WIDTH imagewidth("sprite.png")
#define SPRITE_HEIGHT imageheight(sprite.png)

Введены для удобства написания java кода, изначально предполагалось ввести некий метаязык, который будет транслироваться препроцессором как в Ява- так и в Си-код.

Ключевое слово cоnst для java-программ будет заменено конструкцией public [static] final. Причем, слово static будет вставлено только для главного класса файла, для его подклассов оно будет опущено (внутренние классы не могут иметь статических элементов поскольку они сами не могут быть статическими).

Аналогично слово vаr будет заменено на public [static],
funс -> public) [static] final
proс -> public [static] final void'

Список – это структура данных, представляющая собой коллекцию однотипных элементов (совокупностей макроопределений, идентификаторов и значений различных типов языка). Списки могут быть использованы, например, для работы со звуками, изображениями, элементами меню и строками локализованных ресурсов. Каждый элемент списка может состоять из нескольких элементов (их число назовем размером списка), причем, этот размер списка есть величина, неизменная для всех его элементов. Таким образом, список представляет собой некоторую прямоугольную матрицу элементов. Язык предпроцессора имеет средства, позволяющие работать со списками.

Объявление списка. Синтаксис объявления списка таков:

#list list_name
   item_1_1, item_1_2, ..., item_1_m
   item_2_1, item_2_2, ..., item_2_m
      ...
   item_n_1, item_n_2, ..., item_n_m
#endlist

здесь n – число элементов в списке, m – размер списка

Для получения числа элементов списка служит макрометод списка count().
Например, следующая конструкция будет заменена макро-предпроцессором на число элементов списка list_name:
list_name->(count)()

Аналогично макрометод size() возвращает размер списка.

Обращение к элементам списка осуществляется с помощью квадратных скобок так, как показано в следующем примере:
list_name[item][sub_item]

здесь

item – номер элемента (строки) списка (нумерация идет от нуля до count()-1),
sub_item – номер подэлемента (столбца, нумерация идет от нуля до size()-1),

Итерация в списках.

Для того чтобы последовательно выполнить некоторую операцию с каждым элементом списка служит директива #foreach. Синтаксис ее использования следующий:

#foreach listname(index, sub_item1, sub_item_2, ..., sub_item_n)
  //
  // внутри блока код, выполняемый над каждым элементом списка,
  //
  // index получит номер элемента,
  //
  // а параметры sub_itemN могут быть использованы для обращения к подэлементам списка
  //
#endforeach
	

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

Добавление и удаление ресурсных файлов

Директива

#make res +(-) ”filename.ext”

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

#make resourcespath "path"

Изменение имени файла приложения

Для указания/изменения имени файла приложения служит директива

#make outputfile ”filename”

Для определения/изменения директории, в которую будет записан файл(ы) скомпилированного приложения служит директива

#make outputdir ”path”

Директива #make appname ”name” позволяет изменить название приложения, а директива #make version version - его версию.

Встроенная макрофункция toquote(str) подставляет значение своего аргумента в кавычках

#error "msg" выдает сообщение об ошибке во время обработки препроцессора

Стандартные макросы __DATЕ__, __TIME__, __FILE__, и __LINЕ__ заменяются на строку в двойных кавычках с текущей датой, временем, именем файла и строкой в нем соответственно.

// информация об ошибке)
TSErrorRec = record
  filename: string;     // имя обрабатываемого файла
  line: Integer;        // номер строки в нем
  pos: Integer;         // позиция ошибки в строке
  msg: string;          // описание ошибки
end;
  
// описание ресурсного файла
TSResourceRec = record
  filename: string;     // имя файла
  included: Boolean;    // флаг того что этот флаг должен быть включен
end;

// запись в манифесте
TSManifestRec = record
  name: string;         // имя ключа
  value: string;        // значение
  target: Integer;      // тип манифеста: TSManifestJad или TSManifestMf
end;

// макроопределение
TSDefine = record
  name: string;     // имя ключа
  value: string;     // значение
end;

TSProject = class
  // ПЕРЕМЕННЫЕ
  name: string;                   // имя главного файла
  caption: string;                // название проекта
  outFile: string;                // имя файла результата компиляции 
                                  // с расширением и без пути
  outFilePath: string;            // путь для результирующего файла
    
  // пути к каталогам
  pathRoot: string;               // каталог проекта
  pathSources: string;            // каталог исходных файлов
  pathResources: string;          // каталог ресурсов
  pathBackup: string;             // каталог резервных копий
  pathBuild: string;              // каталог, куда сохранятся результаты компиляции
  pathPreprocessed: string;       // каталог, куда сохранятся файлы, 
                                  // обработанные препроцессором
  pathCompiled: string;           // каталог, куда сохранятся скомпилированные файлы
  pathPreverifed: string;         // каталог, куда сохранятся преверифицированные файлы
  pathObfuscated: string;         // каталог, куда сохранятся обфусцированные файлы
    
  // настройки компилятора
  compilerDebugInfo: Boolean;     // включать отладочную информацию
  compilerCompress: Boolean;      // сжимать результирующий файл
  compilerCbfuscation: Boolean;   // обфусцировать результирующий файл
  compilerOptimizationSize: string;// строка-название типа оптимизации при компиляции
    
  // манифесты java
  manifestIcon: string;           // путь к файлу иконки
  manifestVendor: string;         // имя производителя
  manifestVersion: string;        // версия мидлета
  manifestBuild: Integer;         // номер билда
  manifestDescription: string;    // описание
  manifestBuildAutoinc: Boolean;  // автоинкремент номера билда

  // платформа
  platformName: string;           // id платформы, для которой компилируется проект
  platformCaption: string;        // название платформы
  platformLang: string;           // язык программирования для платформы
    
  // устройство
  deviceName: string;             // id устройства, для которого компилируется проект
  deviceCaption: string;          // название устройства
  deviceScreenWidth: Integer;     // ширина экрана устройства
  deviceScreenHeight: Integer;    // высота экрана устройства
    
  // МЕТОДЫ
    
  function GetSourcesCount(): Integer;
  function GetSourceName(index : Integer): string;
  // получение числа исходных файлов и их полные имена
		
  function GetResourcesCount(): Integer;
  function GetResourceName(index : Integer): string;
  // получение числа ресурсных файлов и их полные имена
    
  function GetManifestRecCount(): Integer;
  function GetManifestRecord(index : Integer): TSManifestRec;
  // получение числа записей манифеста и их полные имена
    
  function GetDefinesCount(): Integer;
  function GetDefines(index : Integer): TSDefine;
  // получение числа и значений макроопределений для препроцессора
  // макроопределения могут быть переданы в командной строке, 
  //определены в конфигурации устройства и платформы
    
  function GetDefinesStr(): string;
  // возвращает список всех макроопределений в виде строки 
  // name1=value1;name2=value2;...
    
  function GetDefine(сonst name : string): string;
  function IsDefined(сonst name : string): Boolean;
  // получение значений макроопределений по имени и проверка того, 
  // что макрозначение было определено
    
  function GetLibrariesCount(): Integer;
  function GetLibrariesName(index : Integer): string;
  // получение путей к библиотечным файлам
  // пути к библиотекам указываются в файлах конфигурации устройств
  end;

TSExecuter = class
  // ПЕРЕМЕННЫЕ
  output: TStringList;     // тут возвращает список строк stdout
  errors: TStringList;     // тут возвращает список строк stderr
  resultCode: Integer;     // тут будет сохранен код возврата после выполнения
   
  // МЕТОДЫ
  function ExecuteTA(сonst path, commandLine : string; timeOut : Integer): Boolean;
  // выполняет утилиту
  // path - путь к программе, commandLine - аргументы командной строки,
  // timeOut - таймаут в миллисекундах
  // возвращает true в случае успеха
	 
  function Execute(сonst commandLine : string): Boolean;
  function ExecuteDir(сonst dir, fileName, commandLine : string): Boolean;
  // выполнение без таймаута
end;

TSPreprocessor = class
  // ПЕРЕМЕННЫЕ
  outputDirectory: string;   // каталог, куда будет сохранено собранное приложение
  outputFile: string;        // каталог, куда будет сохранено собранное приложение
  applicationName: string;   // название приложения
  applicationVersion: string;// версия приложения
  resourcesPath: string;     // путь к каталогу с файлами ресурсов
   
  // МЕТОДЫ
  procedure Define(сonst name, value : string);
  // определяет макроконстанту
	 
  procedure DefineList(сonst defines : string);;
  // определяет список макроопределений по строке вида 'DEFINE1;DEFINE2=val2;DEFINE3'
	 
  procedure Reset();
  // очищает все переменные объекта перед очередной операцией препроцессинга
	 
  function PreprocessFile(сonst sourceFileName, outputFileName : string): Boolean;
  // препроцессинг файла с сохранением результата. Возвращает true,
  // если не возникло ошибок
	 
  function PreprocessStrings(сonst source: TStringList; vаr 
             output : TStringList): Boolean;
  // препроцессит коллекцию строк сохраняя результат в виде коллекции. 
  // Возвращает true, если не возникло ошибок
	 
  function GetErrorsCount(): Integer;
  function GetErrors(index : Integer): TSErrorRec;
  // получение списка ошибок препроцессинга
	 
  function GetResourcesCount(): Integer;
  function GetErrors(index : Integer): TSResourceRec;
  // список файлов ресурсов, которые надо включить/исключить командами #make res+|- file
	 
  procedure UpdateProjectResources(prj : TSProject);
  // обновляет описание проекта после выполнения всех директив проепроцессора #make
   
  procedure SetIncludePaths(list : TStringList);
  procedure SetIncludePaths(list : TStringList);
  // задать списки директорий, в которых будут искаться заголовочные файлы 
  // и файлы библиотек
   
  function IsDefined(сonst name : string): Boolean;
  // возвращает true, если макрос с таким именем определен
  function GetDefine(сonst name : string): srting;
  // возвращает значение макроопределения
end;

TSFileReader = class
  // ПЕРЕМЕННЫЕ
  status: Boolean;       // true, если не возникло ошибок
   
  // МЕТОДЫ
  constructor Create(сonst fileName : string);
  // открывает файл
   
  procedure Close();
  // закрыть файл
  function Readln(): string;
  // читает строку до тех пор, пока не встретится символ конца строки
   
  function ReadByte(): Integer;
  function ReadWord(): Integer;
  function ReadDword(): Integer;
  // читают беззнаковые целые: 1, 2, 4 байта
   
  function ReadShortInt(): Integer;
  function ReadLongInt(): Integer;
  // читает знаковые целые: 2 и 4 байта
	 
  function ReadString(sizeBytes : Integer): string;
  // читает pascal-строку вида [длина, данные]. 
  //sizeBytes указывает, сколько первых байт выделено на хранение длины
	 
  function Size(): Integer;
  // возвращает размер файла
	 
  function Pos(): Integer;
  // возвращает текущую позицию в файле
	 
  procedure Seek(pos : Integer);
  // перевод текущей позиции
end;

TSFileWriter = class
  // ПЕРЕМЕННЫЕ
  status: Boolean;       // true, если не возникло ошибок
   
  // МЕТОДЫ
  constructor Create(сonst fileName : string);
  // создает файл
   
  procedure Close();
  // закрыть файл
  procedure Writeln(сonst str : string);
  // записывает строку и признак перехода к новой строке
   
  procedure Printf(сonst str : string; args: array of cоnst);
  // записывает строку (без end of line) с использованием FmtStr()
   
  procedure WriteByte(val : Integer);
  procedure WriteWord(val : Integer);
  procedure WriteDword(val : Integer);
  // записывают беззнаковые целые: 1, 2, 4 байта
   
  procedure WriteShortInt(val : ShortInt);
  procedure WriteLongInt(val : Integer);
  // записывает знаковые целые: 2 и 4 байта
   
  procedure WriteString(сonst str : string; sizeBytes: Integer);
  // записывает pascal-строку.
  // sizeBytes указывает, сколько байт выделено на хранение длины.
  // Байты длины сохраняются перед строкой
   
  function Size(): Integer;
  // возвращает размер файла
	 
  function Pos(): Integer;
  // возвращает текущую позицию в файле
	 
  procedure Seek(pos : Integer);
  // перевод текущей позиции
end;

TBase = class
  // МЕТОДЫ
  procedure Error(сonst msg, fileName : string; line, pos : Integer);
  // посылает сообщение об ошибке в IDE или консольному компилятору
	 
  procedure Warning(сonst msg, fileName : string; line, pos : Integer);
  // посылает сообщение о предупреждении в IDE или консольному компилятору
	 
  procedure Msg(сonst msg : string);
  // посылает информационное сообщение
	 
  procedure SetProgress(progress : Integer);
  // посылает сообщение о прогрессе компиляции в процентах. Обновляет индикатор IDE
	 
  procedure SetCurrentFile(сonst fileName : string);
  // определяет имя файла, который обрабатывается в данный момент. Выводится в окне IDE
	 
  function GetPath(сonst name : string): string;
  // получает путь по идентификатору переменной. 
  // Переменные объявляются в файлах /xml/paths/*.xml
end;

Обработка строк

  function WordCount(сonst str, delims : string): Integer;
  // возвращает количество слов в строке str для разделителей delims
	
  function ExtractWord(сonst str : string; n: Integer; delims): Integer;
  // возвращает слово под номером n в строке str для разделителей delims  
  // (нумерация от 1)
	
  function WordPosition(сonst str : string; n: Integer; delims): Integer;
  // возвращает позицию вхождения слова номер n в строке str для разделителей delims 
  // (нумерация от 1)
	
  function ExtractFileName(сonst path : string): string;
  // возвращает имя файла с расширением и без пути
	
  function ExtractFileNameOnly(сonst path : string): string;
  // возвращает только имя файла без расширением и без пути
	
  function ExtractFileExt(сonst path : string): string;
  // возвращает расширение файла (без точки)
	
  function ExtractFileDir(сonst path : string): string;
  // возвращает путь к файлу (без последнего слэша)
	
  procedure VerifySlash(vаr path : string);
  // проверяет, что имя директории содержит в конце слеш, 
  // все слэши соответствуют текущей системе (windows/linux)
	
  function LowerCase(сonst path : string): string;
  // переводит строку в нижний регистр
	
  function UpperCase(сonst path : string): string;
  // переводит строку в верхний регистр
	
  function VerifyInt(сonst path : string): Boolean;
  // возвращает true, если аргумент является правильным 
  // строковым представлением целого

Работа с файлами и каталогами

  function VerifyDir(сonst path : string): Boolean;
  // проверяет существование указанного каталога и создает его, если надо
  // возвращает TRUE, если каталог существовал и FALSE, если он был создан
	
  function DeleteFile(сonst fileMask : string): Boolean;
  // удаляет файл/файлы по маске
  // возвращает TRUE, если был удален хоть один файл
	
  function CopyFile(сonst srcPath, destPath : string): Boolean;
  // копирует файл
  // возвращает TRUE в случае успешного выполнения операции
	
  function RenameFile(сonst srcPath, destPath : string): Boolean;
  // переименовывает файл
  // возвращает TRUE в случае успешного выполнения операции
	
  function GetFileSize(сonst path : string): Integer;
  // возвращает размер файла или -1, если файл не существует
	
  function SetCurrentDir(сonst path : string): Boolean;
  // задает текущую директорию
  // возвращает TRUE в случае успешного выполнения операции
	
  function GetCurrentDir(): string;
  // возвращает текущую директорию

Вложеные теги:
defines
Содержит объявления макроопределений для устройства. Макроопределения перечислены в блоке в виде NAME=VALUE
libs
Содержит список файлов библиотек, которые будут использоваться при компиляции для этого устройства.
Если имя библиотеки начинается с '//', то путь отсчитывается относительно директории TRMS
run
Содержит сценарий запуска
Атрибуты:
system - определяет идентификатор операционной системы (win32/linux)
Внутри тега содержатся команды запуска приложения (или его эмулятора).
В командах можно использовать следующие параметры:
%FULLNAME% - полное имя файла скомпилированного приложения с путем
%FILEPATH% - полный путь к файлу (без завершающего слэша)
%FILENAME% - имя файла с расширением
%FILENAMEONLY% - имя файла без расширения

Корневой тег - Path, может содержать вложенные теги path, includes и libraries для определения путей к разным утилитам, заголовочным файлам и библиотекам соответственно. Внутри тега path каждый путь определяется тегом set.

Вложенные теги:
path
Определяет пути для компиляторов
Атрибуты:
system - определяет операционную систему (win32, linux)
Вложенный тег set определяет переменную
< set name= "name" value= "c:\java\jdk 1.6" >

includes и libraries
Определяет пути к файлам заголовков и библиотечным файлам
Атрибуты:
system - определяет операционную систему (win32, linux)

Если путь начинается с '//', то он будет отсчитываться относительно директории TRMS

Корневой тег - Platform содержит вложенные теги defines и compiler. Первый служит для определения макросов, которые будут переданы препроцессору на этой платформы, второй - для определения скрипта компиляции.

Тег Platform.
Атрибуты:
name - идентификатор платформы
caption - название платформы
lang - определяет язык программирования
Вложенные теги:
defines
Содержит объявления макроопределений для платформы. Макроопределения перечислены в стлоках тега в виде NAME=VALUE
compiler
Атрибуты:
system - определяет операционную систему (win32, linux)
script - имя файла скрипта компиляции для этой платформы и системы. Скрипт будет искаться в каталоге scripts

Тег Platform.
Атрибуты:
name - идентификатор проекта
description - описание шаблона
category - категория, к которой принадлежит проект
defaultdir - имя каталога, в который будет помещен созданный проект
Вложенные теги:
file
Добавляет файл к шаблону. Строки внутри этого тега будут сохранены в созданный файл,
а единственный атрибут name определяет имя создаваемого файла.
В имени файла и его строках можно использовать следующие параметры:
%FULLPROJECTFILE% - полное имя файла проекта (с путем)
%PROJECTFILE% - имя файла проекта (с расширением и без пути)
%FILENAME% - имя файла проекта (без расширения). Первая буква заглавная
%PACKAGENAME% - названи пакета (задумывалось для мидлетов). совпадает с %FILENAME%, только первая буква строчная
%PROJECTCAPTION% - название проекта
%PATH% - путь к проекту (со слэшем на конце)
%DATE% - текущая дата
%TIME% - текущее время
dir
Добавляет каталог к шаблону, атрибут name определяет имя создаваемого каталога.

Корневой тег проекта - Project служит контейнером для остальных тегов: paths, compiler, manifest, sources, resources, defines, package.

Атрибуты корневого тега Project:
name - имя проекта
outfile - имя выходного файла (по умолчанию, может быть изменено в коде)
caption - название проекта для IDE
device - идентификатор устройства по умолчанию

Атрибуты тега описания путей paths:
sources - путь к исходным файлам
resources - путь к файлам ресурсов
backup - путь к каталогу, в который IDE будет помещать резервные копии файлов
build - путь к каталогу, в который будет помещено собранное приложение
preprocessed - путь к каталогу, в который будут помещаться файлы, полученные после препроцессинга
compiled - путь к какталогу, в который будут помещаться файлы, полученные после компиляции
preverifed - путь к каталогу, в который будут помещаться файлы классов после преверификации (для j2me)
obfuscated - путь к каталогу, в который будут помещаться файлы, обработанные оптимизатором
Пути могут начинаться с '\', тогда они будут отсчитываться от корневой директории проекта

Атрибуты тега настроек компилятора compiler:
debuginfo - определяет, будет ли включаться отладочная информация в созданное приложение
compress - определяет, будет ли сжиматься .jar файл java-приложений
obfuscate - определяет, будет ли оптимизироваться/обфусцироваться файл приложения
optimization - определяет тип оптимизации приложения: size|speed

Атрибуты тега манифеста приложения manifest:
icon - определяет файл иконки приложения
vendor - определяет производителя приложения
version - версия приложения вида major.minor или major.minor.build
build - номер сборки приложения
description - описание приложения
buildautoinc - если установлен, то значение билда будет инкрементироваться при каждой сборке
Внутри тега manifest можно размещать теги записей key:
name - название параметра
value - значение параметра
target - для j2me приложений определяет, в каких манифестах будет определен этот ключ (jad|manifest)

Тег sources содержит строки - имена исходных файлов проекта

Тег resources содержит строки - имена ресурсных файлов проекта

Тег defines содержит строки - объявления макроконстант препроцессора вида name[=value]

Тег package определяет конфигурацию пакетной сборки приложения для группы устройств. Единственный атрибут name определяет название пакета. Тег служит контейнером для тегов release, каждый из которых описывает сборку приложение под одно устройство.
Атрибуты тега release:
name - название релиза
device - имя устройства, под который будет собран релиз
description - описание релиза
Внутри тега можно помещать определение макросов препроцессора вида name[=value]