Code Monkey home page Code Monkey logo

kotlin-ace-wrapper's Introduction

Release Build Status

Kotlin + Ace (wrapper)

Ace is a great embeddable code editor which provides a ton of themes and language modes to work with. However, writing new modes or syntax validators is not always easy. Especially since in most cases, you end up writing one parser for the front-end (data entry) and then another for the back-end (data processing). To get rid of this duplicity, we want to use the same language for both front-end and back-end: Kotlin.

Due to various design decisions made by Ace and Kotlin teams, this isn't always as easy as it could be. This library takes away the pain of working with Ace editor inside Kotlin by exposing Ace's API as standard Kotlin classes.

Getting started

There are two main modules:

  • Web: wrapper around Ace APIs for interaction with the code editors, such as EditSession or Tokenizer.
  • Worker: allows creation of web workers, mainly for syntax validation.

Note that the JS files in the worker module are meant to be run in a web worker context, and therefore you should never run them directly in your main website JS context. For more information about workers, see the worker tutorial.

Distribution

You can include the library into any Gradle/Maven project using Jitpack:

repositories {
  ...
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation 'com.github.daemontus.kotlin-ace-wrapper:web:VERSION_HERE'
  // Worker module should not be available in the web context, so your web modules 
  // should not be able to access the module at compile time, only at runtime.
  runtime 'com.github.daemontus.kotlin-ace-wrapper:worker:VERSION_HERE'  
}

This gives you a jar file with all necessary Javascript files. In the demo build.gradle, you can see how to deploy these Javscript files alongside your Kotlin/JS scripts.

This form of distribution is primarily useful for JVM related projects. If you have other, more JS friendly, preferred method of distribution (npm, etc.), please create an issue/pull request with your suggestion.

Versioning

Each version of the wrapper should match the version of the Ace editor for which it was written, suffixed with a wrapper version number. So a wrapper of version 1.3.1-2 is a wrapper of Ace 1.3.1 and it is the version 2 for this specific Ace version. For best results, you should always use matching wrapper and Ace versions, but often no changes are necessary between versions, since Ace API is quite stable.

Set-up

To initialize the web module, simply load the provided JS files in the following order:

<!-- Ace Editor - not included in the distribution. -->
<script src="ace.js" type="text/javascript"></script>

<!-- Class loader - a small piece of JS which exposes the Ace classes to the Kotlin code. -->
<script src="class-loader.js" type="text/javascript"></script>

<!-- Kotlin JS standard library, obviously :) -->
<script src="kotlin.js" type="text/javascript"></script>

<!-- A few common classes shared by the web and worker contexts. -->
<script src="ace-common.js" type="text/javascript"></script>
<!-- All web specific APIs for editor manipulation. -->
<script src="ace-web.js" type="text/javascript"></script>

Once you have the dependencies set-up, you can start loading your own Kotlin code. For a more detailed example see the demo module or some of the tutorials.

Tutorials

To see how to use the wrapper efficiently, please refer to some of the following tutorials:

Demo

The repository contains a simple demo module showcasing the functionality described in the tutorials. It is a simple editor with a custom theme, a custom tokenizer for syntax highlighting (recognizing numbers, parenthesis and numerical operators) and a custom syntax validation worker (checks for unclosed/unexpected parenthesis). You can try it here.

Notes on documentation, completeness and reliability

Currently, the wrapper exposes most methods documented in the Ace API reference and also some undocumented APIs which are necessary for extending Ace's basic functionality. However, there is no comprehensive documentation for the wrapper itself. It would be awesome to have a more detailed documentation in the future. However, this is just a small sideproject, so I mainly maintain and test the features I actually need and the documentation focuses mainly on tutorials. If you find some inconsistency with the actual Ace API or some missing features, feel free to send a pull request or create an issue. Ideally, please provide a use case for testing this problem too.

kotlin-ace-wrapper's People

Contributors

daemontus avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.