allow multiple string placeholders to be altered from CLI call

Author: marco-foscato

README.md

@@ -105,6 +105,11 @@ To use a parameters' file, call AutoCompChem and give it the pathname to the par
 ```
 autocompchem -p <path_to_parameters_file>
 ```
+The content of a parameter file may also contain any number of placeholder strings that can be replaced upon calling AutoCompChem:
+```
+autocompchem -p <path_to_parameters_file> --replace <old_String>:<new_string> <other_placeholder>:<new_value>
+```
+where `<old_String>` and `<other_placeholder>` are two placeholder strings that will be replaces respectivly with `<new_string>` and `<new_value>`. 
 
 ##### Example
 The parameters file [examples/single_job.params](examples/single_job.params) defines a simple task meant to change the identity of any Cl atom into Br in a given SDF file:
@@ -151,12 +156,23 @@ To use a job details file, call AutoCompChem and give it the pathname to the job
 ```
 autocompchem -j <path_to_job_details_file>
 ```
-
 The job details file [examples/single_job.json](examples/single_job.json) defines the same job performed in the previous example, i.e., a job meant to change the identity of any Cl atom into Br in a given SDF file.
 Many other examples are available under the [test folder](test). However, note that the JSON format can be used to define many kinds on objects, including jobs that are not meant to be performed by AutoCompChem, e.g., any molecular modeling job. Therefore, not all ´.json´ files in the test folder define ACCJobs.
 
 JSON job details files can be conveniently generated from parameter's file (and vice versa) by the `convertJobDefinition` task.
 
+Notably, the parameters of the outermost job defined in the JSON file can be alterd by providing the correspodning CLI argument. Therefore, to re-run a job with a different input file we can use the wollowing:
+
+```
+autocompchem -j <path_to_job_details_file> --infile <path_to_new_input_file>
+```
+This possibility applies *only to the parameters of the outermost job in the JSON file*, settings of any nested job cannot be overwritten by the corresponding CLI arguments. However, a string replacement mechanism allows to directly replace strings in any part of the JSON or parameter's file from CLI upon reading such files:
+```
+autocompchem -j <path_to_job_details_file> --replace <old_String>:<new_string> <other_placeholder>:<new_value>
+```
+where `<old_String>` and `<other_placeholder>` are two placeholder strings that will be replaces respectivly with `<new_string>` and `<new_value>`. 
+
+
 ### Multiple Jobs
 AutoCompChem can also perform multiple tasks, hence *jobs*, whether in a sequence (i.e., a workflow), or in parallel (i.e., a batch). Either way, the list of jobs to perform, whether steps of a workflow or independent jobs to be performed in parallel, are defined within a job that acts as a container. Such container may itself be contained in a parent job resulting in a recursive structure.
 The distinction between serial and parallel execution is controlled by the jobs' container: if the container defines the `PARALLELIZE: <threads>` key-value pair, then the contained jobs will be executed in parallel using a number of asynchronous threads equal to the value specified by `<threads>`.

src/main/java/autocompchem/datacollections/ParameterConstants.java

@@ -138,13 +138,6 @@ public class ParameterConstants
 	 */
 	public static final String SITUATION = "SITUATION";
 
