Merge pull request #649 from Systems-Modeling/ST6RI-823

ST6RI-823 Support extending Jupyter integration with additional magic commands

Author: seidewitz

org.omg.sysml.interactive/src/org/omg/sysml/interactive/SysMLInteractive.java

@@ -282,7 +282,7 @@ public String help(String command) {
 	public String repo(String apiBasePath, List<String> help) {
 		this.counter++;
 		if (!help.isEmpty()) {
-			return SysMLInteractiveHelp.getApiBasePathHelp();
+			return SysMLInteractiveHelp.getRepoPathHelp();
 		}
 
 		if (!Strings.isNullOrEmpty(apiBasePath)) {

org.omg.sysml.interactive/src/org/omg/sysml/interactive/SysMLInteractiveHelp.java

@@ -21,46 +21,42 @@
  *
  * Contributors:
  *  Ed Seidewitz, MDS
- *  Ivan Gomes
- *  Hisashi Miyashita
+ *  Zoltan Ujhelyi, MDS
+ *  Ivan Gomes, Twingineer
+ *  Hisashi Miyashita, Mgnite
  *
  *******************************************************************************/
 
 package org.omg.sysml.interactive;
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.TreeMap;
 
 import org.omg.sysml.plantuml.SysML2PlantUMLStyle;
 
+import com.google.common.base.Preconditions;
+
 public class SysMLInteractiveHelp {
 
-	private static final String GENERAL_HELP_STRING =
+	private static final String GENERAL_HELP_STRING_PREFIX =
 			  "The following SysML v2 magic commands are available.\n"
 			+ "For help on a specific command, use \"%help <COMMAND>\" or \"%<cmd> -h\".\n\n"
-			+ "%eval\t\tEvaluate a given expression.\n"
-			+ "%export\t\tSave a file of the JSON representation of the abstract syntax tree rooted in the named element.\n"
-			+ "%help\t\tGet a list of available commands or help on a specific command\n"
-			+ "%list\t\tList loaded library packages or the results of a given query\n"
-			+ "%load\t\tLoad a model from the repository\n"
-			+ "%repo\t Set the api base path for the repository\n"
-			+ "%show\t\tPrint the abstract syntax tree rooted in a named element\n"
-			+ "%projects\tList projects in the repository\n"
-			+ "%publish\tPublish to the repository the modele elements rooted in a named element\n"
-			+ "%view\t\tRender the view specified by the named view usage\n"
-			+ "%viz\t\tVisualize the name model elements\n"
 			;
 
+	private static final String HELP_HELP_SHORT_STRING = "%help\t\tGet a list of available commands or help on a specific command";
 	private static final String HELP_HELP_STRING =
 			  "Usage: %help [<COMMAND>]\n\n"
 			+ "Print help information on the named SysML v2 magic <COMMAND>.\n"
 			+ "If no <COMMAND> is given, then list the available commands.\n";
 
+	private static final String EVAL_HELP_SHORT_STRING = "%eval\t\tEvaluate a given expression.";
 	private static final String EVAL_HELP_STRING =
 			  "Usage: %eval [--target=<NAME>] <EXPR>\n\n"
 			+ "Print the results of evaluating <EXPR> on the target given by <NAME>, which must be fully qualified.\n"
 			+ "If a target is not given, then evaluate <EXPR> in global scope.\n";
 
+	private static final String LIST_HELP_SHORT_STRING = "%list\t\tList loaded library packages or the results of a given query";
 	private static final String LIST_HELP_STRING =
 			  "Usage: %list [<QUERY>]\n\n"
 			+ "If <QUERY> is not given, then list all loaded library packages.\n"
@@ -72,13 +68,17 @@ public class SysMLInteractiveHelp {
 			+ "    <NAME>::**\t\tall members of the namespace <NAME> and, recursively, members of owned namespaces.\n"
 			+ "The last two forms may be optionally followed by a filter expression in square brackets.\n";
 
+	private static final String SHOW_HELP_SHORT_STRING =
+			"%show\t\tPrint the abstract syntax tree rooted in a named element";
 	private static final String SHOW_HELP_STRING =
 			  "Usage: %show [--style=<STYLE>] <NAME>\n\n"
 			+ "Print the abstract syntax tree rooted in <NAME>. <NAME> must be fully qualified.\n\n"
 			+ "<STYLE> is also case insensitive. The possible style names are:\n"
     	    + "   TREE\t\tHierarchically indented representation with only identifying information\n"
     	    + "   JSON\t\tComplete JSON representation of the tree\n";
 
+	private static final String PUBLISH_HELP_SHORT_STRING =
+			"%publish\tPublish to the repository the model elements rooted in a named element";
 	private static final String PUBLISH_HELP_STRING =
 			  "Usage: %publish [-d] [--project=<PROJECT NAME>] [--branch=<BRANCH NAME>] <NAME>\n\n"
 			+ "Publish the model elements rooted in <NAME> to the repository. <NAME> must be fully qualified.\n"
@@ -90,6 +90,9 @@ public class SysMLInteractiveHelp {
 			+ "If <BRANCH NAME> is given, then the model is written to this branch of the project.\n"
 			+ "If <BRANCH NAME> is not given, the default branch is used.\n";
 
+
+	private static final String VIZ_HELP_SHORT_STRING =
+			"%viz\t\tVisualize the named model elements";
     private static final String VIZ_HELP_STRING =
     	      "Usage: %viz [--view=<VIEW>] [--style=<STYLE>...] <NAME> [<NAME>...]\n\n"
     	    + "Visualize model elements of <NAME>(s). <NAME>s must be fully qualified.\n\n"
@@ -107,6 +110,8 @@ public class SysMLInteractiveHelp {
     	    + "\t%viz --view Tree --style LR --style ortholine Pkg1::PartDef Pkg1::Pkg2::partUsage\n"
     	    + "should visualize Pkg1::PartDef and Pkg1::Pkg2::partUsage with a tree view ordered in the left-to-right direction with orthogonal lines.\n";
 
+    private static final String VIEW_HELP_SHORT_STRING =
+			"%view\t\tRender the view specified by the named view usage";
     private static final String VIEW_HELP_STRING =
     	      "Usage: %view [--render=<RENDERING>] [--style=<STYLE>...] <NAME>\n\n"
     	    + "Render the view specified by the view usage <NAME>. <NAME> must be fully qualified.\n"
@@ -122,34 +127,51 @@ public class SysMLInteractiveHelp {
             + SysML2PlantUMLStyle.getStyleHelp();
 
 
+    private static final String EXPORT_HELP_SHORT_STRING =
+    		"%export\t\tSave a file of the JSON representation of the abstract syntax tree rooted in the named element.";
 	private static final String EXPORT_HELP_STRING =
 			  "Usage: %export <NAME>\n\n"
 			+ "Save a file containing the complete JSON representation of the abstract syntax tree rooted in <NAME>.\n"
 		    + "<NAME> must be fully qualified.\n";
 
+	private static final String LOAD_HELP_SHORT_STRING = "%load\t\tLoad models from the repository";
 	private static final String LOAD_HELP_STRING =
-			"Usage: %load [--id=<PROJECT ID] [--name=<NAME>] [--branch=<BRANCH_NAME>] [<NAME>]\n\n"
-			+ "Download previously published models from a project in the repository. <NAME> is the full name of the project.\n"
-			+ "Named elements of the downloaded models may then be referenced models in the notebook."
-			+ "(Use %projects to view repository contents.)\n"
+			"Usage: %load [--id=<PROJECT ID>] [--name=<NAME>] [--branch=<BRANCH_NAME>] [<NAME>]\n\n"
+			+ "Download previously published models from a project in the repository. (Use %projects to view repository contents.)\n"
+			+ "Named elements of the downloaded models may then be referenced by models in the notebook.\n"
+			+ "<NAME> is the full name of the project.\n"
 			+ "If <PROJECT ID> is given, then the project with that UUID is loaded. In this case, the <NAME> must not be given.\n"
-			+ "If <BRANCH NAME> is given, then the model is loaded from this branch of the project.\n"
-			+ "If <BRANCH NAME> is not given, the default branch is used.\n";
+			+ "If <BRANCH NAME> or <BRANCH ID> is given, then the model is loaded from this branch of the project.\n"
+			+ "If no <BRANCH NAME> or <BRANCH ID> is given, the default branch is used.\n"
+			+ "If <BRANCH ID> is given, then a <BRANCH NAME> must not be given.\n";
 
+	private static final String PROJECTS_HELP_SHORT_STRING = "%projects\tList projects in the repository";
 	private static final String PROJECTS_HELP_STRING =
 			  "Usage: %projects\n\n"
 			+ "Print the name and identifier of all projects in the repository.\n";
 
-	private static final String API_BASE_PATH_HELP_STRING =
+	private static final String REPO_HELP_SHORT_STRING ="%repo\t\tSet the API base path for the repository";
+	private static final String REPO_HELP_STRING =
 			  "Usage: %repo [<BASE PATH>]\n\n"
-			+ "If <BASE PATH> is not given, print the current repository base path.\r\n"
-			+ "If <BASE PATH> is given, set the repository base path.\r\n"
-			+ "\r\n"
-			+ "<BASE PATH> is a URL giving the API base path for the repository access by the %projects, %publish and %load commands. \r\n"
-			+ "For example: https://my.domain.com/sysml_repo";
- 
+			+ "Set the API base path for the repository accessed by the %projects, %publish and %load commands.\n"
+			+ "<BASE PATH> is a URL (possibly including port number), such as: https://my.domain.com/sysml_repo:9000.\n"
+			+ "If <BASE PATH> is not given, the current repository base path is printed.\n"
+			+ "If <BASE PATH> is given, the repository base path is set to this.\n"
+			;
+
+	private static String generalHelpCached;
+
 	public static String getGeneralHelp() {
-		return GENERAL_HELP_STRING;
+		if (generalHelpCached == null) {
+			StringBuilder sb = new StringBuilder();
+			sb.append(GENERAL_HELP_STRING_PREFIX);
+			for (var entry: commandShortHelpMap.entrySet()) {
+				sb.append(entry.getValue());
+				sb.append(System.lineSeparator());
+			}
+			generalHelpCached = sb.toString();
+		}
+		return generalHelpCached;
 	}
 
 	public static String getHelpHelp() {
@@ -192,27 +214,42 @@ public static String getLoadHelp() {
     	return LOAD_HELP_STRING;
     }
 
-    public static String getApiBasePathHelp() {
-    	return API_BASE_PATH_HELP_STRING;
+    public static String getRepoPathHelp() {
+    	return REPO_HELP_STRING;
 	}
 
-    private static Map<String, String> commandHelpMap = createCommandHelpMap();
-
-    private static Map<String, String> createCommandHelpMap() {
-    	Map<String, String> map = new HashMap<>();
-    	map.put("%help", HELP_HELP_STRING);
-    	map.put("%eval", EVAL_HELP_STRING);
-    	map.put("%list", LIST_HELP_STRING);
-    	map.put("%show", SHOW_HELP_STRING);
-    	map.put("%publish", PUBLISH_HELP_STRING);
-    	map.put("%viz", VIZ_HELP_STRING);
-    	map.put("%view", VIEW_HELP_STRING);
-    	map.put("%export", EXPORT_HELP_STRING);
-    	map.put("%load", LOAD_HELP_STRING);
-    	map.put("%projects", PROJECTS_HELP_STRING);
-    	map.put("%repo", API_BASE_PATH_HELP_STRING);
-
-    	return map;
+    private static Map<String, String> commandShortHelpMap = new TreeMap<>();
+    private static Map<String, String> commandHelpMap = new HashMap<>();
+    static {
+    	registerHelpString("%help", HELP_HELP_SHORT_STRING, HELP_HELP_STRING);
+    	registerHelpString("%eval", EVAL_HELP_SHORT_STRING, EVAL_HELP_STRING);
+    	registerHelpString("%list", LIST_HELP_SHORT_STRING, LIST_HELP_STRING);
+    	registerHelpString("%show", SHOW_HELP_SHORT_STRING, SHOW_HELP_STRING);
+    	registerHelpString("%publish", PUBLISH_HELP_SHORT_STRING, PUBLISH_HELP_STRING);
+    	registerHelpString("%viz", VIZ_HELP_SHORT_STRING, VIZ_HELP_STRING);
+    	registerHelpString("%view", VIEW_HELP_SHORT_STRING, VIEW_HELP_STRING);
+    	registerHelpString("%export", EXPORT_HELP_SHORT_STRING, EXPORT_HELP_STRING);
+    	registerHelpString("%load", LOAD_HELP_SHORT_STRING, LOAD_HELP_STRING);
+    	registerHelpString("%projects", PROJECTS_HELP_SHORT_STRING, PROJECTS_HELP_STRING);
+    	registerHelpString("%repo", REPO_HELP_SHORT_STRING, REPO_HELP_STRING);
+    }
+
+    /**
+     * Adds command helps to the centralized store.
+     * @param command The name of the magic command, including the '%' prefix
+     * @param shortDescription
+     * 		A one-line description of a command, including the command name with the '%' prefix
+     * 		one or two tabs to make the output of the %help command nicely formatted.
+     * @param detailedHelp
+     * 		A multi-line help for a given command, expected to also detail the parameter formatting
+     *
+     * @throws IllegalStateException when help for a command is being re-registered
+     */
+    public static void registerHelpString(String command, String shortDescription, String detailedHelp) {
+    	Preconditions.checkState(!commandHelpMap.containsKey(command), "Help is already registered for command %s", command);
+    	commandShortHelpMap.put(command, shortDescription);
+    	commandHelpMap.put(command, detailedHelp);
+    	generalHelpCached = null;
     }
 
     public static String getHelpString(String command) {

org.omg.sysml.jupyter.kernel/.classpath

@@ -21,7 +21,6 @@
 	</classpathentry>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-17">
 		<attributes>
-			<attribute name="module" value="true"/>
 			<attribute name="maven.pomderived" value="true"/>
 		</attributes>
 	</classpathentry>
@@ -37,12 +36,6 @@
 			<attribute name="maven.pomderived" value="true"/>
 		</attributes>
 	</classpathentry>
-	<classpathentry kind="src" output="target/classes" path="target/kernel">
-		<attributes>
-			<attribute name="optional" value="true"/>
-			<attribute name="maven.pomderived" value="true"/>
-		</attributes>
-	</classpathentry>
 	<classpathentry combineaccessrules="false" kind="src" path="/org.omg.sysml.interactive"/>
 	<classpathentry combineaccessrules="false" kind="src" path="/org.omg.sysml"/>
 	<classpathentry kind="output" path="target/classes"/>

org.omg.sysml.jupyter.kernel/pom.xml

@@ -8,7 +8,7 @@
     <version>${revision}</version>
   </parent>
   <artifactId>jupyter-sysml-kernel</artifactId>
-  
+
     <dependencies>
         <dependency>
             <groupId>org.omg.sysml</groupId>
@@ -35,8 +35,8 @@
         		</exclusion>
     		</exclusions>
         </dependency>
-        <!-- 
-        Dependencies needed for m2e 
+        <!--
+        Dependencies needed for m2e
         we need to add these manually so the Eclipse IDE can see the classpath
         -->
         <dependency>
@@ -119,7 +119,7 @@
           </execution>
         </executions>
       </plugin>
-      
+
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-jar-plugin</artifactId>
@@ -138,7 +138,7 @@
            </execution>
         </executions>
       </plugin>
-      
+
       <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-shade-plugin</artifactId>
@@ -201,25 +201,6 @@
             </executions>
         </plugin>
 
-        <!-- Needed for updating the version number in the kernel.json. This is used to copy the resources to the unzipped kernel.-->
-		<plugin>
-			<groupId>org.codehaus.mojo</groupId>
-			<artifactId>templating-maven-plugin</artifactId>
-			<version>3.0.0</version>
-			<executions>
-				<execution>
-					<phase>prepare-package</phase>
-					<goals>
-						<goal>filter-sources</goal>
-					</goals>
-				</execution>
-			</executions>
-			<configuration>
-				<sourceDirectory>src/main/resources</sourceDirectory>
-				<outputDirectory>target/kernel</outputDirectory>
-			</configuration>
-		</plugin>
-       
        <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-resources-plugin</artifactId>
@@ -241,6 +222,9 @@
                     <include>${project.artifactId}-${project.version}-all.jar</include>
                   </includes>
                 </resource>
+                <resource>
+                  <directory>${basedir}/src/main/resources</directory>
+                </resource>
                 <resource>
                   <directory>..</directory>
                   <targetPath>sysml</targetPath>
@@ -255,7 +239,7 @@
           </execution>
         </executions>
       </plugin>
-       
+
 	     <plugin>
 	        <groupId>org.apache.maven.plugins</groupId>
 	        <artifactId>maven-assembly-plugin</artifactId>

org.omg.sysml.jupyter.kernel/src/main/java/org/omg/sysml/jupyter/kernel/IMagicCommandRegistrator.java

@@ -0,0 +1,46 @@
+/*****************************************************************************
+ * SysML 2 Pilot Implementation
+ * Copyright (c) 2025 Model Driven Solutions, Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of theGNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * @license LGPL-3.0-or-later <http://spdx.org/licenses/LGPL-3.0-or-later>
+ *
+ * Contributors:
+ *  Zoltan Ujhelyi, MDS
+ *
+ *****************************************************************************/
+package org.omg.sysml.jupyter.kernel;
+
+import org.omg.sysml.interactive.SysMLInteractiveHelp;
+
+import io.github.spencerpark.jupyter.kernel.magic.registry.Magics;
+
+public interface IMagicCommandRegistrator {
+
+	/**
+	 * Implementors of this method are free to register their extra commands to the
+	 * Jupyter kernel. This method is called when the Jupyter environment is
+	 * initialized and it assumed the registration code will run quickly and without
+	 * exceptions. If the registrator cannot run successfully, it should not
+	 * register anything instead of throwing an exception.
+	 * </p>
+	 * Implementors are recommended to use the register methods of the {@link Magics}
+	 * class. Help is managed by the {@link SysMLInteractiveHelp} class.
+	 *
+	 * @see Magics#registerMagics(Class)
+	 * @see SysMLInteractiveHelp#registerHelpString(String, String, String)
+	 */
+	void registerMagicCommand(Magics magics);
+}