More documentation written.

Author: Nestor Soriano Vilchez

NestorMSX.BuiltInPlugins/SlotPlugins/DiskImageBasedStoragePlugin.cs

@@ -75,7 +75,7 @@ public DiskImageBasedStoragePlugin(PluginContext context, IDictionary<string, ob
                 .Select(f => StringExtensions.AsAbsolutePath(f, basePathForDiskImages))
                 .ToArray();
 
-            this.slotNumber = new SlotNumber(pluginConfig.GetValue<byte>("slotNumber"));
+            this.slotNumber = new SlotNumber(pluginConfig.GetValue<byte>("NestorMSX.slotNumber"));
 
             var machineName = pluginConfig.GetValue<string>("NestorMSX.machineName");
             stateFileFullPath = $"{machineName}/{PluginDisplayName} in slot {slotNumber}.dat".AsAbsolutePath();

NestorMSX.Infrastructure/Misc/DictionaryUtils.cs NestorMSX.Infrastructure/Misc/DictionaryExtensions.cs

@@ -6,7 +6,7 @@
 
 namespace Konamiman.NestorMSX.Misc
 {
-    public static class DictionaryUtils
+    public static class DictionaryExtensions
     {
         /// <summary>
         /// Gets the value of the configuration for the specified key, converted
@@ -140,21 +140,21 @@ private static T AdaptValue<T>(string key, object value)
             return (T)AdaptValue(typeof(T), key, value);
         }
 
-        private static object AdaptValue(Type type, string key, object value)
+        private static object AdaptValue(Type destinationType, string key, object value)
         {
             if(value == null)
                 return null;
 
-            if(type.IsInstanceOfType(value))
+            if(destinationType.IsInstanceOfType(value))
                 return value;
 
-            if(type.IsArray)
+            if(destinationType.IsArray)
             {
                 if(!value.GetType().IsArray)
                     throw new ConfigurationException($"Configuration key '{key}' has value '{value.ToString()}', that can't be converted to an array");
 
                 var originalArray = (Array)value;
-                var arrayItemsType = type.GetElementType();
+                var arrayItemsType = destinationType.GetElementType();
 
                 var arrayLength = originalArray.GetLength(0);
                 var adaptedArray = Array.CreateInstance(arrayItemsType, arrayLength);
@@ -168,10 +168,10 @@ private static object AdaptValue(Type type, string key, object value)
             object[] convertMethodArguments;
             if(value is string)
             {
-                convertMethod = GetConvertMethod(type, new[] {typeof(string), typeof(int)});
+                convertMethod = GetConvertMethod(destinationType, new[] {typeof(string), typeof(int)});
                 if(convertMethod == null)
                 {
-                    convertMethod = GetConvertMethod(type, new[] {typeof(object)});
+                    convertMethod = GetConvertMethod(destinationType, new[] {typeof(object)});
                     convertMethodArguments = new object[] { value };
                 }
                 else
@@ -187,12 +187,12 @@ private static object AdaptValue(Type type, string key, object value)
             }
             else
             {
-                convertMethod = GetConvertMethod(type, new[] { typeof(object) });
+                convertMethod = GetConvertMethod(destinationType, new[] { typeof(object) });
                 convertMethodArguments = new object[] { value };
             }
 
             if(convertMethod == null)
-                throw new ConfigurationException($"Configuration key '{key}' has value '{value.ToString()}', that can't be converted to '{type.Name}'");
+                throw new ConfigurationException($"Configuration key '{key}' has value '{value.ToString()}', that can't be converted to '{destinationType.Name}'");
 
             try
             {
@@ -201,7 +201,7 @@ private static object AdaptValue(Type type, string key, object value)
             catch(TargetInvocationException ex)
             {
                 throw new ConfigurationException(
-                    $"Error when converting value {value.ToString()} for key '{key}' to {type.Name}: {ex.InnerException.Message}",
+                    $"Error when converting value {value.ToString()} for key '{key}' to {destinationType.Name}: {ex.InnerException.Message}",
                     ex.InnerException);
             }
         }

NestorMSX.Infrastructure/NestorMSX.Infrastructure.csproj

@@ -69,7 +69,7 @@
     <Compile Include="Memories\PlainRam.cs" />
     <Compile Include="Memories\PlainRom.cs" />
     <Compile Include="Menus\MenuEntry.cs" />
-    <Compile Include="Misc\DictionaryUtils.cs" />
+    <Compile Include="Misc\DictionaryExtensions.cs" />
     <Compile Include="Misc\SlotNumber.cs" />
     <Compile Include="Misc\StringExtensions.cs" />
     <Compile Include="Misc\TwinBit.cs" />

NestorMSX/Emulator/MsxEmulationEnvironment.cs

@@ -222,7 +222,7 @@ private void CreateSlotsSystem()
                     continue;
 
                 var pluginConfig = (IDictionary<string, object>)slotConfig.Value;
-                pluginConfig["slotNumber"] = slotNumber.EncodedByte;
+                pluginConfig["NestorMSX.slotNumber"] = slotNumber.EncodedByte;
 
                 var typeName = (string)pluginConfig["type"];
 

PluginDevelopmentGuide.md

@@ -153,3 +153,35 @@ The supplied `PluginContext` instance is what allows the plugin to really do som
 Note that the `PluginContext` class has a `EnvironmentInitializationComplete` event. If your plugin needs to access the loaded plugins list or the slots system, it shouldn't do so until this event is fired. Note also that plugins aren't loaded/initialized in any particular order.
 
 Please take a look at the `PluginContext` class itself for more details.
+
+
+## The plugin configuration ##
+
+The `pluginConfig` argument passed to the plugin class constructor or to the `GetInstance` method contains all the configuration that the user has supplied for the plugin in either the global _NestorMSX.config_ file or the specific _machine.config_ file. It is a dictionary that represents a direct translation of the JSON object that represents the plugin configuration. Values that are in turn JSON objects are supplied as nested dictionaries in turn.
+
+Rather than accessing the supplied dictionary directly, it is recommended to use the extension methods that are available in [the DictionaryExtensions class](NestorMSX.Infrastructure/Misc/DictionaryExtensions.cs), being the most important ones:
+
+* **GetValue<T>(key):** Gets the value of the specified key, appropriately converted to the specified type T. [The standard Convert class](https://msdn.microsoft.com/en-us/library/system.convert) is used to perform the conversion from string to T, and a special handling is in place for arrays. An exception is thrown if the key does not exist.
+
+* **GetValueOrDefault<T>(key):** Same as above, but the supplied default value is returned if the key does not exist.
+
+* **GetDictionaryOrDefault(key):** Returns the value of the specified key as a dictionary. If the key does not exist it returns an empty dictionary. If the key exists but the value is not a dictionary, an exception is thrown.
+
+* **MergeInto(destination):** Copies all the key/value pairs into the destination dictionary, but only for the keys that don't already exist. Useful to inject default values in the supplied configuration dictionary.
+
+* **GetMachineFilePath, GetMachineOrDataFilePath:** These methods are useful to find plugin-specific files when relative paths are supplied.
+
+See also [the StringExtensions class](NestorMSX.Infrastructure/Misc/StringExtensions.cs).
+
+
+### Injected configuration ###
+
+Besides containing the configuration object supplied by the user as a JSON object in the global or machine configuration file, `pluginConfig` contains also some extra values that are injected by NestorMSX and can be useful for the plugin. These are:
+
+* **"NestorMSX.machineName"**: Contains the name of the machine currently running.
+* **"NestorMSX.machineDirectory"**: Contains the full path of the directory where the `machine.config` file for the currently running machine is.
+* **"NestorMSX.sharedDirectory"**: Contains the full path of the _Shared_ subdirectory in the machines directory. Note that this directory is examined automatically as needed if you use the `GetMachineFilePath` and `GetMachineOrDataFilePath` methods.
+* **"NestorMSX.applicationDirectory"**: Contains the full path of the _NestorMSX.exe_ file.
+* **"NestorMSX.slotNumber"**: This value is injected only for plugins that are plugged in a slot. It contains the slot number where the plugin is, as one byte in the standard format (slot + 4*subslot + 128 if slot is expanded).
+
+Future versions of NestorMSX could inject more values, but the names of these will always start with "NestorMSX."