8. M++ API

Примечание. Данная документация может не успевать отражать изменения, вносимые в M++ API в процессе сопровождения и развития M++. Наиболее точную справочную информацию по конкретной версии M++ можно получить запустив утилиту mxxc с ключем -api.

Примечание. Данная глава описывает только функции M++ API без привязки к конкретным шаблонам. Шаблоны M++ для конкретных языков программирования реализованы на основе описываемых ниже функций, но для изучения деталей реализации шаблонов необходимо обратиться к самим файлам шаблонов.

8.1. cpp_add_file

string
cpp_add_file( string file );

string
cpp_add_file( string[] files );

Добавляет указанное имя файла (вектор имен файлов) в список имен файлов для анализатора C++ зависимостей. Анализатор C++ зависимостей будет осуществлять анализ только тех файлов, имена которых были ему переданы посредством функций cpp_app_file.

8.2. cpp_add_include_path

string
cpp_add_include_path( string path );

string
cpp_add_include_path( string[] paths );

Добавляет указанное имя каталога (вектор имен каталогов) в список имен каталогов стандартных заголовочных файлов для анализатора C++ зависимостей. Когда анализатор C++ зависимостей встречает директиву #include <имя_файла>, то он пытается найти файл имя_файла в каталогах, имена которых были указаны посредством функции cpp_add_include_path.

8.3. cpp_query_dependences_for

string[]
cpp_query_dependences_for( string file );

Возвращает список файлов, которые загружаются (напрямую или опосредованно) в указанном C++ файле. Получить этот список можно только после успешного завершения работы анализатора C++ зависимостей.

8.4. cpp_run_analyzer

string
cpp_run_analyzer();

Запуск анализатора C++ зависимостей. Возвращает empty в случае успешного завершения анализа.

8.5. io_file_close

string
io_file_close( string descriptor );

Закрывает файл, открытый ранее функцией io_file_create или io_file_open. Возвращает empty в случае успеха. После успешного завершения файловый дескриптор становится недействительным. Если файл не был закрыт явно, он закрывается автоматически при завершении программы.

8.6. io_file_create

string
io_file_create( string name );

Создает файл с указанным именем или переписывает его, если такой файл уже существует. Возвращает дескриптор созданного файла (специальное представление дескриптора) или empty, если создать файл не удалось.

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

8.7. io_file_open

string
io_file_open( string name );

Открывает существующий файл с указанным именем для дописывания информации в конец файла. Возвращает дескриптор открытого файла (специальное представление дескриптора) или empty, если открыть файл не удалось.

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

8.8. io_print

string
io_print( string s );

string
io_print( string file_descriptor, string s );

Первая функция помещает указанную строку в стандартный поток вывода. Вторая функция помещает указанную строку в файл, открытый ранее функцией io_file_create или io_file_open.

8.9. io_print_err

string
io_print_err( string s );

Помещает указанную строку в стандартный поток ошибок.

8.10. make_build_node

string
make_build_node( string node );

Запускает построение цели с указанным в параметре node именем на основании сформированных make-правил. Возвращает empty, если построение цели прошло успешно.

8.11. make_define_node

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-правила для всех указанных целей.

Параметры:

node
имя цели;
nodes
вектор имен целей;
dependences
вектор имен файлов (целей) от которых зависит данная цель;
build_cmds
вектор с командами построения цели. Команды запускаются последовательно, в том порядке, в котором они указаны. Цель считается построенной, если все команды завершились с нулевым кодом возврата.

8.12. make_is_node_exists

string
make_is_node_exists( string node );

Проверяет наличие make-правила для указанной в параметре node цели. Возвращает empty, если make-правила не существует или отличное от empty значение, если make-правило существует.

8.13. make_print_tree_from

string
make_print_tree_from( string node );

Отображает на стандартный поток вывода make-правила для указанной в параметре node цели и всех целей, от которых зависит указанная цель. Печать осуществляется в "родном" формате утилиты make.

8.14. make_query_node_build_cmds

string[]
make_query_node_build_cmds( string node );

