overall: improved readme

demos: added a demo for using mps-cli-py in a jupyter notebook

Readme.md

@@ -6,10 +6,13 @@ This repository contains tooling for reading MPS models from command line - with
 ### Projects
 - A Gradle plugin for reading MPS files and building an object model - [here](mps-cli-gradle-plugin/Readme.md).
 - A Python library for reading MPS files and building an object model - [here](mps-cli-py/Readme.md).
+- A Typescript libeary for reading MPS files and building an object model - [here](mps-cli-ts/Readme.md).
 
 ### Repository Structure
 - `mps-cli-gradle-plugin` - the gradle plugin to read MPS models
 - `mps-cli-py` - a Python library to read MPS models
+- `mps-cli-ts` - a Typescript library to read MPS models  
 - `demos` - examples for the use of the MPS-CLI tooling 
   - `gradle-plugin-use` - example of the use of the `mps-cli-gradle-plugin` 
+  - `jupyter-notebook` - example of the use of the `mps-cli-py` library in a Jupyter Notebook
 - `mps_test_projects` - MPS project containing language definitions and models used as test-data for the MPS-cli tools

demos/jupyter-notebook/Readme.md

@@ -0,0 +1,4 @@
+## Jupyter Notebook - Demo Project
+
+This project demonstrates the use of the MPS CLI Python library from within a Jupyter Notebook.
+

demos/jupyter-notebook/mps-cli-notebook.ipynb

