{"id":15055837,"url":"https://github.com/schleifenkauz/Hextant","last_synced_at":"2025-08-02T08:31:32.460Z","repository":{"id":57721822,"uuid":"140250837","full_name":"schleifenkauz/Hextant","owner":"schleifenkauz","description":"An AST-Editor","archived":false,"fork":false,"pushed_at":"2024-10-07T22:27:35.000Z","size":9071,"stargazers_count":31,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-06T11:12:51.119Z","etag":null,"topics":["ast-representation","editor","ide","javafx-application","kotlin","lisp-editor","source-code"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schleifenkauz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-09T07:57:57.000Z","updated_at":"2024-11-19T14:10:12.000Z","dependencies_parsed_at":"2024-05-28T14:18:00.180Z","dependency_job_id":"6e0aa764-251f-4ffc-b195-1311299ef241","html_url":"https://github.com/schleifenkauz/Hextant","commit_stats":null,"previous_names":["schleifenkauz/hextant","nkb03/hextant"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schleifenkauz%2FHextant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schleifenkauz%2FHextant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schleifenkauz%2FHextant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schleifenkauz%2FHextant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schleifenkauz","download_url":"https://codeload.github.com/schleifenkauz/Hextant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228454012,"owners_count":17922584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast-representation","editor","ide","javafx-application","kotlin","lisp-editor","source-code"],"created_at":"2024-09-24T21:46:39.485Z","updated_at":"2025-08-02T08:31:32.447Z","avatar_url":"https://github.com/schleifenkauz.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hextant - A structural editor\n\n## What is Hextant?\n\nHextant is a structured editor. \nThis means that when you use Hextant, \nwhat you're editing is not the textual representation, but the *Abstract Syntax Tree* of the thing you edit.\nMore precisely, Hextant itself is not a structured editor, \nbut a framework for easily creating structured editors (or *AST-editors*) for different data formats and languages.\n\n## What can be edited with Hextant?\n\nIn principle, everything, that has some well-defined syntax or format, can be edited with Hextant.\nFor example, one could use Hextant to edit:\n- code written in a programming language\n- some data written in markup language like XML\n- an HTML-website\n- an arithmetic expression\n\nBut nothing comes for free. \nTo use Hextant for a specific programming language or data format, \nyou need a plugin (written by you or someone else), \nthat tells Hextant about the shape of the code or data you want to edit \nand what transformations the user should be able to apply to it.\nAs an example, watch this demo of a Hextant plugin for a language similar to Haskell:\n\u003cdiv\u003e\u003c/div\u003e\n\u003ca href=\"http://www.youtube.com/watch?feature=player_embedded\u0026v=09ni_mwsipc\n\" target=\"_blank\"\u003e\u003cimg src=\"http://img.youtube.com/vi/09ni_mwsipc/0.jpg\" \nalt=\"Video could not be loaded\" width=\"560\" height=\"315\"/\u003e\u003c/a\u003e\n\n## How does it work?\n\nAs said above, Hextant is a structured editor (or AST-editor).\nEach node in the Abstract Syntax Tree, you are editing, is represented by one editor in the *editor tree*.\nEditors may either be leaves, or they may be composed of other editors.\nMost of the time, the leave editors (also called **token editors**) are displayed as text fields. \nFor example, an editor for arithmetic expressions may have editors for integer literals as the leaves. \nAs the user types in some characters, the editor checks, \nthat the string typed by the user is indeed a valid integer literal.   \n![Demo couldn't be loaded](gif/literals.gif)  \nOne may argue, that this is at the end yet again a text-based approach,\nbut the distinction to an ordinary text-editor is,\nthat textual representation is only used in the leaves (or \"tokens\" in BNF-jargon) of the editor tree.\nNote, for example, that this editor for integer literals would never recognize a string such as \"1+2\".  \nTo form such an expression, a **compound editor** is needed. \nCompound editors are editors that are composed of other editors.\nFor example in the following GIF there is an editor that is composed of two editors for integer literals\nand one editor for an arithmetic operator.  \n![Demo couldn't be loaded](gif/compound.gif)  \nTo quickly switch between the individual components of a compound editor without using the mouse,\nyou can use the shortcuts ``Ctrl+🡄`` and ``Ctrl+🡆``. \nBy pressing ``Ctrl+M`` (for \"select more\") you select the parent of the currently focused editor\nand the shortcut ``Ctrl+L`` (for \"select less\") lets you select the child of a compound editor that was focused last.  \nYou're probably not very impressed with an editor that can only edit expressions with one operator and two operands.\nWhat we want is a structured editor that can be used to write down every possible arithmetic expression using the four basic operators.\nThis leads us to the next concept: **Expanders**.\nAn expander is an editor that acts as a placeholder that can be filled in by the user. \nExpanders can be in two different states. They can be either *unexpanded* or *expanded*.\nIn the unexpanded state the expander is displayed by a text field. \nIf not focused, unexpanded are highlighted, so that the user knows that the has to fill in a gap in his program.\nThe user can type into that text field and then hit ``Enter`` to expand the text to a concrete editor.\nFor example, in the following GIF, the text \"+\" is expanded to a compound editor for binary expressions with \"+\" as the operator\nand integer literals are expanded to editors for integer literals.  \n![Demo couldn't be loaded](gif/expander.gif)  \nTo replace the editor that was expanded by the placeholder again), the user has to use the keyboard shortcut ``Ctrl+R``.  \nNow suppose, our language of arithmetic expressions is extended with a form ``sum \u003cexpressions...\u003e``, \nthat sums up an arbitrary-size list of expressions.\nTo represent such an expression with a structured editor, \nan editor that is composed of arbitrarily many sub-editors of equal shape is needed.\nIn Hextant, such editors are called **list editors**.  \n![Demo couldn't be loaded](gif/lists_cooler.gif)  \nTo add a new editor to a list editor, the shortcut ``Ctrl+Insert`` is used.\nThe shortcut ``Ctrl+Remove`` removes the selected item.\nLike with compound editors, the arrow keys can be used to traverse the sub-editors. \nNote that using the summation sign in the above GIF is only possible,\nbecause in Hextant, the display of editors is detached from there internal representation.  \nA problem arises, when you have made an expression and now want to multiply it by three.\nWith what the editor is able to do so far, \nyou would have to select the whole expression by repeated use of the ``Ctrl+M``-shortcut\nand then press ``Ctrl+R`` to reset the whole thing.\nThen you would type \"*\" into the expander, expand it, \nretype your whole expression on the left-hand side and put the integer literal \"3\" into the right-hand side.\nThis kind of redundancy is of course intolerable.\nTherefore, Hextant supports **commands**, that implement common transformations of editors.\nFor example, the plugin for editing arithmetic expressions supports a ``wrap`` command,\nthat replaces some expression by binary expression with the selected expression as the left-hand side.\nTo execute a command, you have to select the editor on which the command is to be executed \nand then type the command into the command-line. \nBy hitting ``Enter`` the command is then expanded and editors for the arguments that the command receives are created.\nTyping ``Ctrl+R`` resets the command line.\nTo execute the command you have to type ``Ctrl+Enter``.\nCommands that have no parameters, can be executed by just pressing ``Ctrl+Enter`` \nafter typing them into the command line, without needing to expand them first. \nSome commands also have shortcuts assigned to them.  \n![Demo couldn't be loaded](gif/commands.gif) \n\n## Why use Hextant?\n\nStructural editors, and Hextant in particular Hextant, have a number of important advantages over traditional text-based IDEs.\n\n- Structural editors **don't need to maintain the synchronization \nbetween textual and structural representation** of the edited program. \nThis eliminates a big factor in terms of **IDE-performance**.\n- The editor works with the same internal representation as the compiler/interpreter of the language does\nSo there is **no need for lexing and parsing** the program before compiling/evaluation it.\nThis reduces the time the programmer waits for the interpreter/compiler by a big margin and facilitates **integration of live-coding features** into plugins.\n- The **decoupling of internal representation of the program and display on the screen** is an inherent feature of Hextant's architecture.\nThis enables the coexistence and mixing of more \"text-like\" and more **graphical views** on the edited program.\nAnother advantage following from the decoupling is the possibility of **programming language personalisation**\n- Perhaps the most important point: \nIn absence of a parser, the syntax of the languages supported by plugins are **extensible**.\nDevelopers can create plugins that extend the features and syntax of languages defined by other plugins.\nThese syntax-extension plugins are **modular** in the sense, that different syntax-extensions plugins can be mixed seamlessly.\nFor each project, he works on, a programmer can put together a language that fits his specific needs by installing the adequate plugins.\n\nFor a more detailed discussion of these advantages and of solutions to inconveniences that arise with the use of structural editors,\nsee [this](https://github.com/schleifenkauz/Hextant/wiki/Why-structural-editors) article.\n\n## How to get it working on my computer?\n\nTo run Hextant, you need version 11 of the Java Runtime Environment.\nThe JavaFX SDK is also required, but it can be installed from the setup wizard on demand.\n\n### Using the 'hextup.sh' script\n\nOn Linux systems, just run the following command:\n`bash \u003c(curl -s https://raw.githubusercontent.com/schleifenkauz/Hextant/master/setup/hextup.sh) install`.\nThe command line setup wizard will ask a few questions. In most cases you can pick the default option.\nAfter the installation finished, you can just type `hextant` into the command line to run the launcher.\nTo update Hextant, use\n`bash \u003c(curl -s https://raw.githubusercontent.com/schleifenkauz/Hextant/master/setup/hextup.sh) update`.\n\n### Installing from source\n\nTo build and run Hextant on your computer you need Git and version 11 of the Java Development Kit.\nFollow these steps:  \n\n- Clone the project: ``git clone https://github.com/schleifenkauz/Hextant``.\n- Create the hextant home directory: ``gradlew initialSetup``.\n- Build the project: ``gradlew build``.\n- Publish all the default plugins: ``gradlew hextantPublish``.\n- Run the Hextant Launcher: ``gradlew hextant-main:run``\n\n### Creating, opening, renaming and deleting projects\n\nNo matter whether you built Hextant from source or used the installer, when you launch it, \nthere should appear a window that looks roughly like this:  \n![Image couldn't be loaded](gif/launcher.png)\n- To create a new project, use the command ``create \u003cproject-type\u003e \u003cproject-name\u003e``. \nSome available project types are ``Lisp Project\"`` and ``Expression``. \n- In the window that pops up, you can select additional plugins, you want to use.\n- Click ``Ok`` to open the newly created project.\n- To open the project command line press ``Ctrl+G``.\n- To save the project use ``Ctrl+S`` or type ``save`` into the project command line.\n- To close the project and return to the launcher window use ``Ctrl+Q`` or type ``quit`` into the project command line.\n- To open a project the command ``open \u003cproject\u003e`` can be used from the launcher.\n- Renaming projects can be done with the ``rename \u003cold-name\u003e \u003cnew-name\u003e`` command.\n- The command ``delete \u003cproject\u003e`` deletes a project. \n\n## How to contribute?\n\nThere are essentially three ways in which you can contribute to Hextant.\n\n1. By trying out Hextant and suggesting possible improvements. \nIf you notice some inconvenience while using Hextant or have an idea for a new feature/plugin just open a new issue.\n2. By developing a plugin for your language of choice.\n   You can refer to [this](https://github.com/schleifenkauz/Hextant/wiki/Writing-plugins) tutorial to learn how to write\n   plugins.\n3. By working on the core-framework.\n\nAll three ways of contributing are greatly appreciated. \nIf you have a question feel free to open an issue or write me an email (niko.knop003@gmail.com). ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschleifenkauz%2FHextant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschleifenkauz%2FHextant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschleifenkauz%2FHextant/lists"}