Metadata-Version: 2.4
Name: sip-parser
Version: 0.2.2
Summary: Scenario Instance Population Parser
Author-email: Leon Starr <leon_starr@modelint.com>
License: MIT License
        
        Copyright (c) 2025 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/sip-parser
Project-URL: documentation, https://github.com/modelint/sip-parser/wiki
Keywords: scenario population,initial instances,parser,executable uml,class model,mbse,xuml,xtuml,platform independent,sysml,leon starr,blueprint,model integration,shlaer-mellor
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: Arpeggio<3.0.0
Requires-Dist: tomli; python_version < "3.13"
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

# Scenario Instance Population Parser

<p align="center">
  <img src="https://raw.githubusercontent.com/modelint/sip-parser/main/docs/images/sip-parser-readme.png"
       alt="Parses a .sip scenario instance population file into an abstract syntax tree for downstream Blueprint modules"
       width="720">
</p>

Parses a *.sip file (Scenario Instance Population) to yield an initial instance population.

> 📖 The sip modeling language is fully documented in the [project wiki](https://github.com/modelint/sip-parser/wiki).

### Why you need this

Before executing your system models, you need to define an initial population of instances,
attribute values, and initial states. In the modeled elevator management (EVMAN) domain for
example, you might specify a single Bank with two Shafts and several Floors. Starting off, one of the Shafts
might be in service while the other is out of service.

Having set this stage, you can run any number of scenarios against that initial population.

The population is provided as a sip file to this sip parser which generates an AST (abstract syntax tree) as
input to some downstream module. For example, the Blueprint [popdata](https://github.com/modelint/domain-populate) module imports 
the sip parser and passes in your `.sip` file.

So you don't typically run the sip parser by itself unless you are performing diagnostics or engineering an updated
toolchain that doesn't feed into popdata.

### Installation

Create or use a python 3.11+ environment. Then

% pip install sip-parser

At this point you can invoke the parser via the command line or from your python script.

#### From your python script

You need this import statement at a minimum:

    from sip_parser.parser import SIParser

You can then specify a path as shown:

    result = SIParser.parse_file(file_input=path_to_file, debug=False)

Here `result` will be a `Scenario` named tuple holding the scenario `name` and a dictionary of `classes` keyed by
class name. Each value is a `ClassModelPopulation` named tuple holding the column `header` and the `population`
of instance rows. You may find the header of the `visitor.py` file helpful in interpreting these results, and the
[Parser output](https://github.com/modelint/sip-parser/wiki/Parser-output) wiki page breaks the whole structure
down with examples.

The parser checks syntax only. It never reads the class or state models, so it cannot tell you
that a class, attribute or state you named doesn't exist, or that a row is a value short. Those checks belong to
whatever consumes the result.

#### From the command line

This is not the intended usage scenario, but may be helpful for testing or exploration. Since the parser
may generate some diagnostic info you may want to create a fresh working directory and cd into it
first. From there...

    % sip EVMAN_three_bank1.sip

The .sip extension is not necessary, but the file must contain sip text. A successful parse just reports
`No problemo`; anything else raises a parse error naming the line and column where the grammar gave up.

See this repository's wiki for more about the sip language. The grammar is defined in the [sip.peg](https://github.com/modelint/sip-parser/blob/main/src/sip_parser/sip.peg) file. (if the link breaks after I do some update to the code,
just browse through the code looking for the sip.peg file, and let me know so I can fix it)

You can also specify a debug option like this:

    % sip EVMAN_three_bank1.sip -D

This will create a `diagnostics` folder in your current working directory and deposit a couple of PDFs defining
the parse of both the sip grammar: `si_model.pdf` and your supplied text: `si_parse_tree.pdf`. These are rendered
with graphviz, so you'll need `dot` on your path to get them.

You should also see a file named `SI_parser.log` in your current working directory
