### Morphir Basic Commands Source: https://github.com/finos/morphir/blob/main/INSTALLING.md Provides examples of fundamental Morphir commands for getting started, including showing help information, checking the version, and initializing a new workspace. ```bash # Show help morphir --help # Show version morphir --version # Initialize a new Morphir workspace (example) morphir workspace init # See all available commands morphir --help ``` -------------------------------- ### Morphir Project Setup and Build Source: https://github.com/finos/morphir/blob/main/NOTES.md Steps to clone the Morphir repository, set up the development environment using `mise run setup`, and build the project. The setup process includes syncing Go modules and installing npm dependencies for git hooks. ```sh # Clone the repository git clone https://github.com/finos/morphir.git cd morphir # Set up the development environment mise run setup # Build the project # For development, use build-dev mise run build-dev # Or for standard build mise run build ``` -------------------------------- ### User Overrides Example (TOML) Source: https://github.com/finos/morphir/blob/main/docs/configuration.md An example of the `.morphir/morphir.user.toml` file, used for local, non-version-controlled settings. This file is ideal for development-specific configurations like debug logging or custom UI themes. ```toml # .morphir/morphir.user.toml [logging] level = "debug" file = ".morphir/debug.log" [ui] theme = "dark" ``` -------------------------------- ### Global User Configuration Example (TOML) Source: https://github.com/finos/morphir/blob/main/docs/configuration.md Example of a global user configuration file (`~/.config/morphir/morphir.toml`) for settings that apply across all Morphir projects. This includes logging level and UI theme. ```toml [logging] level = "debug" [ui] theme = "dark" ``` -------------------------------- ### Verify Morphir CLI Installation Source: https://github.com/finos/morphir/blob/main/docs/cli-preview/getting-started.md Verifies the installation of the Morphir CLI by running the 'morphir about' command. This command displays information about the installed Morphir version, build details, and system configuration. ```bash morphir about ``` -------------------------------- ### Morphir 'make' Configuration Example Source: https://github.com/finos/morphir/blob/main/docs/getting-started/installation-and-usage.md Provides an example structure for the 'morphir.json' configuration file required by the 'morphir-elm make' command. This file defines package name, source directory, and exposed modules. ```json { "name": "My.Package", "sourceDirectory": "src", "exposedModules": [ "Foo", "Bar" ] } ``` -------------------------------- ### Setup Decorations using Morphir CLI Source: https://github.com/finos/morphir/blob/main/docs/user-guides/development-guides/decorators-users-guide.md These bash commands demonstrate how to set up decorations using the Morphir CLI. It includes options for using registered types and specifying paths directly. ```bash # Using a registered type morphir decoration setup myDecoration --type documentation # Using direct paths morphir decoration setup myDecoration \ -i decorations/morphir-ir.json \ -e "My.Amazing.Decoration:Foo:Shape" \ --display-name "My Amazing Decoration" \ --storage-location "my-decoration-values.json" ``` -------------------------------- ### Run Morphir CLI Source: https://github.com/finos/morphir/blob/main/DEVELOPING.md Executes the Morphir CLI. This example shows how to run the help command to see available options. ```bash ./bin/morphir --help ``` -------------------------------- ### Create a WIT file for compilation Source: https://github.com/finos/morphir/blob/main/docs/cli-preview/getting-started.md Defines a simple WIT (Web Interface Technology) interface named 'greeter' with two functions: 'greet' and 'goodbye'. This file serves as input for Morphir's compilation process. ```wit package example:hello; interface greeter { /// Greet someone by name greet: func(name: string) -> string; /// Say goodbye goodbye: func() -> string; } ``` -------------------------------- ### Create Example Directory (Bash) Source: https://github.com/finos/morphir/blob/main/AGENTS.md This command creates a new directory for an example project. It ensures that parent directories are created if they don't exist. ```bash mkdir -p examples/my-example ``` -------------------------------- ### Example WIT Parse Error (JSON) Source: https://github.com/finos/morphir/blob/main/docs/cli-preview/getting-started.md This JSON object represents a typical parse error encountered by the WIT tool. It indicates that the validation failed due to a syntax error at a specific line number, providing the error message. ```json {"success":false,"error":"parse error at line 3: expected 'func'"} ``` -------------------------------- ### Query Decorations using Morphir CLI Source: https://github.com/finos/morphir/blob/main/docs/user-guides/development-guides/decorators-users-guide.md These bash commands show how to query and retrieve decoration information using the Morphir CLI. Examples include listing decorated nodes, getting decorations for specific nodes, and showing decoration statistics. ```bash # List all decorated nodes morphir decoration list # List nodes with specific decoration type morphir decoration list --type documentation # Get decorations for a specific node morphir decoration get "My.Package:Foo:bar" # Get specific decoration type for a node morphir decoration get "My.Package:Foo:bar" --type documentation # Show decoration statistics morphir decoration stats ``` -------------------------------- ### Create and Run Morphir TUI App (Go) Source: https://github.com/finos/morphir/blob/main/cmd/morphir/internal/tui/README.md Demonstrates how to create a basic Morphir TUI application with a sidebar and a viewer. It initializes sidebar items and configures the application using options like title, sidebar content, and initial viewer content. This example requires the 'github.com/finos/morphir/cmd/morphir/internal/tui' and 'github.com/finos/morphir/cmd/morphir/internal/tui/components' packages. ```go package main import ( "github.com/finos/morphir/cmd/morphir/internal/tui" "github.com/finos/morphir/cmd/morphir/internal/tui/components" ) func main() { // Create sidebar items items := []*components.SidebarItem{ {ID: "1", Title: "Introduction"}, {ID: "2", Title: "Documentation"}, } // Create and run app app := tui.NewApp( tui.WithTitle("My App"), tui.WithSidebar(items), tui.WithViewer("# Welcome\n\nSelect an item from the sidebar."), ) app.Run() } ``` -------------------------------- ### WIT Compilation API - Examples Source: https://github.com/finos/morphir/blob/main/docs/cli-preview/commands/wit.md Provides practical examples of using the WIT compilation API in various scenarios, including CI/CD integration, generating IR for multiple APIs, and using strict mode. ```APIDOC --- ## Examples ### CI/CD Integration ```bash #!/bin/bash # Validate all WIT files in a directory find ./wit -name "*.wit" -exec echo '{"file":"{}"}' \; > /tmp/sources.jsonl morphir wit make --jsonl-input /tmp/sources.jsonl --jsonl > /tmp/results.jsonl # Check for failures if grep -q '"success":false' /tmp/results.jsonl; then echo "Validation failed:" grep '"success":false' /tmp/results.jsonl exit 1 fi echo "All WIT files validated successfully" ``` ### Generate IR for All APIs ```bash # Create JSONL from directory for f in ./wit/*.wit; do echo "{\"name\": \"$(basename $f .wit)\", \"file\": \"$f\"}" done > apis.jsonl # Compile all morphir wit make --jsonl-input apis.jsonl --jsonl > compiled.jsonl # Extract module data jq -c 'select(.success) | .module' compiled.jsonl ``` ### Strict Mode for Production ```bash # Fail on any warnings or unsupported constructs morphir wit make api.wit --warnings-as-errors --strict -o api.ir.json ``` ``` -------------------------------- ### Install Morphir using Windows PowerShell Script Source: https://github.com/finos/morphir/blob/main/INSTALLING.md Installs or updates Morphir on Windows systems by downloading and executing a PowerShell installation script. This script automates the download and setup process for Windows users. ```powershell irm https://raw.githubusercontent.com/finos/morphir/main/scripts/install.ps1 | iex ``` -------------------------------- ### Install Gulp Build Tool (JavaScript) Source: https://github.com/finos/morphir/blob/main/docs/developers/contribution-guide-readme.md Installs the Gulp build tool globally using NPM. Gulp is used as the build tool for the project. Ensure Node.js and NPM are installed. ```bash npm install -g gulp ``` -------------------------------- ### Morphir Installation Methods Source: https://github.com/finos/morphir/blob/main/AGENTS.md Outlines the different ways users can install the Morphir CLI. This includes downloading pre-compiled binaries from GitHub Releases, using 'go install', and a planned Homebrew installation. ```bash # 1. Binary download - Download from GitHub Releases # 2. Go install - go install github.com/finos/morphir-go/cmd/morphir@vX.Y.Z # 3. Homebrew - (future) brew install finos/tap/morphir ``` -------------------------------- ### Entry Point Format Example (FQName) Source: https://github.com/finos/morphir/blob/main/docs/developers/decorators-implementation-plan.md Illustrates the Fully Qualified Name (FQName) format used for specifying entry points in Morphir, which typically follows the pattern `PackageName:ModuleName:TypeName`. This standardized format ensures unambiguous identification of types within the Morphir ecosystem. ```text My.Amazing.Decoration:Foo:Shape ``` -------------------------------- ### Install Morphir CLI using npm Source: https://github.com/finos/morphir/blob/main/docs/getting-started/installation.md Installs the Morphir command line tools globally using the npm package manager. This command requires Node.js and npm to be pre-installed on the system. ```bash npm install -g morphir-elm ``` -------------------------------- ### Go Module Tagging Examples Source: https://github.com/finos/morphir/blob/main/AGENTS.md Demonstrates how to tag individual Go modules within a monorepo using subdirectory prefixes. This allows for independent versioning of packages like 'pkg/config' and 'cmd/morphir'. Synchronized releases are recommended, where all modules share the same version number. ```bash pkg/config/v0.3.0 # Tag for pkg/config module pkg/models/v0.3.0 # Tag for pkg/models module cmd/morphir/v0.3.0 # Tag for cmd/morphir module v0.3.0 # Main repository tag ``` -------------------------------- ### Install Lobo Test Runner Source: https://github.com/finos/morphir/blob/main/docs/user-guides/modeling-guides/modelling-testing.md Installs Lobo, a test runner, as a development dependency for your project. Lobo is used to execute your Elm tests. ```bash npm install lobo --save ``` -------------------------------- ### Install elm-test Testing Library Source: https://github.com/finos/morphir/blob/main/docs/user-guides/modeling-guides/modelling-testing.md Installs the standard Elm testing library, elm-test, into your project. This is a prerequisite for writing and running Elm tests. ```bash elm install elm-explorations/test ``` -------------------------------- ### Morphir Go TOML Configuration Example Source: https://github.com/finos/morphir/blob/main/docs/getting-started/morphir-go-preview.md An example TOML file demonstrating the configuration structure for a Morphir project. It includes settings for the workspace, project source directory, and logging. ```toml [workspace] name = "MyProject" format = "json" [project] source_directory = "./src" [logging] level = "info" format = "text" ``` -------------------------------- ### Verify Morphir Development Setup Source: https://github.com/finos/morphir/blob/main/DEVELOPING.md Runs all module verifications to ensure the development environment is correctly configured. This command checks the integrity of the setup. ```bash mise run verify ``` -------------------------------- ### Print Hello World in Python Source: https://github.com/finos/morphir/blob/main/pkg/nbformat/testdata/sample.ipynb A basic Python script to print the string 'Hello, World!' to the console. This is a fundamental example for verifying Python execution. ```python print('Hello, World!') ``` -------------------------------- ### Create Morphir Project Directory Source: https://github.com/finos/morphir/blob/main/docs/getting-started/tutorials.md This snippet demonstrates how to create a new directory for a Morphir project and navigate into it. It's a foundational step for starting any new Morphir development. ```shell mkdir scratch cd scratch ``` -------------------------------- ### Validate Morphir Release Setup Source: https://github.com/finos/morphir/blob/main/DEVELOPING.md Performs validation checks for the release setup, ensuring modules are synced with '.goreleaser.yaml', hook scripts exist, and module dependencies are correct. ```bash mise run release:validate ``` -------------------------------- ### Morphir Local Development Environment Setup Source: https://github.com/finos/morphir/blob/main/CI_RELEASE_FAQ.md Details the initial setup for a local Morphir development environment. It involves cloning the repository and running a setup script that configures the workspace using `mise` and `go.work`. This ensures all modules are correctly synchronized and enables cross-module development. ```bash # Clone repository git clone https://github.com/finos/morphir.git cd morphir # Set up workspace mise run setup-workspace # Verify setup mise run verify ``` -------------------------------- ### VFS File Polymorphism Examples (JSON) Source: https://github.com/finos/morphir/blob/main/docs/design/draft/ir/README.md Demonstrates the structure of VFS files for type definitions and specifications using mutually exclusive 'def' and 'spec' keys. This allows for distinguishing between library distributions and specs distributions or dependencies. ```json { "formatVersion": "4.0.0", "name": "user", "def": { "TypeAliasDefinition": { ... } } } ``` ```json { "formatVersion": "4.0.0", "name": "user", "spec": { "TypeAliasSpecification": { ... } } } ``` -------------------------------- ### Install docling-doc Package Source: https://github.com/finos/morphir/blob/main/pkg/docling-doc/README.md This snippet shows how to install the docling-doc Go package using the go get command. This is the first step to using the package in your Go projects. ```bash go get github.com/finos/morphir/pkg/docling-doc ``` -------------------------------- ### Run Simple Generation Example (Bash) Source: https://github.com/finos/morphir/blob/main/pkg/bindings/golang/examples/README.md This command executes the simple generation example using the Go runtime. It demonstrates the process of generating Go code from Morphir IR. ```bash # Run the simple generation example go run simple_gen.go ``` -------------------------------- ### FQName Round-Trip Example (Gleam) Source: https://github.com/finos/morphir/blob/main/docs/design/draft/ir/naming.md Demonstrates the creation and serialization of a Fully Qualified Name (FQName) using `FQName`, `package_path`, `module_path`, and `name_unchecked`. It also shows parsing an FQName string back into an `FQName` object using `fqname_from_string`, ensuring a lossless round-trip. ```gleam // FQName round-trip let fqn = FQName( package_path(path_unchecked([name_unchecked(["morphir"]), name_unchecked(["sdk"])])), module_path(path_unchecked([name_unchecked(["list"])])), name_unchecked(["map"]), ) fqname_to_string(fqn) // "morphir/sdk:list#map" let parsed = fqname_from_string("morphir/sdk:list#map") // Ok(fqn) - lossless round-trip ``` -------------------------------- ### Name Construction from Words (Gleam Example) Source: https://github.com/finos/morphir/blob/main/docs/design/draft/ir/naming.md Demonstrates constructing a `Name` type from a list of words. It shows examples of creating names with simple kebab-case and names involving abbreviations like `(usd)`. The output is an `Ok(Name)` containing the canonical string representation. ```gleam // Construction from words let user_name = name_from_words(["user", "account"]) // Ok(Name) with canonical: "user-account" let amount_usd = name_from_words(["amount", "in", "u", "s", "d"]) // Ok(Name) with canonical: "amount-in-(usd)" ``` -------------------------------- ### Install Elm Tooling (JavaScript) Source: https://github.com/finos/morphir/blob/main/docs/developers/contribution-guide-readme.md Installs essential Elm development tools globally using NPM. This includes the Elm compiler, test runner, formatter, and live server. Requires Node.js and NPM. ```bash npm install -g elm npm install -g elm-test npm install -g elm-format npm install -g elm-live ``` -------------------------------- ### Troubleshoot 'package not found' errors in Morphir Source: https://github.com/finos/morphir/blob/main/DEVELOPING.md This snippet provides commands to troubleshoot 'package not found' errors in the Morphir project. It involves verifying the workspace setup, re-running the setup script, and syncing the workspace. ```bash cat go.work ``` ```bash ./scripts/dev-setup.sh ``` ```bash go work sync ``` -------------------------------- ### Build Morphir from Source Source: https://github.com/finos/morphir/blob/main/docs/getting-started/morphir-go-preview.md Clones the Morphir repository, navigates into the directory, and uses 'mise' to set up and build the project from its source code. The resulting binary will be located in the './bin/morphir' path. ```bash git clone https://github.com/finos/morphir.git cd morphir mise run setup mise run build ``` -------------------------------- ### Get Morphir Go Version Information Source: https://github.com/finos/morphir/blob/main/docs/getting-started/morphir-go-preview.md Retrieves detailed information about the Morphir installation, including version, commit hash, build date, and Go version. Supports options for viewing the changelog or getting JSON output for automation. ```bash # Version and platform info morphir about # View embedded changelog morphir about --changelog # JSON output for automation morphir about --json ``` -------------------------------- ### morphir-elm develop Source: https://github.com/finos/morphir/blob/main/docs/getting-started/installation-and-usage.md Starts a web server to browse Morphir IR and expose developer tools through a web UI. ```APIDOC ## `morphir-elm develop` ### Description This command relies on the JSON produced by `morphir-elm make` and brings up a web server to browse the Morphir IR and associated developer tools. ### Method CLI Command ### Endpoint N/A (Command-line tool) ### Parameters #### Options - **-p, --project-dir** `` - Optional - Root directory of the project where morphir.json is located. (default: ".") ### Request Example ```bash morphir-elm develop --project-dir ./my-morphir-project ``` ### Response #### Success Response (Web Server) - **Web UI** - Access the developer tools and Morphir IR visualization through a web browser at the provided local address (e.g., http://localhost:8080). ``` -------------------------------- ### Morphir Task Execution Commands (Bash) Source: https://github.com/finos/morphir/blob/main/examples/toolchain-config/README.md Illustrates basic commands for executing Morphir tasks, including running a specific target, running a task with a variant, and executing a build workflow. ```bash # Run a target morphir make # Run with a variant morphir gen:scala # Run a workflow morphir build ``` -------------------------------- ### Morphir API: Sample Test URL Source: https://github.com/finos/morphir/blob/main/docs/reference/testing-framework-readme.md An example URL for testing test suites of the `addFunction` in `Morphir.Reference.Model:Issues.Issue410`. ```HTTP http://localhost:8000/function/Morphir.Reference.Model:Issues.Issue410:addFunction ``` -------------------------------- ### go.work Setup Script (Bash) Source: https://github.com/finos/morphir/blob/main/CI_RELEASE_FAQ.md This bash script dynamically discovers all Go modules within the repository by finding 'go.mod' files. It then initializes a go workspace and adds each discovered module to the 'go.work' file, enabling local development across multiple modules. ```bash #!/usr/bin/env bash # 1. Find all go.mod files in the repository find . -name "go.mod" -type f -not -path "*/vendor/*" -not -path "*/node_modules/*" # 2. Initialize workspace go work init # 3. Add each module to workspace for module in "${MODULES[@]}"; do go work use "./$module" done # Result: go.work file with all modules listed ``` -------------------------------- ### Morphir Publish Command Examples Source: https://github.com/finos/morphir/blob/main/docs/design/draft/daemon/packages.md Shows how to use the 'morphir publish' command to upload packages to a configured registry. Examples include publishing the current project, a specific archive file, to a custom registry, performing a dry run, and tagging releases. ```bash # Publish current project morphir publish # Publish specific package file morphir publish dist/my-org-core-1.0.0.morphir.tgz # Publish to specific registry morphir publish --registry https://npm.my-org.com # Dry run (validate without uploading) morphir publish --dry-run # Publish with specific tag (npm) morphir publish --tag beta ``` -------------------------------- ### Morphir V4 Documentation Field Example (JSON) Source: https://github.com/finos/morphir/blob/main/docs/spec/ir/schemas/migration-guide.md An example demonstrating how documentation can be embedded within Morphir V4's Intermediate Representation (IR). This JSON structure shows a 'doc' field within a type definition, intended for human-readable descriptions. ```json { "types": [ [ ["user", "id"], { "access": "Public", "value": { "doc": "Unique identifier for a user", "value": ["TypeAliasSpecification", [], ["Reference", {}, "morphir/sdk:string#String", []]] } } ] ] } ``` -------------------------------- ### NPM: Dev Server Live Command Source: https://github.com/finos/morphir/blob/main/docs/reference/testing-framework-readme.md Command to start the live developer server, typically used after running the Morphir development server. ```Shell npm run dev-server-live ``` -------------------------------- ### Sample Morphir Test Suite JSON Source: https://github.com/finos/morphir/blob/main/docs/reference/testing-framework-readme.md An example of the `morphir-tests.json` file format, demonstrating how to associate test cases with a specific function identified by its FQName. ```JSON [ [ [ [ ["morphir"], ["reference"], ["model"] ] ], [ ["issues"], ["issue", "410"] ], [ "add", "function" ] ], [ { "inputs": [ 4, 5 ], "expectedOutput": 9, "description": "Add" }, { "inputs": [ 14, 15 ], "expectedOutput": 29, "description": "Add" }, { "inputs": [ 10, 1 ], "expectedOutput": 11, "description": "Add" }, { "inputs": [ -10, 1 ], "expectedOutput": -9, "description": "Add" } ] ] ``` -------------------------------- ### Main Morphir Command TUI Setup (Go) Source: https://github.com/finos/morphir/blob/main/cmd/morphir/internal/tui/README.md This Go function initializes the main TUI for Morphir commands. It creates a sidebar listing available commands like 'validate', 'test', and 'build', using the bubbletea framework for the TUI structure. ```go // In cmd/morphir/main.go func runInteractiveMode() error { commands := []*components.SidebarItem{ {ID: "validate", Title: "Validate"}, {ID: "test", Title: "Test"}, {ID: "build", Title: "Build"}, } app := tui.NewApp( tui.WithTitle("Morphir"), tui.WithSidebarTitle("Commands"), tui.WithSidebar(commands), ) return app.Run() } ``` -------------------------------- ### Add New Dependency to Morphir Module Source: https://github.com/finos/morphir/blob/main/DEVELOPING.md Adds a new external dependency to a specific Morphir module (e.g., 'pkg/models') using 'go get' and then synchronizes the workspace. ```bash # Navigate to the module that needs the dependency cd pkg/models # Add the dependency go get github.com/example/package@latest # Sync the workspace cd ../.. go work sync ``` -------------------------------- ### Run Morphir TUI Demo Application (Bash) Source: https://github.com/finos/morphir/blob/main/cmd/morphir/internal/tui/README.md This command navigates to the example directory and executes the TUI demo application using Go. It showcases features like hierarchical navigation, dynamic content loading, and Markdown rendering. ```bash cd cmd/morphir/examples go run tui_demo.go ``` -------------------------------- ### Set up Decoration in Morphir Project using Bash Source: https://github.com/finos/morphir/blob/main/examples/decorations/simple-flag/README.md Sets up a specific decoration, 'myFlag', of the previously registered 'simpleFlag' type within a Morphir project. This prepares the project to use the decoration. ```bash morphir decoration setup myFlag --type simpleFlag ``` -------------------------------- ### Example V3 to V4 Migration Script (Python) Source: https://github.com/finos/morphir/blob/main/docs/spec/ir/schemas/migration-guide.md This Python script provides a practical example of migrating a Morphir IR file from version V3 to V4. It reads a V3 JSON file, performs the migration using a hypothetical `migrate_v3_to_v4` function, and writes the resulting V4 JSON to a new file. ```python import json def migrate_v3_to_v4_file(input_path, output_path): with open(input_path, 'r') as f: ir_v3 = json.load(f) ir_v4 = migrate_v3_to_v4(ir_v3) with open(output_path, 'w') as f: json.dump(ir_v4, f, indent=2) print(f"Migrated {input_path} → {output_path}") # Usage migrate_v3_to_v4_file("morphir-ir-v3.json", "morphir-ir-v4.json") ``` -------------------------------- ### Morphir JSON configuration Source: https://github.com/finos/morphir/blob/main/docs/reference/insight-readme.md Example configuration for morphir.json, specifying the module name, source directory, and exposed modules. This file is used during the translation of Elm sources to Morphir IR. ```json { "name": "Morphir.Reference.Model", "sourceDirectory": "example", "exposedModules": [ "Insight.UseCase1" ] } ``` -------------------------------- ### Install Morphir-Dev Binary Source: https://github.com/finos/morphir/blob/main/AGENTS.md Installs the 'morphir-dev' binary to the Go bin directory. This script ensures the development binary is accessible system-wide. Both bash and PowerShell versions are provided. ```bash #!/usr/bin/env bash set -e # Installs the morphir-dev binary to the Go bin directory GO111MODULE=on go install github.com/finos/morphir/cmd/morphir-dev@latest ``` ```powershell $ErrorActionPreference = "Stop" # Installs the morphir-dev binary to the Go bin directory $env:GO111MODULE = "on" go install github.com/finos/morphir/cmd/morphir-dev@latest ``` -------------------------------- ### Manually Update Dependencies in Morphir Module Source: https://github.com/finos/morphir/blob/main/DEVELOPING.md Updates dependencies for a specific module by navigating to it and using 'go get -u ./...'. This is an alternative to the global 'mod-tidy' command. ```bash cd pkg/models && go get -u ./... cd ../config && go get -u ./... # ... repeat for each module ```