{ "info": { "author": "Seven Bridges Genomics Inc.", "author_email": "kaushik.ghose@sbgenomics.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Natural Language :: English", "Operating System :: POSIX", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.7" ], "description": "# Benten\n\nThis is a [language server] for\n[Common Workflow Language](https://www.commonwl.org/) documents.\n\n[language server]: https://langserver.org/\n\n[](https://github.com/rabix/benten/actions?query=workflow%3ATests)\n[](https://codecov.io/gh/rabix/benten)\n[](https://www.codacy.com/app/kaushik-work/benten?utm_source=github.com&utm_medium=referral&utm_content=rabix/benten&utm_campaign=Badge_Grade)\n[](https://badge.fury.io/py/benten)\n [](https://anaconda.org/conda-forge/benten)\n[](https://marketplace.visualstudio.com/items?itemName=sbg-rabix.benten-cwl)\n[](https://open-vsx.org/extension/sbg-rabix/benten-cwl)\n\n## Features\n\n[(Click for feature screenshot gallery)](https://github.com/rabix/benten/blob/master/docs/features.md)\n\n- Syntax highlighting (CWL and JS)\n- Evaluate expression on hover\n- File path autocomplete for linked files in `run` field\n- Port completion for workflow\n- Navigate to linked sub-workflows and includes (Jump to definition)\n- Outline view (Symbols) + Step symbols\n- Type validations\n- Port validations\n- Display language documentation on hover\n\n\n\n\n_Benten_ is written using Python3 and developed against VS Code. The language\nserver component will work with any editor/IDE that offers language server\nsupport. Syntax highlighting is currently only available for the VS Code\nextension. The VS Code extension is written in Typescript.\n\n# Install VS Code extension\n\nSearch for\n\"[Benten](https://marketplace.visualstudio.com/items?itemName=sbg-rabix.benten-cwl)\"\nin the marketplace. The name of the client extension is Rabix/benten. Follow the\nusual method to install the extension.\n\nIf you have not installed the Benten server separately (see below) then the\nclient will attempt to find and download a matching server version from the\ngithub releases page.\n\n# Server installation\n\nBenten requires [Python 3.7 or later](https://www.python.org/downloads/)\n\nIf you will be installing from source you will need\n[git](https://git-scm.com/downloads) on your system\n\n\n## Using pipx\n\nA neat way to install `benten` in a virtual env (isolating it from your\nsystem python) and still be able to call it as a regular executable is\nto use `pipx`\n\n```\npip3 install pipx # in case you don't have pipx\npipx ensurepath # ensures CLI application directory is on your $PATH\n```\n\nNow you can install Benten with\n```\npipx install benten\n```\n\nIf you already have Benten installed you can upgrade it\n```\npipx upgrade benten\n```\n\n\nIf your base python install is earlier than 3.7 you can tell `pipx` to use 3.7 for Benten\n```\npipx install benten --python python3.7\n```\n\n\nNotes:\n\n1. `pipx` installs the executables in `$HOME/.local/bin`\n (`%HOMEPATH%\\.local\\bin` for Windows). This needs to be added to your\n PATH env variable. `pipx ensurepath` does this for you\n2. `pipx install` can be done from within another virtual environment.\n This is helpful when you have an incompatible global version of\n Python which you wish to keep but still want to install Benten. You\n can create a virtual env with Python > 3.7 and invoke the\n installation commands from there.\n3. If you are using VS Code, if you install the server after loading a CWL file\n you will have to restart VS Code.\n\n### Special instructions for Ubuntu Linux\n\n```\nsudo apt install python3-pip python3-venv\n```\n\n### Note for Windows\nIf you are trying to reinstall or updating the server on windows with\nthe server running (e.g. because you have VS Code running), you will\nhave to shutdown the server (e.g. by exiting VS Code) before updating.\n\n\n### Installing versions directly from github\n\nTo install from the master branch\n```\npipx install git+https://github.com/rabix/benten.git\n```\n\nTo install from develop branch (or some other branch):\n```\npipx install git+https://github.com/rabix/benten.git@develop\n```\n\nOr, if you have cloned the repository and want to play with the server\ncode itself:\n```\npipx install -e benten # benten is the name of the directory with the cloned code\n```\n\n# Using with VI/Vim\n\nSee [this page](https://github.com/rabix/benten/blob/master/docs/vim.md) please.\n\n\n# Expression evaluations on hover\n\nHovering over an expression will display the result of the evaluation or\nany errors that are encountered. Benten auto-generates sample process\ninputs, outputs and intermediate outputs (if the process is a workflow).\nNote that these are all randomly generated sample data meant for quick\nsanity checking of expressions.\n\n\n## Over-riding auto-generated sample data\n\nThe sample data is auto-generated on demand when an evaluation is\nrequested. The generated sample data is also stored in a scratch file.\nThis scratch file can be accessed by clicking \"go to definition\" when\nover any expression. Normally this file is just overwritten each time\nwith fresh, randomly generated data.\n\nIf you wish to customize some of the sample data (for example you have\nspecific test cases you want to check as you code the workflow) if you\nadd the string (exactly)\n\n```\n#custom\n```\n\nto the first line of the sample data file, Benten will stop overwriting\nthe file and use the contents of this customized file instead.\n\n**Once you add this line to the sample data file, Benten will no longer\noverwrite this file. If you want the test data to be regenerated (e.g.\nyou've changed the input schema of the CWL) you need to remove this\nfirst sentinel line and Benten will regenerate the input.**\n\n\n# Other tips and Tricks\n\nBenten attaches onto your regular text editor and offers help by\nway of auto-completions and document validations, so most of its\nfunctionality is exposed naturally via the editor's regular UI, and a\nspecialized tutorial is not necessary, but some helpful\n[tips and tricks](docs/tips.md) are listed in this page.\n\n\n# For developers\nSee the [development documentation](docs/developer.md)\n\n\n# License\n[Apache 2.0](LICENSE)\n\n\n# Acknowledgments\n\n[Peter Amstutz](https://github.com/tetron/) for the PyInstaller formula and the\nauto-downloading feature on the VS Code extension.\n\n[Peter van Heusden](https://github.com/pvanheus/) for the\nBenten Conda [distribution](https://github.com/conda-forge/benten-feedstock).\n\nThe low level client-server communication [code][jsonrpc-code] is taken from [Sourcegraph's\n(now defunct) Python Language Server][sourcegraph-python] as is the VS Code client code (which\nwas based originally off Microsoft's example code). The CWL preview uses [vis.js]\n\n[jsonrpc-code]: https://github.com/sourcegraph/python-langserver/blob/master/langserver/jsonrpc.py\n[sourcegraph-python]: https://github.com/sourcegraph/python-langserver\n[vis.js]: http://visjs.org/\n\n# What's in a name?\n\n**Saraswati** is the Hindu goddess of learning and knowledge and a long time ago\nshe visited Japan, where she is known as [Benzaiten] (**Benten** for short) and\nher sitar has morphed into a Japanese _biwa_ but she has kept some of her many arms.\n\nBenzaiten is the goddess of everything that flows: water, time, words, speech,\neloquence, music and by extension, knowledge. Therefore _Benten_ is an\nappropriate goddess for scientific workflow developers.\n\n[Benzaiten]: https://en.wikipedia.org/wiki/Benzaiten\n\n_References_\n- [Wikipedia page](https://en.wikipedia.org/wiki/Benzaiten)\n- [Benzaiten (Benten): Japan\u2019s Goddess of Reason ](http://yabai.com/p/3200) - a much more detailed history\n\n---\n\n