Metadata-Version: 2.4
Name: make-xuml-repo
Version: 0.16.0
Summary: Generates a database from a set of *.xcm (executable class model) files
Author-email: Leon Starr <leon_starr@modelint.com>
License: MIT License
        
        Copyright (c) 2019-2023 Leon Starr
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: repository, https://github.com/modelint/make-xuml-repo
Project-URL: documentation, https://github.com/modelint/make-xuml-repo/wiki
Keywords: action language,executable uml,mbse,xuml,xtuml,platform independent,sysml
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML
Requires-Dist: xcm-parser
Requires-Dist: mi-pyral
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Provides-Extra: dev
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Make an Executable UML Repository

This is the first step in the model execution tool chain.

The `make-xuml-repo` command generates an empty metamodel database that can be populated with the modeled
components of your system.

We say 'metamodel' because the generated database schema defines the 
[Shlaer-Mellor Executable UML modeling language](https://github.com/modelint/shlaer-mellor-metamodel/wiki). It defines
all structures necessary to describe platform independent domains, class models, state models, as well as the complete 
computational activities driven by each state transition and method call.

#### Output

The output consists of these three files:

- `mmdb.ral` -- The database
- `mmdb.txt` -- Human readable text that displays all of the database tables (relvars / relational variables)
- `mmclass_nt.py` -- A set of python named tuples, one per metamodel class, used for model population. Each metamodel class corresponds to a similarly named relvar (table).

#### Input

The input to `make-xuml-repo` is a set of *.xcm (Executable Class Model) files. The files are parsed using
the [xcm-parser](https://github.com/modelint/xcm-parser). You can view these files here: `<TBD>`

This file set defines a subset of the full modeling language though the bulk of the language is, in fact, supported.
But work continues and, as the `.xcm` files upgrade, it will be necessary to refresh your metamodel database
by re-running make-xuml-repo.

The latest [Shlaer-Mellor metamodel](https://github.com/modelint/shlaer-mellor-metamodel/wiki) is specified inside this 
package as a folder of .xcm (executable class model) files and a types.yaml file.

Each subsystem of the metamodel (class-attribute, state, etc) is defined in a single .xcm file all within 
a single foler. That folder also contains one types.yaml file specifying the db type (data type) to use for each 
metamodel attribute type. The db type 'string', for example, is associated with the `State Name` metamodel type.

#### Database

Rather than a traditional SQL database, we use Andrew Mangogna's open source tclRAL Relational Algebra Library.

It is an implementation of relational algebra as defined by [C.J. Date and Hugh Darwen](https://github.com/modelint/shlaer-mellor-metamodel/wiki/Resources#ttm-databases-types-and-the-relational-model-the-third-manifesto-cj-date-hugh-darwen----links-to-the-actual-book-as-a-downloadable-pdf). So we can use nested relational algrebra 
without any of that SQL mess. It is implemented in C and Tcl, but we provide a python front end 
called [PyRAL]() to keep everything pythonic.

### Why you need this

You probably don't. What you want instead is the metamodel populator which does use this package.
It's not up on PyPI yet. Give me a couple of weeks and it should be here. I'll post a link when it's ready.

Though if you did want to fiddle with the metamodel, generate your own variation of it and such, this package
might come in handy.

### Installation

Create or activate a Python 3.11+ environment (earlier versions may or may not work), then install
from PyPI:

    % pip install make-xuml-repo

It's a good idea to upgrade `pip` first if you haven't in a while:

    % pip install --upgrade pip

Once installed, you can invoke the repository generator with the `makexumlrepo` command.

### Usage

Run the command in the directory where you want the output files created:

    % makexumlrepo

This generates three files in the current directory:

- `mmdb.ral` — The database. Although it is a text file, it can be opened by TclRAL (via PyRAL) to
  establish an empty relvar (table) per metamodel class, ready to be populated with instances of your
  modeled domains.
- `mmdb.txt` — A human readable listing of every relvar in the database.
- `mmclass_nt.py` — A set of Python named tuples, one per metamodel class, with a field for each of that
  class's attributes. PyRAL uses these to insert one or more tuples into the corresponding relvar.

You can load these with the metamodel populator (coming soon) or your own tooling. In my own workflow I
generate the files and copy them into my metamodel populator package.

### Command line options

| Option | Long form | Description |
| ------ | --------- | ----------- |
| `-h` | `--help` | Show a summary of all options and exit. |
| `-V` | `--version` | Print the installed version and exit. |
| `-M` | `--models` | Copy the packaged `metamodel` and `layout` directories into the current directory, then exit. Existing directories are left untouched (a warning is issued). No database is built. |
| `-v` | `--verbose` | Show warnings on the console. By default warnings are suppressed on the console (but still recorded in the log file when `-L` is used). |
| `-L` | `--log` | Keep the diagnostic `make_xuml_repo.log` file. Without this flag the log is removed on exit. |
| `-D` | `--debug` | Run in debug mode. |

#### Inspecting or customizing the metamodel

If you want to look at the `.xcm` metamodel files or the layout sheets that ship with the package, copy
them into your working directory with:

    % makexumlrepo -M

This creates a `metamodel` directory (the `.xcm` files and `mm_types.yaml`) and a `layout` directory in
the current directory. No database is generated when `-M` is supplied.
