Implement filePathPattern in the script configuration with handling

also
- tests
- extending kdoc for the definitions

libraries/scripting/common/src/kotlin/script/experimental/api/scriptCompilation.kt

@@ -3,7 +3,7 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
-@file:Suppress("unused")
+@file:Suppress("unused", "RemoveExplicitTypeArguments")
 
 package kotlin.script.experimental.api
 
@@ -59,9 +59,21 @@ val ScriptCompilationConfigurationKeys.displayName by PropertiesCollection.key<S
 
 /**
  * The script filename extension
+ * Used for the primary script definition selection as well as to assign a kotlin-specific file type to the files with the extension in Intellij IDEA
+ * For Intellij IDEA support, it is important to have this extension set to a non-ambiguous name.
+ * See also {@link ScriptCompilationConfigurationKeys#filePathPattern} parameter for more fine-grained script definition selection
  */
 val ScriptCompilationConfigurationKeys.fileExtension by PropertiesCollection.key<String>("kts")
 
+/**
+ * Additional (to the filename extension) RegEx pattern with that the script file path is checked
+ * It is used in the hosts that may have several script definitions registered and need to distinguish script file types not only by extension
+ * The argument passed to the RegEx matcher is equivalent to the File.path, taken relatively from a base path defined by the host
+ * (usually should be the project root or the current directory)
+ * See also {@link ScriptCompilationConfigurationKeys#fileExtension} parameter for the primary script definition selection
+ */
+val ScriptCompilationConfigurationKeys.filePathPattern by PropertiesCollection.key<String>()
+
 /**
  * The superclass for target script class
  */