diff --git a/NAPS2.Sdk/ImportExport/Placeholders.cs b/NAPS2.Sdk/ImportExport/Placeholders.cs index 995649e85..0a0f5f036 100644 --- a/NAPS2.Sdk/ImportExport/Placeholders.cs +++ b/NAPS2.Sdk/ImportExport/Placeholders.cs @@ -6,6 +6,10 @@ using System.Text.RegularExpressions; namespace NAPS2.ImportExport { + /// + /// Class for handling substitution of special values in file paths. For example, "$(YYYY)" can be substituted with the current year. + /// Use Placeholders.All for recommended substitutions. Alternatively, you can use Placeholders.Env or Placeholders.None if you prefer. + /// public abstract class Placeholders { public const string YEAR_4_DIGITS = "$(YYYY)"; @@ -20,12 +24,30 @@ namespace NAPS2.ImportExport public const string NUMBER_2_DIGITS = "$(nn)"; public const string NUMBER_1_DIGIT = "$(n)"; + /// + /// Substitutes all the standard placeholders. For example, "$(YYYY)-$(MM)-$(DD) $(hh):$(mm):$(ss)" is substituted with the current date and time. Substitutes environment variables. Handles auto-numbering for multiple files, + /// using the numeric placeholders ("$(n)", "$(nn)", "$(nnn)", or "$(nnnn)") if specified; otherwise, the number is appended to the file name. + /// public static DefaultPlaceholders All => new DefaultPlaceholders(); + /// + /// Substitutes environment variables in file names. Not recommended if you may be saving multiple files. + /// public static EnvironmentPlaceholders Env => new EnvironmentPlaceholders(); + /// + /// Does not make any changes to the file name. Not recommended if you may be saving multiple files. + /// public static StubPlaceholders None => new StubPlaceholders(); + /// + /// Performs substitutions on the given file path. + /// + /// The file path to perform substitutions on. + /// Whether to use an auto-incrementing file number to make the file name unique. + /// The file number will be at least one bigger than this value. + /// The minimum number of digits in the file number. Only has an effect if the path does not contain a numeric placeholder like $(n) or $(nnn). + /// The file path with substitutions. public abstract string Substitute(string filePath, bool incrementIfExists = true, int numberSkip = 0, int autoNumberDigits = 0); public class StubPlaceholders : Placeholders @@ -60,6 +82,11 @@ namespace NAPS2.ImportExport this.dateTimeOverride = dateTimeOverride; } + /// + /// Creates a copy of the DefaultPlaceholders object that will use the specified DateTime for date and time substitutions. + /// + /// The date and time to use. + /// The new DefaultPlaceholders object. public DefaultPlaceholders WithDate(DateTime dateTime) => new DefaultPlaceholders(dateTime); public override string Substitute(string filePath, bool incrementIfExists = true, int numberSkip = 0, int autoNumberDigits = 0)