Task #485: Add factory IFoldersConfiguration builder 'Folders' for co…

…nvenience (#490)

Make it easier to configure custom folder configurations when using grate as a library.

Solves #485

src/grate.core/Configuration/Folders.cs

@@ -0,0 +1,73 @@
+namespace grate.Configuration;
+
+/// <summary>
+/// Factory class for creating <see cref="IFoldersConfiguration"/> instances.
+/// </summary>
+public static class Folders
+{
+ /// <summary>
+ /// The default <see cref="IFoldersConfiguration"/>.
+ /// </summary>
+ public static IFoldersConfiguration Default => FoldersConfiguration.Default();
+
+ /// <summary>
+ /// An empty <see cref="IFoldersConfiguration"/>.
+ /// </summary>
+ public static IFoldersConfiguration Empty => FoldersConfiguration.Empty;
+
+ /// <summary>
+ /// Folder configuration with the specified folders.
+ /// </summary>
+ /// <param name="folders">A list of migration folders</param>
+ /// <returns>An IFoldersConfiguration with the supplied folders</returns>
+ public static IFoldersConfiguration Create(params MigrationsFolder [] folders) 
+ => new FoldersConfiguration(folders);
+
+ /// <summary>
+ /// Folder configuration with the specified folders.
+ /// </summary>
+ /// <param name="folders">A list of migration folders</param>
+ /// <returns>An IFoldersConfiguration with the supplied folders</returns>
+ public static IFoldersConfiguration Create(IEnumerable<MigrationsFolder> folders) 
+ => new FoldersConfiguration(folders);
+
+ /// <summary>
+ /// Folder configuration with the specified Dictionary of folder names and folders.
+ /// </summary>
+ /// <param name="folders">A Dictionary of folder names and migration folders</param>
+ /// <returns>An IFoldersConfiguration with the supplied folders</returns>
+ public static IFoldersConfiguration Create(IDictionary<string, MigrationsFolder> folders) 
+ => new FoldersConfiguration(folders);
+
+ /// <summary>
+ /// Folder configuration from strings, where each string is a folder configuration, as
+ /// you can specify on the command line.
+ ///
+ /// For convenience, you can specify each folder in a separate string, instead of all in one string, separated by a semicolon.
+ ///
+ /// For example:
+ ///
+ /// <code>
+ /// Create("structure=relativePath:myCustomFolder,type:Once,connectionType:Admin",
+ /// "randomstuff=type:Once;procedures=type:Once;security=type:Once")
+ /// </code>
+ /// 
+ /// </summary>
+ /// <param name="folders">Separate strings with folder configurations</param>
+ /// <returns>An IFoldersConfiguration with the supplied folders</returns>
+ public static IFoldersConfiguration Create(params string[] folders) 
+ => FoldersCommand.Parse(string.Join(";", folders));
+
+ /// <summary>
+ /// Folder configuration from strings, where each string is a folder configuration, as
+ /// you can specify on the command line.
+ /// 
+ /// You specify multiple folders in one string, separated by a semicolon.
+ ///
+ /// For example: "structure=relativePath:myCustomFolder,type:Once,connectionType:Admin;randomstuff=type:Once;procedures=type:Once;security=type:Once"
+ /// </summary>
+ /// <param name="folders">A semicolon separated string with all the folder configurations, as specified on the command line</param>
+ /// <returns>An IFoldersConfiguration with the supplied folders</returns>
+ public static IFoldersConfiguration Create(string folders) 
+ => FoldersCommand.Parse(folders);
+}

src/grate/Commands/FoldersCommand.cs → src/grate.core/Configuration/FoldersCommand.cs

@@ -1,8 +1,7 @@
 using System.Reflection;
-using grate.Configuration;
 using grate.Exceptions;
 
-namespace grate.Commands;
+namespace grate.Configuration;
 
 internal static class FoldersCommand
 {

src/grate.core/Configuration/GrateConfigurationBuilder.cs

@@ -51,7 +51,12 @@ public GrateConfigurationBuilder WithOutputFolder(string outputFolder)
  /// names of the folders and the migration type. Default is the grate default folder configuration,
  /// using 'up', 'functions', 'views', 'sprocs', 'triggers', 'indexes', 'permissions' and 'after_migration'.
  /// </summary>
- /// <param name="folders">A folder configuration to use. Can be DefaultConfiguration with some modifications.</param>
+ /// 
+ /// <param name="folders">A folder configuration to use. Can be DefaultConfiguration with some modifications,
+ /// a fully customized folder set, or a slightly modified one.
+ ///
+ /// Please see the static helper class <see cref="Folders"/> with factory methods for creating folder configurations.</param>
+ /// 
  /// <returns>GrateConfigurationBuilder</returns>
  public GrateConfigurationBuilder WithFolders(IFoldersConfiguration folders)
  {

unittests/Basic_tests/CommandLineParsing/FolderConfiguration_.cs

@@ -20,7 +20,7 @@ public async Task Default()
  var cfg = await ParseGrateConfiguration("--sqlfilesdirectory=/tmp");
  _ = cfg?.SqlFilesDirectory ?? new DirectoryInfo("/tmp");
 
- var expected = FoldersConfiguration.Default(null);
+ var expected = Folders.Default;
  var actual = cfg?.Folders;
 
  AssertEquivalent(expected.Values, actual?.Values);

unittests/Basic_tests/DependencyInjection/GrateConfigurationBuilder_Factory.cs

@@ -1,4 +1,5 @@
-using FluentAssertions;
+using System.Collections.Immutable;
+using FluentAssertions;
 using grate.Configuration;
 using grate.Infrastructure;
 using Microsoft.Extensions.DependencyInjection;
@@ -11,7 +12,6 @@ public class GrateConfigurationBuilder_Factory
  [Fact]
  public void Creates_default_builder_with_non_interactive()
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  var grateConfiguration = builder.Build();
  grateConfiguration.NonInteractive.Should().Be(true);
@@ -23,7 +23,6 @@ public void Creates_default_builder_with_output_folder(string outputFolder)
  {
  var outputDir = Directory.CreateDirectory(outputFolder);
  WriteSql(Wrap(outputDir, "views"), "01_test_view.sql", "create view v_test as select 1");
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithOutputFolder(outputFolder);
  var grateConfiguration = builder.Build();
@@ -38,7 +37,6 @@ public void Creates_default_builder_with_sql_folder(string sqlFolder)
  {
  var sqlDir = Directory.CreateDirectory(sqlFolder);
  WriteSql(Wrap(sqlDir, "views"), "01_test_view.sql", "create view v_test as select 1");
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithSqlFilesDirectory(sqlFolder);
  var grateConfiguration = builder.Build();
@@ -51,7 +49,6 @@ public void Creates_default_builder_with_sql_folder(string sqlFolder)
  [InlineData("roundhouse")]
  public void Creates_default_builder_with_schema(string schemaName)
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithSchema(schemaName);
  var grateConfiguration = builder.Build();
@@ -63,7 +60,6 @@ public void Creates_default_builder_with_schema(string schemaName)
  [InlineData("Data source=whatever;Database=;")]
  public void Creates_default_builder_with_connection_string(string connectionString)
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithConnectionString(connectionString);
  var grateConfiguration = builder.Build();
@@ -75,7 +71,6 @@ public void Creates_default_builder_with_connection_string(string connectionStri
  [InlineData("Data source=whatever;Database=master;")]
  public void Creates_default_builder_with_admin_connection_string(string adminConnectionString)
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithAdminConnectionString(adminConnectionString);
  var grateConfiguration = builder.Build();
@@ -87,16 +82,15 @@ public void Creates_default_builder_with_admin_connection_string(string adminCon
  [InlineData("1.0.0.0")]
  public void Creates_default_builder_with_version(string version)
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithVersion(version);
  var grateConfiguration = builder.Build();
  grateConfiguration.Version.Should().Be(version);
  }
+
  [Fact]
  public void Creates_default_builder_with_do_not_create_database()
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.DoNotCreateDatabase();
  var grateConfiguration = builder.Build();
@@ -106,7 +100,6 @@ public void Creates_default_builder_with_do_not_create_database()
  [Fact]
  public void Creates_default_builder_with_transaction()
  {
- var serviceCollection = new ServiceCollection();
  var builder = GrateConfigurationBuilder.Create();
  builder.WithTransaction();
  var grateConfiguration = builder.Build();
@@ -128,4 +121,18 @@ public void Creates_default_builder_with_environment_name(string environmentName
  grateConfiguration.Environment.Should().BeEquivalentTo(new GrateEnvironment(environmentName));
  }
 
+ [Fact]
+ public void Creates_default_builder_with_custom_folder_configuration()
+ {
+ var builder = GrateConfigurationBuilder.Create()
+ .WithFolders(Folders.Create("up=ddl", "views=binoculars"));
+ var grateConfiguration = builder.Build();
+
+ var folders = grateConfiguration.Folders!;
+ folders.Should().HaveCount(Folders.Default.Count);
+
+ folders[KnownFolderKeys.Up]!.Path.Should().Be("ddl");
+ folders[KnownFolderKeys.Views]!.Path.Should().Be("binoculars");
+ }
+
 }

unittests/Basic_tests/Infrastructure/FileSystem_.cs

@@ -12,7 +12,7 @@ public class FileSystem_
  public void Sorts_enumerated_files_on_filename_when_no_subfolders()
  {
  var parent = TestConfig.CreateRandomTempDirectory();
- var knownFolders = FoldersConfiguration.Default(null);
+ var knownFolders = Folders.Default;
 
  var path = Wrap(parent, knownFolders[KnownFolderKeys.Up]!.Path);
 
@@ -32,7 +32,7 @@ public void Sorts_enumerated_files_on_filename_when_no_subfolders()
  public void Sorts_enumerated_files_on_filename_without_extension_when_no_subfolders()
  {
  var parent = TestConfig.CreateRandomTempDirectory();
- var knownFolders = FoldersConfiguration.Default(null);
+ var knownFolders = Folders.Default;
 
  var path = Wrap(parent, knownFolders[KnownFolderKeys.Up]!.Path);
 
@@ -52,7 +52,7 @@ public void Sorts_enumerated_files_on_filename_without_extension_when_no_subfold
  public void Sorts_enumerated_files_on_sub_path_when_subfolders_are_used()
  {
  var parent = TestConfig.CreateRandomTempDirectory();
- var knownFolders = FoldersConfiguration.Default(null);
+ var knownFolders = Folders.Default;
 
  var path = Wrap(parent, knownFolders[KnownFolderKeys.Up]!.Path);
 
@@ -75,7 +75,7 @@ public void Sorts_enumerated_files_on_sub_path_when_subfolders_are_used()
  public void Sorts_enumerated_files_on_filename_when_directory_names_are_ignored()
  {
  var parent = TestConfig.CreateRandomTempDirectory();
- var knownFolders = FoldersConfiguration.Default(null);
+ var knownFolders = Folders.Default;
 
  var path = Wrap(parent, knownFolders[KnownFolderKeys.Up]!.Path);
 

unittests/Basic_tests/Infrastructure/FolderConfiguration/Customized_Folders_Can_Be_Set_Programmatically.cs

@@ -0,0 +1,115 @@
+using System.Collections.Immutable;
+using FluentAssertions;
+using grate.Configuration;
+
+namespace Basic_tests.Infrastructure.FolderConfiguration;
+
+// ReSharper disable once InconsistentNaming
+public class Customized_Folders_Can_Be_Set_Programmatically
+{
+ [Fact]
+ public void From_MigrationsFolder_list()
+ {
+ var folders = Folders.Create(
+ new MigrationsFolder("structure"),
+ new MigrationsFolder("randomstuff"),
+ new MigrationsFolder("procedures"),
+ new MigrationsFolder("security")
+ );
+ var items = folders.Values.ToImmutableArray();
+
+ Assert.Multiple(() =>
+ {
+ items[0].Should().Be(folders["structure"]);
+ items[1].Should().Be(folders["randomstuff"]);
+ items[2].Should().Be(folders["procedures"]);
+ items[3].Should().Be(folders["security"]);
+ });
+ }
+
+ [Fact]
+ public void From_Enumerable_of_MigrationsFolder()
+ {
+ var folders = Folders.Create(new List<MigrationsFolder>
+ {
+ new("structure"),
+ new("randomstuff"),
+ new("procedures"),
+ new("security")}
+ );
+ var items = folders.Values.ToImmutableArray();
+
+ Assert.Multiple(() =>
+ {
+ items[0].Should().Be(folders["structure"]);
+ items[1].Should().Be(folders["randomstuff"]);
+ items[2].Should().Be(folders["procedures"]);
+ items[3].Should().Be(folders["security"]);
+ });
+ }
+
+ [Fact]
+ public void From_Dictionary_of_MigrationsFolder()
+ {
+ var folders = Folders.Create(new Dictionary<string, MigrationsFolder>
+ {
+ {"structure", new("str") },
+ {"randomstuff", new("rnd") },
+ {"procedures", new("procs") },
+ {"security", new("sec") }
+ }
+ );
+ var items = folders.Values.ToImmutableArray();
+
+ Assert.Multiple(() =>
+ {
+ items[0].Should().Be(folders["structure"]);
+ items[1].Should().Be(folders["randomstuff"]);
+ items[2].Should().Be(folders["procedures"]);
+ items[3].Should().Be(folders["security"]);
+ });
+ }
+
+
+ [Fact]
+ public void From_command_line_argument_style_single_string()
+ {
+ var folders = Folders.Create("nup=tables;sprocs=storedprocedures;views=projections");
+ var items = folders.ToImmutableArray();
+
+ Assert.Multiple(() =>
+ {
+ items[0].Key.Should().Be("nup");
+ items[0].Value!.Path.Should().Be("tables");
+ 
+ items[1].Key.Should().Be("sprocs");
+ items[1].Value!.Path.Should().Be("storedprocedures");
+ 
+ items[2].Key.Should().Be("views");
+ items[2].Value!.Path.Should().Be("projections");
+ });
+ }
+
+ [Fact]
+ public void From_multiple_string_arguments()
+ {
+ var folders = Folders.Create("zup=tables", "sprocs=path:storedprocedures,type:anytime", "views=projections");
+ var items = folders.ToImmutableArray();
+
+ Assert.Multiple(() =>
+ {
+ items[0].Key.Should().Be("zup");
+ items[0].Value!.Path.Should().Be("tables");
+ 
+ items[1].Key.Should().Be("sprocs");
+ items[1].Value!.Path.Should().Be("storedprocedures");
+ items[1].Value!.Type.Should().Be(MigrationType.AnyTime);
+ 
+ items[2].Key.Should().Be("views");
+ items[2].Value!.Path.Should().Be("projections");
+ });
+ }
+
+
+
+}

unittests/Basic_tests/Infrastructure/FolderConfiguration/KnownFolders_Default.cs

@@ -59,7 +59,7 @@ TransactionHandling transactionHandling
  }
 
  private static readonly DirectoryInfo Root = TestConfig.CreateRandomTempDirectory();
- private static readonly IFoldersConfiguration Folders = FoldersConfiguration.Default(null);
+ private static readonly IFoldersConfiguration Folders = global::grate.Configuration.Folders.Default;
 
  public static IEnumerable<object?[]> ExpectedKnownFolderNames()
  {

unittests/Basic_tests/Infrastructure/TokenReplacerTests.cs

@@ -37,7 +37,7 @@ public void EnsureTokensAreReplaced()
  [Fact]
  public void EnsureConfigMakesItToTokens()
  {
- var folders = FoldersConfiguration.Default(null);
+ var folders = Folders.Default;
  var config = new GrateConfiguration() { SchemaName = "Test", Folders = folders };
  var provider = new TokenProvider(config, Substitute.For<IDatabase>());
  var tokens = provider.GetTokens();

unittests/CommandLine/CommandLine.MariaDB/Running_MigrationScripts/One_time_scripts.cs

@@ -20,7 +20,7 @@ public override async Task Fails_if_changed_between_runs()
  var db = TestConfig.RandomDatabase();
 
  var parent = CreateRandomTempDirectory();
- var knownFolders = FoldersConfiguration.Default(null);
+ var knownFolders = Folders.Default;
  CreateDummySql(parent, knownFolders[Up]);
 
  var config = GrateConfigurationBuilder.Create(Context.DefaultConfiguration)

unittests/CommandLine/CommandLine.Oracle/Running_MigrationScripts/One_time_scripts.cs

@@ -22,7 +22,7 @@ public override async Task Fails_if_changed_between_runs()
  var db = TestConfig.RandomDatabase();
 
  var parent = CreateRandomTempDirectory();
- var knownFolders = FoldersConfiguration.Default(null);
+ var knownFolders = Folders.Default;
  CreateDummySql(parent, knownFolders[Up]);
 
  var config = GrateConfigurationBuilder.Create(Context.DefaultConfiguration)