Примечание. Данная документация может не успевать отражать изменения, вносимые в M++ API в процессе сопровождения и развития M++. Наиболее точную справочную информацию по конкретной версии M++ можно получить запустив утилиту mxxc с ключем -api.
Примечание. Данная глава описывает только функции M++ API без привязки к конкретным шаблонам. Шаблоны M++ для конкретных языков программирования реализованы на основе описываемых ниже функций, но для изучения деталей реализации шаблонов необходимо обратиться к самим файлам шаблонов.
string cpp_add_file( string file ); string cpp_add_file( string[] files );
Добавляет указанное имя файла (вектор имен файлов) в список имен файлов для анализатора C++ зависимостей. Анализатор C++ зависимостей будет осуществлять анализ только тех файлов, имена которых были ему переданы посредством функций cpp_app_file.
string cpp_add_include_path( string path ); string cpp_add_include_path( string[] paths );
Добавляет указанное имя каталога (вектор имен каталогов) в список имен каталогов стандартных заголовочных файлов для анализатора C++ зависимостей. Когда анализатор C++ зависимостей встречает директиву #include <имя_файла>, то он пытается найти файл имя_файла в каталогах, имена которых были указаны посредством функции cpp_add_include_path.
string[] cpp_query_dependences_for( string file );
Возвращает список файлов, которые загружаются (напрямую или опосредованно) в указанном C++ файле. Получить этот список можно только после успешного завершения работы анализатора C++ зависимостей.
string cpp_run_analyzer();
Запуск анализатора C++ зависимостей. Возвращает empty в случае успешного завершения анализа.
string io_file_close( string descriptor );
Закрывает файл, открытый ранее функцией io_file_create или io_file_open. Возвращает empty в случае успеха. После успешного завершения файловый дескриптор становится недействительным. Если файл не был закрыт явно, он закрывается автоматически при завершении программы.
string io_file_create( string name );
Создает файл с указанным именем или переписывает его, если такой файл уже существует. Возвращает дескриптор созданного файла (специальное представление дескриптора) или empty, если создать файл не удалось.
Дескриптор созданного файла затем можно использовать в функциях io_print, io_file_close.
string io_file_open( string name );
Открывает существующий файл с указанным именем для дописывания информации в конец файла. Возвращает дескриптор открытого файла (специальное представление дескриптора) или empty, если открыть файл не удалось.
Дескриптор открытого файла затем можно использовать в функциях io_print, io_file_close.
string io_print( string s ); string io_print( string file_descriptor, string s );
Первая функция помещает указанную строку в стандартный поток вывода. Вторая функция помещает указанную строку в файл, открытый ранее функцией io_file_create или io_file_open.
string io_print_err( string s );
Помещает указанную строку в стандартный поток ошибок.
string make_build_node( string node );
Запускает построение цели с указанным в параметре node именем на основании сформированных make-правил. Возвращает empty, если построение цели прошло успешно.
string make_define_node( string node, string[] dependences, string[] build_cmds ); string make_define_node( string[] nodes, string[] dependences, string[] build_cmds );
Формирует make-правила для указанной цели (целей). Если для цели уже было сформировано make-правило, то оно заменяется на новое. Вторая функция формирует одинаковые make-правила для всех указанных целей.
Параметры:
string make_is_node_exists( string node );
Проверяет наличие make-правила для указанной в параметре node цели. Возвращает empty, если make-правила не существует или отличное от empty значение, если make-правило существует.
string make_print_tree_from( string node );
Отображает на стандартный поток вывода make-правила для указанной в параметре node цели и всех целей, от которых зависит указанная цель. Печать осуществляется в "родном" формате утилиты make.
string[] make_query_node_build_cmds( string node );
Возвращает список команд для построения указанной в параметре node цели (т.е. возвращается часть make-правила, описывающая создание цели). Данная функция может применятся для модификации уже сформированного make-правила - возвращенный вектор нужным образом изменяется, а затем make-правило модифицируется посредством make_define_node.
string[] make_query_node_dependences( string node );
Возвращает список файлов (целей), от которых зависит указанная в параметре node цель (т.е. возвращается часть make-правила, описывающая зависимости цели). Данная функция может применятся для модификации уже сформированного make-правила - возвращенный вектор нужным образом изменяется, а затем make-правило модифицируется посредством make_define_node.
string[] mxxc_query_cmd_line_args();
Возвращает вектор аргументов командной строки утилиты mxxc (т.е. те аргуметны, которые были указаны утилите mxxc при запуске данной программы). В возвращаемый вектор попадают только аргументы -u, -d, -i и имена response-файлов. Данная функция может использоваться для запуска утилиты mxxc из программы с тем же самым набором параметров, как для текущей программы (например, для построения вспомогательных проектов).
string mxxc_query_main_file();
Возвращает имя стартовой единицы компиляции (имя файла заданое в аргументе командной строки -f, выведеное из аргумента командной строки -sf или default.4xx).
string mxxc_set_exit_code( string exit_code );
Устанавливает код возврата для утилиты mxxc. Утилита mxxc в своем коде возврата указывает несколько успешно была скомпилирована программа (правильные ли аргументы для mxxc, найден ли файл программы, скомпилирован ли файл программы и т.д.). Для того, чтобы указать, что в процессе своего выполнения программа не выполнила своей задачи (например, не скомпилировала проект) необходимо явно установить код возврата mxxc.
Параметр exit_code должен содержать десятичное представление кода возврата. Возвращается предыдущее значение кода возврата или empty, если в параметре exit_code содержится некорректное значение.
string str_array_to_str( string[] what ); string str_array_to_str( string[] what, string delimiter );
Первая функция преобразует значение вектора строк в одну строку, разделяя отдельные элементы вектора пробелом. Вторая функция преобразует значение вектора строк в одну строку, разделяя отдельные элементы разделителем, указанным в параметре delimeter. После последнего элемента вектора разделитель не указывается.
string str_correct_path_separators( string full_name ); string[] str_correct_path_separators( string[] full_names );
Преобразует разделители имен каталогов в указанном имени файла (векторе имен файлов) на принятые на данной платформе разделители. Возвращаются преобразованные значения.
string str_escape_encode( string what ); string[] str_escape_encode( string[] what );
Возвращает преобразованную строку, значение которой может использоваться в исходном тексте mxx-программы. Специальные и пепечатаемые символы заменяются на соответствующие escape-последовательности. Результат в двойные кавычки не обрамляется.
string str_exclude_file_ext( string full_name );
Возвращает путь к файлу и имя файла без расширения (т.е. удаляет последнее расширение). Например, для /home/mxx-api.1.1.htm возвращается /home/mxx-api.1.1.
string str_exclude_file_path( string full_name );
Возвращает имя файла и расширение без пути к файлу (т.е. удаляет путь к файлу). Например, для c:\file\my-file.txt возвращается my-file.txt.
string str_extract_file_ext( string full_name );
Возвращает расширение имени файла (последнее из расширений, включая точку). Например, для /home/mxx-api.1.1.htm возвращается .htm.
string str_extract_file_name( string full_name );
Возвращает имя файла (без пути и последнего расширения). Например, для /home/mxx-api.1.1.htm возвращается mxx-api.1.1.
string str_extract_file_path( string full_name );
Возвращает путь к файлу без завершающего слэша.
Например:
для filename возвращается .
для filename.ext возвращается .
для c:filename.ext возвращается c:
для c:\filename.ext возвращается c:
для /home/eao/filename.ext возвращается /home/eao
для filename.ext.ext2 возвращается .
для .ext возвращается .
для c:\ возвращается c:
string sys_change_cwd( string path );
Изменяет текущий рабочий каталог на каталог, указанный в параметре path. Возвращает empty в случае успеха.
string sys_change_file_mtime( string file_name, string mtime );
Изменяет для указанного файла время модификации. Возвращает empty в случае успеха.
Параметры:
string sys_exists( string path_or_file_name );
Проверяет существование файла или каталога, имя которого указывается в параметре path_or_file_name. Возвращает empty, если файл (каталог) существует.
string[] sys_find_directories( string start_path, string[] masks, string[] exclude_items );
Осуществляет поиск имен каталогов, находящихся в указаном каталоге, и возвращает список найденых имен.
Параметры:
Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.
Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".
string[] sys_find_directories_subdir( string start_path, string[] masks, string[] exclude_dirs, string[] exclude_items );
Осуществляет поиск имен каталогов, находящихся в указаном каталоге и его подкаталогах, и возвращает список найденых имен.
Параметры:
Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.
Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".
string[] sys_find_files( string start_path, string[] masks, string[] exclude_files );
Осуществляет поиск имен файлов, находящихся в указаном каталоге, и возвращает список найденых имен.
Параметры:
Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.
Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".
string[] sys_find_files_subdir( string start_path, string[] masks, string[] exclude_dirs, string[] exclude_files );
Осуществляет поиск имен файлов, находящихся в указаном каталоге и его подкаталогах, и возвращает список найденых имен.
Параметры:
Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.
Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".
string sys_get_cwd();
Возвращает имя текущего рабочего каталога.
string sys_get_env( string var_name );
Возвращает значение переменной среды с именем, указанной в параметре var_name. Если переменная среды не задана, то возвращается empty.
string sys_get_file_atime( string file_name );
Возвращает время последнего доступа к указанному файлу. Возвращается т.н. unix-время в специальном внутреннем представлении.
string sys_get_file_ctime( string file_name );
Возвращает время создания указанного файла. Возвращается т.н. unix-время в специальном внутреннем представлении.
string sys_get_file_mtime( string file_name );
Возвращает время последней модификации указанного файла. Возвращается т.н. unix-время в специальном внутреннем представлении.
string sys_get_file_size( string file_name );
Возвращает десятичное представление размера указанного файла в байтах.
string sys_remove( string file_name );
Удаляет файл с именем, указанным в параметре file_name. Возвращается empty в случае успеха.
string sys_run( string cmd );
Запускает внешнюю команду (программу). Параметр cmd содержит имя команды и, если необходимо, параметры командной строки. Возвращается десятичное представление кода возврата программы (т.е. если внешняя программа завершилась успешно, то будет возвращено "0").
string utime_is_later_than( string time1, string time2 );
Возвращается отличное от empty значение, если время time1 является более поздним временем, чем time2. Сравниваются внутренние представления времени, возвращаемые функциями sys_get_file_atime, sys_get_file_ctime, sys_get_file_mtime.
string utime_to_str( string time );
Возвращается текстовое представление внутреннего представления времени, аналогичное функции ctime в C/C++. Например: Wed Jan 02 02:03:55 1980. Предназначена для работы со значениями, возвращаемыми функциями sys_get_file_atime, sys_get_file_ctime, sys_get_file_mtime.