Возвращает список команд для построения указанной в параметре node цели (т.е. возвращается часть make-правила, описывающая создание цели). Данная функция может применятся для модификации уже сформированного make-правила - возвращенный вектор нужным образом изменяется, а затем make-правило модифицируется посредством make_define_node.

8.15. make_query_node_dependences

string[]
make_query_node_dependences( string node );

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

8.16. mxxc_query_cmd_line_args

string[]
mxxc_query_cmd_line_args();

Возвращает вектор аргументов командной строки утилиты mxxc (т.е. те аргуметны, которые были указаны утилите mxxc при запуске данной программы). В возвращаемый вектор попадают только аргументы -u, -d, -i и имена response-файлов. Данная функция может использоваться для запуска утилиты mxxc из программы с тем же самым набором параметров, как для текущей программы (например, для построения вспомогательных проектов).

8.17. mxxc_query_main_file

string
mxxc_query_main_file();

Возвращает имя стартовой единицы компиляции (имя файла заданое в аргументе командной строки -f, выведеное из аргумента командной строки -sf или default.4xx).

8.18. mxxc_set_exit_code

string
mxxc_set_exit_code( string exit_code );

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

Параметр exit_code должен содержать десятичное представление кода возврата. Возвращается предыдущее значение кода возврата или empty, если в параметре exit_code содержится некорректное значение.

8.19. str_array_to_str

string
str_array_to_str( string[] what );

string
str_array_to_str( string[] what, string delimiter );

Первая функция преобразует значение вектора строк в одну строку, разделяя отдельные элементы вектора пробелом. Вторая функция преобразует значение вектора строк в одну строку, разделяя отдельные элементы разделителем, указанным в параметре delimeter. После последнего элемента вектора разделитель не указывается.

8.20. str_correct_path_separators

string
str_correct_path_separators( string full_name );

string[]
str_correct_path_separators( string[] full_names );

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

8.21. str_escape_encode

string
str_escape_encode( string what );

string[]
str_escape_encode( string[] what );

Возвращает преобразованную строку, значение которой может использоваться в исходном тексте mxx-программы. Специальные и пепечатаемые символы заменяются на соответствующие escape-последовательности. Результат в двойные кавычки не обрамляется.

8.22. str_exclude_file_ext

string
str_exclude_file_ext( string full_name );

Возвращает путь к файлу и имя файла без расширения (т.е. удаляет последнее расширение). Например, для /home/mxx-api.1.1.htm возвращается /home/mxx-api.1.1.

8.23. str_exclude_file_path

string
str_exclude_file_path( string full_name );

Возвращает имя файла и расширение без пути к файлу (т.е. удаляет путь к файлу). Например, для c:\file\my-file.txt возвращается my-file.txt.

8.24. str_extract_file_ext

string
str_extract_file_ext( string full_name );

Возвращает расширение имени файла (последнее из расширений, включая точку). Например, для /home/mxx-api.1.1.htm возвращается .htm.

8.25. str_extract_file_name

string
str_extract_file_name( string full_name );

Возвращает имя файла (без пути и последнего расширения). Например, для /home/mxx-api.1.1.htm возвращается mxx-api.1.1.

8.26. str_extract_file_path

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:

8.27. sys_change_cwd

string
sys_change_cwd( string path );

Изменяет текущий рабочий каталог на каталог, указанный в параметре path. Возвращает empty в случае успеха.

8.28. sys_change_file_mtime

string
sys_change_file_mtime( string file_name, string mtime );

Изменяет для указанного файла время модификации. Возвращает empty в случае успеха.

Параметры:

file_name
имя файла;
mtime
новое время последней модификации файла (в специальном внутреннем формате).

8.29. sys_exists

string
sys_exists( string path_or_file_name );

Проверяет существование файла или каталога, имя которого указывается в параметре path_or_file_name. Возвращает empty, если файл (каталог) существует.

8.30. sys_find_directories

string[]
sys_find_directories( string start_path,
	string[] masks,
	string[] exclude_items );

Осуществляет поиск имен каталогов, находящихся в указаном каталоге, и возвращает список найденых имен.

Параметры:

