SUSHI (aka "SUSHI Unshortens Short Hand Inputs") is a reference implementation command-line interpreter/compiler for FHIR Shorthand (FSH).
FHIR Shorthand (FSH) is a specially-designed language for defining the content of FHIR Implementation Guides (IG). It is simple and compact, with tools to produce Fast Healthcare Interoperability Resources (FHIR) profiles, extensions and implementation guides (IG). Because it is a language, written in text statements, FHIR Shorthand encourages distributed, team-based development using conventional source code control tools such as Github.
For more information about the evolving FSH syntax see the FHIR Shorthand Reference Manual.
SUSHI requires Node.js to be installed on the user's system. Users should install Node.js 12 (LTS), although the previous LTS version (Node.js 10) is also expected to work.
Once Node.js is installed, run the following command to install or update SUSHI:
$ npm install -g fsh-sushiAfter installation, the sushi commandline will be available on your path:
$ sushi --help
Usage: sushi [path-to-fsh-defs] [options]
Options:
-o, --out <out> the path to the output folder
-d, --debug output extra debugging information
-s, --snapshot generate snapshot in Structure Definition output (default: false)
-i, --init initialize a SUSHI project
-v, --version print SUSHI version
-h, --help output usage information
Additional information:
[path-to-fsh-defs]
Default: "."
If input/fsh/ subdirectory present, it is included in [path-to-fsh-defs]
-o, --out <out>
Default: "fsh-generated"
If legacy publisher mode (fsh subdirectory present), default output is parent of "fsh"
If legacy flat mode (no input/fsh or fsh subdirectories present), default output is "build"
See the SUSHI documentation for detailed information on using SUSHI.
SUSHI supports publishing implementation guides via the new template-based IG Publisher. The template-based publisher is still being developed by the FHIR community. See the Guidance for HL7 IG Creation for more details.
Based on the inputs in FSH files, sushi-config.yaml, and the IG project directory, SUSHI populates the output directory. See the documentation on IG Project with SUSHI for more information on using SUSHI to generate IGs.
SUSHI is a TypeScript project. At a minimum, SUSHI requires Node.js to build, test, and run the CLI. Developers should install Node.js 12 (LTS), although the previous LTS version (Node.js 10) is also expected to work.
Once Node.js is installed, run the following command from this project's root folder:
$ npm installThe following NPM tasks are useful in development:
| Task | Description |
|---|---|
| build | compiles src/**/*.ts files to dist/**/*.js files using the TypeScript compiler (tsc) |
| build:watch | similar to build but automatically builds when changes are detected in src files |
| build:grammar | builds the ANTLR grammar from 'antlr/src/main/antlr' to 'src/import/generated' |
| test | runs all unit tests using Jest |
| test:watch | similar to test, but automatically runs affected tests when changes are detected in src files |
| lint | checks all src files to ensure they follow project code styles and rules |
| lint:fix | fixes lint errors when automatic fixes are available for them |
| prettier | checks all src files to ensure they follow project formatting conventions |
| prettier:fix | fixes prettier errors by rewriting files using project formatting conventions |
| check | runs all the checks performed as part of ci (test, lint, prettier) |
| regression | runs regression against the repos in regression/all-repos.txt (mac only) |
To run any of these tasks, use npm run. For example:
$ npm run checkWARNING: The regression script currently works on Mac systems only. It is not expected to work on Windows at this time.
The regression/run-regression.sh script can be used to run regression on a set of repos. It takes the following arguments:
repoFile: A text file for which each line is a GitHub clone URL for a repository to run regression on.#comments out a line. (default: regression/all-repos.txt)version1: The base version of SUSHI to use. Can be a specific version number,github:fhir/sushi#branchto use a GitHub branch, orlocalto use the local code withts-node. (default: github:fhir/sushi)version2: The version of SUSHI under test. Can be a specific version number,github:fhir/sushi#branchto use a GitHub branch, orlocalto use the local code withts-node. (default: local)
For example:
$ regression/run-regression.sh regression/all-repos.txt 0.16.0 localNOTE: Using GitHub branches of SUSHI is slow. This may be optimized in the future.
The regression script will do the following for each repository:
- Clone the repo from GitHub, creating two copies (for the base version of SUSHI and the version under test)
- Run the base version of SUSHI against one copy of the repo
- Run the version of SUSHI under test against the other copy of the repo
- Compare results and generate a report of the differences
When the script is complete, it will generate and launch a top-level index file with links to the reports and logs for each repo.
For the best experience, developers should use Visual Studio Code with the following plugins:
- ESLint
- Prettier - Code formatter
- Consider configuring the formatOnSave feature in VS Code settings:
"[typescript]": { "editor.formatOnSave": true }
- Consider configuring the formatOnSave feature in VS Code settings:
- vscode-language-fsh
Copyright 2019 Health Level Seven International
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.