@@ -0,0 +1,226 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0c9c2589-01a6-48ea-a4ec-f01e452cb134",
+   "metadata": {},
+   "source": [
+    "# Using the MPS-CLI Python Library\n",
+    "\n",
+    "## Loading the model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f5969fb2-8bdc-4b6e-ab0e-5d48e41ec810",
+   "metadata": {},
+   "source": [
+    "import sys\n",
+    "sys.path.insert(1, '..\\..\\mps-cli-py\\src')\n",
+    "\n",
+    "from mpscli.model.builder.SSolutionsRepositoryBuilder import SSolutionsRepositoryBuilder\n",
+    "\n",
+    "builder = SSolutionsRepositoryBuilder()\n",
+    "repo = builder.build('..\\\\..\\\\mps_test_projects\\\\mps_cli_lanuse_file_per_root')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "44a68574-8c57-4186-bac2-3930491120c3",
+   "metadata": {},
+   "source": [
+    "## Accessing solutions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "713d0c76-eae1-4bb2-a7f5-8b133f1193f1",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "number of parsed solutions: 2\n",
+      "\tmps.cli.lanuse.library_second\n",
+      "\tmps.cli.lanuse.library_top\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"number of parsed solutions: \" + str(len(repo.solutions)))\n",
+    "print(\"parsed solutions:\")\n",
+    "for sol in repo.solutions:\n",
+    "    print(\"\\t\" + sol.name)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c950f571-906a-494f-84bc-d3cfe9f84a30",
+   "metadata": {},
+   "source": [
+    "## Accessing models and root nodes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "id": "9722e60a-2d79-4131-8cef-59101237df13",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "models and root nodes of \"mps.cli.lanuse.library_second\" are:\n",
+      "\tmps.cli.lanuse.library_second.library_top\n",
+      "\t\troot nodes are:\n",
+      "\t\t\t_library\n"
+     ]
+    }
+   ],
+   "source": [
+    "library_second_solution = repo.find_solution_by_name(\"mps.cli.lanuse.library_second\")\n",
+    "print(f'models and root nodes of \"{ library_second_solution.name }\" are:')\n",
+    "for model in library_second_solution.models:\n",
+    "    print(\"\\t\" + model.name)\n",
+    "    print(\"\\t\\troot nodes are:\")\n",
+    "    for root in model.root_nodes:\n",
+    "        print(\"\\t\\t\\t\" + root.get_property(\"name\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c6edf78e-e4fc-4657-8ce9-d3e818dd2907",
+   "metadata": {},
+   "source": [
+    "## Accessing node information"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "id": "16cbb784-9ccb-4bb1-8207-12c53a785ca5",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "root node _library\n",
+      "child node: Tom Sawyer  with concept mps.cli.landefs.library.structure.Book\n"
+     ]
+    }
+   ],
+   "source": [
+    "library_top_model = repo.find_model_by_name(\"mps.cli.lanuse.library_second.library_top\")\n",
+    "for root in library_top_model.root_nodes:\n",
+    "    print(f'root node { root.get_property(\"name\") }')\n",
+    "    for child in root.children:\n",
+    "        print(f'\\t child node: {child.get_property(\"name\") }  with concept {child.concept.name}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f2e9d929-990f-4070-9f39-52035697a8d4",
+   "metadata": {},
+   "source": [
+    "## Accessing the meta-information about languages and concepts"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "id": "45802a94-2ee3-4dda-8373-a47e4fd8d140",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "language: mps.cli.landefs.library\n",
+      "\tconcepts:\n",
+      "\t\tmps.cli.landefs.library.structure.Library\n",
+      "\t\t\tchildren roles:\n",
+      "\t\t\t\tentities\n",
+      "\t\tmps.cli.landefs.library.structure.LibraryEntityBase\n",
+      "\t\t\tproperties:\n",
+      "\t\t\t\tisbn\n",
+      "\t\t\t\tavailable\n",
+      "\t\tmps.cli.landefs.library.structure.Book\n",
+      "\t\t\tproperties:\n",
+      "\t\t\t\tpublicationDate\n",
+      "\t\t\tchildren roles:\n",
+      "\t\t\t\tauthors\n",
+      "\t\tmps.cli.landefs.library.structure.Magazine\n",
+      "\t\t\tproperties:\n",
+      "\t\t\t\tperiodicity\n",
+      "language: jetbrains.mps.lang.core\n",
+      "\tconcepts:\n",
+      "\t\tjetbrains.mps.lang.core.structure.INamedConcept\n",
+      "\t\t\tproperties:\n",
+      "\t\t\t\tname\n",
+      "language: mps.cli.landefs.people\n",
+      "\tconcepts:\n",
+      "\t\tmps.cli.landefs.people.structure.PersonRef\n",
+      "\t\t\treferences roles:\n",
+      "\t\t\t\tperson\n",
+      "\t\tmps.cli.landefs.people.structure.PersonsContainer\n",
+      "\t\t\tchildren roles:\n",
+      "\t\t\t\tpersons\n",
+      "\t\tmps.cli.landefs.people.structure.Person\n"
+     ]
+    }
+   ],
+   "source": [
+    "for language in repo.languages:\n",
+    "    print(\"language: \" + language.name)\n",
+    "    print(\"\\tconcepts:\")\n",
+    "    for concept in language.concepts:\n",
+    "        print(\"\\t\\t\" + concept.name)\n",
+    "        if (len(concept.properties) > 0):\n",
+    "            print(\"\\t\\t\\tproperties:\")\n",
+    "            for property in concept.properties:\n",
+    "                print(\"\\t\\t\\t\\t\" + property)\n",
+    "        if (len(concept.children) > 0):\n",
+    "            print(\"\\t\\t\\tchildren roles:\")\n",
+    "            for child in concept.children:\n",
+    "                print(\"\\t\\t\\t\\t\" + child)\n",
+    "        if (len(concept.references) > 0):\n",
+    "            print(\"\\t\\t\\treferences roles:\")\n",
+    "            for reference in concept.references:\n",
+    "                print(\"\\t\\t\\t\\t\" + reference)        "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e67706cf-07a2-486c-91ad-329d7f0433b4",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

mps-cli-ts/readme.md

@@ -5,4 +5,20 @@
 - 'tests' - unit tests
 
 ## Run Tests
-- Run tests with: `npm test`
+- Run tests with: `npm test`
+
+### Features
+The following features are available:
+- load MPS files (*.mpsr) and expose their content as Typescript object model 
+  - solutions, models, root nodes, nodes, children, references, properties
+
+The core of the Typescript object model is given by the following classes:
+- `SNode` - represents a node
+- `SModel` - represents a model
+- `SSolution` - represents a solution
+- `SRepository` - the repository containing the parsed model and meta-information
+
+### Limitations
+The plugin has currently the following limitations:
+- only File-per-Root persistency is currently supported
+- the recovered language information reflects only the used language in the loaded solutions