-	/**
-	 * Placeholder for a string defined via command line argument. This
-	 * placeholder string is replaced with the string given in CLI upon
-	 * importing parameters from a file.
-	 */
-	public static final String STRINGFROMCLI = "STRINGFROMCLI";
-
 	/**
 	 * Keyword of parameter defining tolerance towards info channels that are
 	 * defined by not readable.

src/main/java/autocompchem/run/JobFactory.java

@@ -2,11 +2,21 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.io.StringReader;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationTargetException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.AbstractMap.SimpleImmutableEntry;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import com.google.gson.JsonIOException;
+import com.google.gson.JsonSyntaxException;
 
 import org.apache.logging.log4j.core.config.Configurator;
 
@@ -15,6 +25,7 @@
 import autocompchem.files.ACCFileType;
 import autocompchem.utils.NumberUtils;
 import autocompchem.files.FileAnalyzer;
+import autocompchem.io.ACCJson;
 import autocompchem.io.IOtools;
 import autocompchem.log.LogUtils;
 import autocompchem.text.TextBlockIndexed;
@@ -96,70 +107,84 @@ public synchronized void registerType(Object object)
 
 	public static Job buildFromFile(File file) throws IOException
 	{
-		return buildFromFile(file, null);
+        Map<String, String> cliReplacements = new HashMap<>();
+		return buildFromFile(file, cliReplacements);
 	}
-	
+
 //------------------------------------------------------------------------------
-	
-    /**
-     * Build a {@link Job} from from an existing file.
-     * @param file the file from which to read the definition of the job.
-     * @param imposedStr a string that has to be used to replace 
-     * {@value ParameterConstants#STRINGFROMCLI} in the definition 
-     * of the job. This is a way to customize a general-purpose job definition 
-     * making it specific for the given string.
-     * @return the resulting job.
-     * @throws IOException if the file is not suitable for creating a Job.
-     */
-	
-	public static Job buildFromFile(File file, String imposedStr) throws IOException
+
+	/**
+	 * Build a {@link Job} from an existing file, applying optional string
+	 * replacements in file order before the job is parsed.
+	 *
+	 * @param file the file from which to read the definition of the job
+     * @param cliReplacements the key-value mapping for replacing the 
+     * string placeholders in the JSON file.
+	 * @return the resulting job
+	 * @throws IOException if the file is not suitable for creating a Job
+	 */
+	public static Job buildFromFile(File file,
+			Map<String, String> cliReplacements) throws IOException
 	{
-    	Job job = null;
-    	
-    	ACCFileType type = FileAnalyzer.detectFileType(file);
-    	switch (type)
-    	{
-    	case JSON:
-    		job = buildFromJSONFile(file, imposedStr);
-    		break;
-    		
-    	case PAR:
-    	case TXT:
-    		job = buildFromParametersFile(file, imposedStr);
-    		break;
-    		
+		Job job = null;
+
+		ACCFileType type = FileAnalyzer.detectFileType(file);
+		switch (type)
+		{
+		case JSON:
+			job = buildFromJSONFile(file, cliReplacements);
+			break;
+
+		case PAR:
+		case TXT:
+			job = buildFromParametersFile(file, cliReplacements);
+			break;
+
 		default:
 			throw new IllegalArgumentException("Format of file '" + file + "' does "
 					+ "not allow to create a Job. Please make sure the file is "
 					+ "either a JSON file or TXT parameters file adhering to "
 					+ "ACC format.");
-    	}
-    	return job;
+		}
+		return job;
 	}
-	
+
 //------------------------------------------------------------------------------
 
     /**
      * Build a {@link Job} from from an existing definition stored in a JSON
-     * file. It also
-     * allows you to given string that will replace the placeholder (i.e.,
-     * {@value ParameterConstants.STRINGFROMCLI}).
+     * file. It also allows to given string that will replace placeholders in
+     * the JSON file.
      * @param file the file from which to read the definition of the job.
-     * @param imposedStr  a string that has to be used to replace 
-     * {@value ParameterConstants#STRINGFROMCLI} in the definition 
-     * of the job. This is a way to customize a general-purpose job definition 
-     * making it specific for the given string.
+     * @param cliReplacements the key-value mapping for replacing the 
+     * string placeholders in the JSON file.
      * @return the resulting job.
      * @throws IOException is the file is not readable somehow.
      */
