Utils.pm -- some useful helper subroutines.
This module provides general helper subroutines such as parsing config or data files.
Utils::exec_cmd(cmd,
description [,
log_ref])Runs a system command and indicates whether it succeeded or failed.
This subroutine captures the output (stdout) of the command and only logs that output to stderr if the command fails or if Constants::DEBUG is set to true.
This subroutine converts exit codes into boolean values,
i.e.,
it returns 1 if the command succeeded and 0 otherwise.
If the optional reference log_ref is provided,
the captured output is stored in that variable.
Utils::get_tmp_dir([tmp_root])Returns tmp_root/scriptname_process_id_timestamp
This directory is unique in a local file system.
The root directory to be used can be specified with tmp_root (optional).
The default is D4J_TMP_DIR.
Utils::get_abs_path(dir)Returns the absolute path to the directory dir.
Utils::get_dir(file)Returns the directory of the absolute path of file.
Utils::append_to_file_unless_matches(file,
string,
regexp)This utility method appends string to file,
unless file contains a line that matches regexp.
This is done in a way that is safe for multiple processes accessing file by acquiring flocks.
Utils::files_in_commit(repo_dir,
commit)Returns an array of files changed in commit in the git repository repo_dir.
Utils::print_entry(key,
val)Print a key-value pair for a single-line value.
For instance,
print_entry("SHELL",
"/bin/bash") will print the following to stdout:
SHELL................./bin/bash
Utils::print_multiline_entry(key, val [, vals...])Print a key-value pair for a multi-line value. For instance, print_multiline_entry("Java Version", `java -version`) will print something like the following to stderr:
Java Version:
openjdk version "1.8.0_232"
OpenJDK Runtime Environment (AdoptOpenJDK)(build 1.8.0_232-b09)
OpenJDK 64-Bit Server VM (AdoptOpenJDK)(build 25.232-b09, mixed mode)
Utils::print_environment_var(var)Lookup an environment variable's value and print it to stderr.
Utils::print_envPrint relevant environment variables to stderr.
Utils::write_config_file(filename, config_hash)Writes all key-value pairs of config_hash to a config file named filename. Existing entries are overridden and missing entries are added to the config file -- all existing but unmodified entries are preserved.
Utils::read_config_file(filename [, key_separator])Read all key-value pairs of the config file named filename. Format: key=value. Returns a hash containing all key-value pairs on success, undef otherwise.
Utils::tag_prefix(pid, bid)Returns the Defects4J prefix for tagging a buggy or fixed program version.
Utils::bug_report_info(pid, vid)Returns the bug report ID and URL of a given project id pid and version id vid. In case there is not any bug report ID/URL available for a specific project id pid and version id, it returns "NA".
Utils::check_vid(vid)Check whether vid represents a valid version id, i.e., matches \d+[bf].
This subroutine terminates with an error message if vid is not valid. Otherwise, it returns a hash that maps bid to the bug id that was parsed from the provided vid, and type to the version type (b or f) that was parsed from the provided vid.
For instance, to check that this is a valid bug and extract the bug-id on success, write:
my bid = Utils::check_vid(vid)->{bid};
Utils::ensure_valid_bid(pid, bid)Ensure bid represents a valid bug-id in project pid, terminating with a detailed error message if not. A bug-id is valid for a project if the project exists and the bug-id both exists in the project and is active.
Utils::ensure_valid_vid(pid, vid)Ensure vid represents a valid version-id in project pid, terminating with a detailed error message if not. A version-id is valid for a project if the project exists, the version-id is of the form d+[bf], and the underlying bug-id, represented by the leading integer part of the version id, both exists in the project and is active.
Utils::has_failing_tests(test_result_file)Returns 1 if the provided test_result_file lists any failing test classes or failing test methods. Returns 0 otherwise.
Utils::get_failing_tests(test_result_file)Determines all failing test classes and test methods in test_result_file, which may contain arbitrary lines. A line indicating a test failure matches the following pattern: /--- ([^:]+)(::([^:]+))?/.
This subroutine returns a reference to a hash that contains three keys (classes, methods, and asserts), which map to lists of failing tests:
{classes} => [org.foo.Class1 org.bar.Class2]
{methods} => [org.foo.Class3::method1 org.foo.Class3::method2]
{asserts} => {org.foo.Class3::method1} => 4711
Utils::get_all_test_suites(suite_dir, pid [, vid])Determines all Defects4J test suite archives that exist in suite_dir and that match the given project id (pid) and version id (vid). Note that vid is optional.
This subroutine returns a reference to a hierarchical hash that holds all matching test suite archives:
$result->{vid}->{suite_src}->{test_id}->{file_name}
Utils::extract_test_suite(test_suite, test_dir)Extracts an archive of an external test suite (test_suite) into a given test directory (test_dir). The directory test_dir is created if it doesn't exist. This subroutine returns 1 on success, 0 otherwise.
Utils::clean_test_results(work_dir)Remove any old test results in the provided work_dir.