start_path
каталог, в котором необходимо искать подкаталоги. Если в имени каталога нет завершающего слэша, то он автоматически добавляется. Поэтому, для поиска в текущем каталоге необходимо указать ".", что будет преобразовано в "./" или ".\", в зависимости от платформы. Если же указать пустую строку "", то она будет преобразована в "/" или "\", что означает поиск в корневом каталоге;
masks
список масок для поиска. Маски для поиска не должны содержать путей - т.е. это должны быть только маски имен и расширений (например, *.cpp, *.tmp, но не prj/*.tmp);
exclude_items
вектор имен, которые необходимо исключить из результирующего списка. Может содержать маски. Результирующие имена будут иметь в качестве префикса имени имя каталога из параметра start_path (например, "./name" или "c:\start_path\name"), поэтому в exclude_items нужно указывать такой же префикс. Т.е. если в текущем каталоге ищутся подкаталоги и нужно исключить из них все имена "*.tmp", то в exclude_items нужно указать "./*.tmp".

Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.

Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".

8.31. sys_find_directories_subdir

string[]
sys_find_directories_subdir( string start_path,
	string[] masks,
	string[] exclude_dirs,
	string[] exclude_items );

Осуществляет поиск имен каталогов, находящихся в указаном каталоге и его подкаталогах, и возвращает список найденых имен.

Параметры:

start_path
каталог, в котором необходимо искать подкаталоги. Если в имени каталога нет завершающего слэша, то он автоматически добавляется. Поэтому, для поиска в текущем каталоге необходимо указать ".", что будет преобразовано в "./" или ".\", в зависимости от платформы. Если же указать пустую строку "", то она будет преобразована в "/" или "\", что означает поиск в корневом каталоге;
masks
список масок для поиска. Маски для поиска не должны содержать путей - т.е. это должны быть только маски имен и расширений (например, *.cpp, *.tmp, но не prj/*.tmp);
exclude_dirs
список имен каталогов, поиск в которых вестись не должен. Может содержать маски. При поиске имена найденых каталогов будут иметь в качестве префикса имени имя каталога из параметра start_path (например, "./name" или "c:\start_path\name"), поэтому в exclude_dirs нужно указывать такой же префикс. Т.е. если в текущем каталоге ищутся подкаталоги и нужно исключить из просмотра подкаталоги с именами "*.tmp", то в exclude_items нужно указать "./*.tmp". Если же указать "./0.tmp/*", то будут найдены все подкаталоги каталога "0.tmp" (и попадут в результирующий список), но они просматриваться не будут.
exclude_items
вектор имен, которые необходимо исключить из результирующего списка. Может содержать маски. Результирующие имена будут иметь в качестве префикса имени имя каталога из параметра start_path (например, "./name" или "c:\start_path\name"), поэтому в exclude_items нужно указывать такой же префикс. Т.е. если в текущем каталоге ищутся подкаталоги и нужно исключить из них все имена "*.tmp", то в exclude_items нужно указать "./*.tmp".

Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.

Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".

8.32. sys_find_files

string[]
sys_find_files( string start_path,
	string[] masks,
	string[] exclude_files );

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

Параметры:

start_path
каталог, в котором необходимо искать файлы. Если в имени каталога нет завершающего слэша, то он автоматически добавляется. Поэтому, для поиска в текущем каталоге необходимо указать ".", что будет преобразовано в "./" или ".\", в зависимости от платформы. Если же указать пустую строку "", то она будет преобразована в "/" или "\", что означает поиск в корневом каталоге;
masks
список масок для поиска. Маски для поиска не должны содержать путей - т.е. это должны быть только маски имен и расширений (например, *.cpp, *.tmp, но не prj/*.tmp);
exclude_files
вектор имен, которые необходимо исключить из результирующего списка. Может содержать маски. Результирующие имена будут иметь в качестве префикса имени имя каталога из параметра start_path (например, "./name" или "c:\start_path\name"), поэтому в exclude_files нужно указывать такой же префикс. Т.е. если в текущем каталоге ищутся файлы и нужно исключить из них все имена "*.tmp", то в exclude_files нужно указать "./*.tmp".

Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.

Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".

8.33. sys_find_files_subdir

string[]
sys_find_files_subdir( string start_path,
	string[] masks,
	string[] exclude_dirs,
	string[] exclude_files );

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

Параметры:

start_path
каталог, в котором необходимо искать файлы. Если в имени каталога нет завершающего слэша, то он автоматически добавляется. Поэтому, для поиска в текущем каталоге необходимо указать ".", что будет преобразовано в "./" или ".\", в зависимости от платформы. Если же указать пустую строку "", то она будет преобразована в "/" или "\", что означает поиск в корневом каталоге;
masks
список масок для поиска. Маски для поиска не должны содержать путей - т.е. это должны быть только маски имен и расширений (например, *.cpp, *.tmp, но не prj/*.tmp);
exclude_dirs
список имен каталогов, поиск в которых вестись не должен. Может содержать маски. При поиске имена найденых каталогов будут иметь в качестве префикса имени имя каталога из параметра start_path (например, "./name" или "c:\start_path\name"), поэтому в exclude_dirs нужно указывать такой же префикс. Т.е. если в текущем каталоге ищутся файлы и нужно исключить из просмотра подкаталоги с именами "*.tmp", то в exclude_items нужно указать "./*.tmp". Если же указать "./0.tmp/*", то будут найдены все файлы каталога "0.tmp" (и попадут в результирующий список), но подкаталоги каталога "0.tmp" просматриваться не будут.
exclude_files
вектор имен, которые необходимо исключить из результирующего списка. Может содержать маски. Результирующие имена будут иметь в качестве префикса имени имя каталога из параметра start_path (например, "./name" или "c:\start_path\name"), поэтому в exclude_items нужно указывать такой же префикс. Т.е. если в текущем каталоге ищутся файлы и нужно исключить из них все имена "*.tmp", то в exclude_items нужно указать "./*.tmp".

Примечание. В масках имен можно указывать только символы * и ?. При этом символы * и ? заменяют любые символы, включая и разделители имен каталогов. Т.е. маске n*.tmp будут удовлетворять имена n000.tmp, name/000.tmp, nnn/mmm/kkk/lll.tmp и т.д.

Примечание.Поиск по маске "*.*" на платформах Win32 и OS/2 традиционно возвращает все имена, даже те, у которых нет расширения. На платформе UNIX поиск по той же маске вернет только имена у которых есть расширения. В M++ API реализован UNIX-подход - т.е. для поиска всех имен (имеющих или не имеющих расширения) необходимо указать маску "*".

8.34. sys_get_cwd

string
sys_get_cwd();

Возвращает имя текущего рабочего каталога.

8.35. sys_get_env

string
sys_get_env( string var_name );

Возвращает значение переменной среды с именем, указанной в параметре var_name. Если переменная среды не задана, то возвращается empty.

8.36. sys_get_file_atime

string
sys_get_file_atime( string file_name );

Возвращает время последнего доступа к указанному файлу. Возвращается т.н. unix-время в специальном внутреннем представлении.

8.37. sys_get_file_ctime

string
sys_get_file_ctime( string file_name );

Возвращает время создания указанного файла. Возвращается т.н. unix-время в специальном внутреннем представлении.

8.38. sys_get_file_mtime

string
sys_get_file_mtime( string file_name );

Возвращает время последней модификации указанного файла. Возвращается т.н. unix-время в специальном внутреннем представлении.

8.39. sys_get_file_size

string
sys_get_file_size( string file_name );

Возвращает десятичное представление размера указанного файла в байтах.

8.40. sys_remove

string
sys_remove( string file_name );

Удаляет файл с именем, указанным в параметре file_name. Возвращается empty в случае успеха.

8.41. sys_run

string
sys_run( string cmd );

Запускает внешнюю команду (программу). Параметр cmd содержит имя команды и, если необходимо, параметры командной строки. Возвращается десятичное представление кода возврата программы (т.е. если внешняя программа завершилась успешно, то будет возвращено "0").

8.42. utime_is_later_than

string
utime_is_later_than( string time1, string time2 );

Возвращается отличное от empty значение, если время time1 является более поздним временем, чем time2. Сравниваются внутренние представления времени, возвращаемые функциями sys_get_file_atime, sys_get_file_ctime, sys_get_file_mtime.

8.43. utime_to_str

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.

Hosted by uCoz