-
-    public static Job buildFromJSONFile(File file, String imposedStr) throws IOException
+    public static Job buildFromJSONFile(File file, Map<String, String> cliReplacements) throws IOException
     {
     	Object obj = null;
-    	if (imposedStr!=null)
+    	if (cliReplacements != null && !cliReplacements.isEmpty())
     	{
-    		obj = IOtools.readJsonFile(file, Job.class, 
-    				ParameterConstants.STRINGFROMCLI, imposedStr);
+    		String json = Files.readString(file.toPath(), StandardCharsets.UTF_8);
+    		for (String key : cliReplacements.keySet())
+    		{
+    			json = json.replace(key, cliReplacements.get(key));
+    		}
+    		try
+    		{
+    			obj = ACCJson.getReader().fromJson(new StringReader(json), Job.class);
+    		}
+    		catch (JsonSyntaxException jse)
+    		{
+    			throw new IOException("JSON file '" + file
+    					+ "' has illegal syntax: " + jse.getMessage(), jse);
+    		}
+    		catch (JsonIOException jio)
+    		{
+    			throw new IOException("Error reading JSON from '" + file + "': "
+    					+ jio.getMessage(), jio);
+    		}
     	} else {
     		obj = IOtools.readJsonFile(file, Job.class);
     	}
@@ -179,19 +204,15 @@ public static Job buildFromJSONFile(File file, String imposedStr) throws IOExcep
     /**
      * Build a {@link Job} from from an existing definition stored in a 
      * text file adhering to the format of ACC's parameter's file. It also
-     * allows you to given string that will replace the placeholder (i.e.,
-     * {@value ParameterConstants.STRINGFROMCLI}).
+     * allows to given string that will replace placeholders in the text file.
      * @param file the file from which to read the definition of the job.
-     * @param imposedStr  a string that has to be used to replace 
-     * {@value ParameterConstants#STRINGFROMCLI} in the definition 
-     * of the job. This is a way to customize a general-purpose job definition 
-     * making it specific for the given string.
-     * @return the resulting job
-     * @throws IOException if the file is not readable
+     * @param cliReplacements the key-value mapping for replacing the 
+     * string placeholders in the text file.
+     * @return the resulting job.
+     * @throws IOException if the file is not suitable for creating a Job.
      */
-
-    public static Job buildFromParametersFile(File file, String imposedStr) 
-		throws IOException
+    public static Job buildFromParametersFile(File file,
+    		Map<String, String> cliReplacements) throws IOException
     {
         List<TextBlockIndexed> blocks = FileAnalyzer.extractTextBlocks(
         		file,
@@ -200,11 +221,11 @@ public static Job buildFromParametersFile(File file, String imposedStr)
                 false,  //don't take only first
                 false); //don't include delimiters
 
-        if (imposedStr != null && !imposedStr.isBlank())
+        if (cliReplacements != null && !cliReplacements.isEmpty())
         {
 	        for (TextBlockIndexed tb : blocks)
 	        {
-	        	tb.replaceAll(ParameterConstants.STRINGFROMCLI,imposedStr);
+	        	applyCliReplacements(tb, cliReplacements);
 	        }
         }
 
@@ -216,13 +237,26 @@ public static Job buildFromParametersFile(File file, String imposedStr)
         	lines.add(ParameterConstants.RUNNABLEAPPIDKEY 
         			+ ParameterConstants.SEPARATOR + SoftwareId.ACC);
         	TextBlockIndexed tb = new TextBlockIndexed(lines, 0, 0, 0);
-        	if (imposedStr != null && !imposedStr.isBlank())
-        		tb.replaceAll(ParameterConstants.STRINGFROMCLI,imposedStr);
+        	if (cliReplacements != null && !cliReplacements.isEmpty())
+        		applyCliReplacements(tb, cliReplacements);
         	blocks.add(tb);
         }
 
         return createJob(blocks);
     }
+
+//------------------------------------------------------------------------------
+
+	private static void applyCliReplacements(TextBlockIndexed tb,
+			Map<String, String> cliReplacements)
+	{
+		for (String key : cliReplacements.keySet())
+		{
+			String regex = Pattern.quote(key);
+			String replacement = Matcher.quoteReplacement(cliReplacements.get(key));
+			tb.replaceAll(regex, replacement);
+		}
+	}
 
 //-----------------------------------------------------------------------------