Implement filePathPattern in the script configuration with handling

also
- tests
- extending kdoc for the definitions

libraries/scripting/common/src/kotlin/script/experimental/annotations/scriptAnnotations.kt

@@ -25,6 +25,9 @@ import kotlin.script.experimental.api.ScriptEvaluationConfiguration
  * @param fileExtension distinct filename extension for the script type being defined, stored in the configuration
  *        as {@link ScriptCompilationConfigurationKeys#fileExtension},
  *        default - "kts"
+ * @param filePathPattern additional (to the filename extension) RegEx pattern with that the script file path is checked
+ *        as {@link ScriptCompilationConfigurationKeys#filePathPattern},
+ *        default - empty - pattern is not used
  * @param compilationConfiguration an object or a class with default constructor containing initial script compilation configuration
  *        default - {@link ScriptCompilationConfiguration#Default}
  * @param evaluationConfiguration an object or a class with default constructor containing initial script evaluation configuration
@@ -47,6 +50,7 @@ import kotlin.script.experimental.api.ScriptEvaluationConfiguration
 annotation class KotlinScript(
     val displayName: String = "Kotlin script",
     val fileExtension: String = "kts",
+    val filePathPattern: String = "",
     val compilationConfiguration: KClass<out ScriptCompilationConfiguration> = ScriptCompilationConfiguration.Default::class,
     val evaluationConfiguration: KClass<out ScriptEvaluationConfiguration> = ScriptEvaluationConfiguration.Default::class
 )

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
  */

libraries/scripting/common/src/kotlin/script/experimental/host/configurationFromTemplate.kt

@@ -78,6 +78,9 @@ private fun ScriptCompilationConfiguration.Builder.propertiesFromTemplate(
     if (fileExtension() == null) {
         fileExtension(mainAnnotation.fileExtension)
     }
+    if (filePathPattern() == null) {
+        filePathPattern(mainAnnotation.filePathPattern)
+    }
     if (displayName() == null) {
         displayName(mainAnnotation.displayName)
     }