Skip to content

Commit

Permalink
#33: Documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@jaccomoc
jaccomoc committed Nov 9, 2023
1 parent 626c07a commit 4b4cfc5
Show file tree
Hide file tree
Showing 12 changed files with 1,207 additions and 490 deletions.
8 changes: 4 additions & 4 deletions build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,13 @@
plugins {
id 'java-library'
id 'maven-publish'
id 'com.github.johnrengelman.shadow' version '8.1.0'
id 'com.github.johnrengelman.shadow' version '8.1.1'
id 'java'
id 'signing'
}

group 'io.jactl'
version '1.3.0-SNAPSHOT'
version '1.3.0'

repositories {
mavenCentral()
Expand All @@ -38,8 +38,8 @@ sourceSets {
}

dependencies {
implementation 'org.ow2.asm:asm:9.3'
implementation 'org.ow2.asm:asm-util:9.3'
implementation 'org.ow2.asm:asm:9.6'
implementation 'org.ow2.asm:asm-util:9.6'
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.7.0'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.7.0'
}
Expand Down
37 changes: 25 additions & 12 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,19 @@ def fib(x) { x <= 2 ? 1 : fib(x-1) + fib(x-2) }
println "fib(20) = ${fib(20)}"
```

A more advance example that takes a file of markdown and extracts the top level headings to generate a table
of contents:
```groovy
// Sanitise text to make suitable for a link
def linkify = { s/ /-/g; s/[^\w-]//g }
// Find all top level headings in input and generate markdown for table of contents:
stream(nextLine).filter{ /^# /r }
.map{ s/# // }
.map{ "* [$it](#${ linkify(it.toLowerCase()) })" }
.each{ println it }
```

### Compiles to Java bytecode
Jactl scripts compile to bytecode to take advantage of the performance capabilities of the JVM.

Expand Down Expand Up @@ -103,10 +116,12 @@ Jactl scripts can be run from the commandline to replace use of various Unix uti
* Regex matching syntax
* Regex capture variables

See [Language Features](https://jactl.io/language-features) for an overview of the language features.

## Download

To run command line scripts you only need the Jactl jar which can be downloaded from Maven Central:
[https://repo1.maven.org/maven2/io/jactl/jactl/1.2.0/jactl-1.2.0.jar](https://repo1.maven.org/maven2/io/jactl/jactl/1.2.0/jactl-1.2.0.jar)
[https://repo1.maven.org/maven2/io/jactl/jactl/1.3.0/jactl-1.3.0.jar](https://repo1.maven.org/maven2/io/jactl/jactl/1.3.0/jactl-1.3.0.jar)

To download the Jactl REPL, which gives you an interactive shell for trying out Jactl code, see the
[jactl-repl](https://github.com/jaccomoc/jactl-repl) project.
Expand All @@ -117,7 +132,7 @@ To download the Jactl REPL, which gives you an interactive shell for trying out

* Java 11+
* Gradle 8.0.2
* ASM 9.3
* ASM 9.6

### Build

Expand All @@ -144,7 +159,7 @@ To use Jactl you will need to add a dependency on the Jactl library.

In the `dependencies` section of your `build.gradle` file:
```groovy
implementation group: 'io.jactl', name: 'jactl', version: '1.1.0'
implementation group: 'io.jactl', name: 'jactl', version: '1.3.0'
```

### Maven
Expand All @@ -154,20 +169,18 @@ In the `dependencies` section of your `pom.xml`:
<dependency>
<groupId>io.jactl</groupId>
<artifactId>jactl</artifactId>
<version>1.1.0</version>
<version>1.3.0</version>
</dependency>
```

## Learn More

See the [Jactl REPL project](https://github.com/jaccomoc/jactl-repl) for how to download and run the Jactl REPL.

The [Jactl Language Guide](https://jaccomoc.github.io/jactl/language-guide) describes the Jactl Language.
The [Jactl Documentation Site](https://jactl.io) has the complete documentation including a language guide, and
an integration guide.
It should be your first port of call.

The [Jactl Commandline Scripts Guide](https://jaccomoc.github.io/jactl/command-line-scripts) describes how to run Jactl scripts at the commandline.
Related GitHub projects:

The [Jactl Integration Guide](https://jaccomoc.github.io/jactl/integration-guide) describes how to integrate Jactl into an application and how
to provide additional functions and methods to extend the language.
* The [Jactl REPL project](https://github.com/jaccomoc/jactl-repl) provides a simple Read-Eval-Print-Loop shell for running Jactl code interactively.
* The [Jactl-Vertx library](https://github.com/jaccomoc/jactl-vertx) provides some basic Vert.x integration capabilities.

The [Jactl-Vertx library](https://github.com/jaccomoc/jactl-vertx) provides some basic Vert.x integration capabilities
as well as JSON functions, a function for sending a web request, and an example application.
2 changes: 1 addition & 1 deletion docs/_config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ plugins:
- jekyll-feed

content:
jactl_version: 1.2.0
jactl_version: 1.3.0

# Exclude from processing.
# The following items will not be processed, by default.
Expand Down
28 changes: 18 additions & 10 deletions docs/about.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,15 @@ to provide customisations and extensions that had the following characteristics:
I wanted a language that looked completely synchronous but which, under the covers, took care of all the asynchronous
behaviour.

* **Checkpointing**

Ability for script execution state to be checkpointed where necessary and for this state to be able to be persisted
or replicated so that scripts can be restored and resumed from where they were up to when a failure occurs.

The final motivation for writing a new language compiler was that I was looking for something fun to work on and
at some point I had stumbled across a marvellous book called _Crafting Interpreters_ by Robert Nystrom
and this inspired me to want to write my own compiler.
I highly recommend the book and there is even a free web version available from the
[Crafting Interpreters site](https://craftinginterpreters.com/).
at some point I had stumbled across a marvellous book called [Crafting Interpreters](https://craftinginterpreters.com/)
by Robert Nystrom and this inspired me to want to write my own compiler.
I highly recommend the book: as well as being a good introduction to compiler design, it is also a fun read.

# Who is it for?

Expand All @@ -61,22 +65,26 @@ For example, the Jactl commandline scripts and REPL assume a `.jactlrc` [configu
which contains Jactl code that is read and executed at startup to set the values of some properties in a Map.

Other uses would be to provide a customisation mechanism for:
* **Database engine extensions**
* **Real-time applications**
* **Game Engines**
* **Database Engine extensions**
* **Real-time Applications**
* **Backend customisations for complex multi-tenant web applications**
* **FaaS (Function as a Service)**

Scripts could act as functions and their secure nature means that many functions can be served from the same process
to avoid having to spin up instancesor processes for each function
to avoid having to spin up instances or processes for each function

# Getting Started

To get a feel for how the language looks and the type of language features that Jactl offers
see the [Language Features](/language-features) page.

You can download the Jactl library and find the source code for Jactl at GitHub: [jactl](https://github.com/jaccomoc/jactl)

The to start playing wth Jactl you can look at running some simple scripts using the [command line scripts](/command-line-scripts)
facility.
To start playing with Jactl and for testing out code interactively, you can use
the [Read-Evaluate-Print-Loop (REPL) utility](https://github.com/jaccomoc/jactl-repl).

For testing out code interactively, you can also use the [Read-Evaluate-Print-Loop (REPL) utility](https://github.com/jaccomoc/jactl-repl).
To see how to use Jactl from the command line see the page about [command line scripts](/command-line-scripts).

To learn how to integrate Jactl into your application see the [Integration Guide](/integration-guide).

Expand Down
40 changes: 30 additions & 10 deletions docs/index.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ layout: home

Jactl is a powerful scripting language for Java-based applications whose syntax is a combination of bits
borrowed from Java and Groovy, with a dash of Perl thrown in for good measure.
See [Jactl Language Features](/language-features) for a quick overview of some of the language features
or [Jactl Language Guide](/language-guide) for a full description of the language.


<div class="row">
<div class="column" markdown="1">
Expand Down Expand Up @@ -67,7 +70,7 @@ It is especially suited to event-loop/reactive applications due to its built-in
mechanism based on continuations that ensures it never blocks the execution thread on which it is
running.

## Example
## Simple Example

Here is some simple Jactl code:
```groovy
Expand All @@ -86,19 +89,36 @@ def fib(x) { x <= 2 ? 1 : fib(x-1) + fib(x-2) }
println "fib(20) = ${fib(20)}"
```

## More Advanced Example

Here is a more advanced example which streams the input as lines, searches for markdown headings and generates
a table of contents:
```groovy
// Sanitise text to make suitable for a link
def linkify = { s/ /-/g; s/[^\w-]//g }
// Find all top level headings in input and generate markdown for table of contents:
stream(nextLine).filter{ /^# /r }
.map{ s/# // }
.map{ "* [$it](#${ linkify(it.toLowerCase()) })" }
.each{ println it }
```

## Getting Started

See the [Jactl REPL project](https://github.com/jaccomoc/jactl-repl) for how to download and run the Jactl REPL
which provides a quick, interactive, way to run Jactl code.
To get a feel for how the language looks and the type of language features that Jactl offers
see the [Language Features](/language-features) page.

You can download the Jactl library and find the source code for Jactl at GitHub: [jactl](https://github.com/jaccomoc/jactl)

The [Jactl Language Guide](/language-guide) describes the Jactl Language.
To start playing with Jactl and for testing out code interactively, you can use
the [Read-Evaluate-Print-Loop (REPL) utility](https://github.com/jaccomoc/jactl-repl).

The [Jactl Commandline Scripts Guide](/command-line-scripts) describes how to run Jactl scripts at the commandline.
To see how to use Jactl from the command line see the page about [command line scripts](/command-line-scripts).

The [Jactl Integration Guide](/integration-guide) describes how to integrate Jactl into an application and how
to provide additional functions and methods to extend the language.
To learn how to integrate Jactl into your application see the [Integration Guide](/integration-guide).

The [Jactl-Vertx library](https://github.com/jaccomoc/jactl-vertx) provides some basic Vert.x integration capabilities
as well as JSON functions, a function for sending a web request, and an example application.
To integrate Jactl into a [Vert.x](https://vertx.io) based application have a look at the
[jactl-vertx library](https://github.com/jaccomoc/jactl-vertx).

You can find the source code for Jactl at GitHub: [jactl](https://github.com/jaccomoc/jactl)
To learn more about the language itself read the [Language Guide](/language-guide).
34 changes: 17 additions & 17 deletions docs/pages/command-line-scripts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -381,33 +381,33 @@ arg: args

## `.jactlrc` File

At start up time the contents of `~/.jactlrc` are read.
At start up time, the contents of `~/.jactlrc` are read.
This file, if it exists, is itself a Jactl script and allows you to customise the behaviour of the Jactl command
line scripts by setting the values of some global variables.
This file is also used by the Jactl REPL.

At the moment, all the variables are to do with allowing you to customise Jactl by providing your own
At the moment, all the variables relate to allowing you to customise Jactl by providing your own
execution environment (for your event-loop specific application environment) and your own functions/methods.
The values of the following variables can be set:

| Variable | Type | Default Value | Description |
|:--------------------|:-------|:-------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `environmentClass` | String | `io.jactl.DefaultEnv` | The name of the class which will is used to encapsulate the Jactl runtime environment. See [Integration Guide](integration-guide) for more details. |
| `extraJars` | List | `[]` | A list of file names for any additional JARs that should be added to the classpath. |
| `functionClasses` | List | `[]` | A list of classes having a static method called `registerFunctions(JactlEnv env)` that will be invoked at start up. This allows you to dynamically add new functions (from one of the `extraJars` files) to the Jactl runtime. |
| Variable | Type | Default Value | Description |
|:--------------------|:-------|:---------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `environmentClass` | String | `io.jactl.DefaultEnv` | The name of the class which will is used to encapsulate the Jactl runtime environment. See [Integration Guide](integration-guide) for more details. |
| `extraJars` | List | `[]` | A list of file names for any additional JARs that should be added to the classpath. |
| `functionClasses` | List | `[]` | A list of classes having a static method called `registerFunctions(JactlEnv env)` that will be invoked at start up. This allows you to dynamically add new functions (from one of the `extraJars` files) to the Jactl runtime. |

For example, there is a [jactl-vertx project](https://github.com/jaccomoc/jactl-vertx) for use when integrating
with a [Vert.x](https://vertx.io/) based application.
It uses a specific `JactlVertxEnv` environment that delegates event scheduling to Vert.x and provides some
Json methods for converting to/from JSON and an example function for sending/receiving JSON messages over HTTP.
global functions that deal with distributed maps and an example function for sending/receiving JSON messages over HTTP.

Since the `sendReceiveJson()` functions is provided as an example, it lives in the test jar of the jactl-vertx
project.
So to include these additional functions in your Jactl REPL or Jactl command line scripts you need to list
So to include all of these additional functions in your Jactl REPL or Jactl command line scripts you need to list
these two jars in the `extraJars` list.

> **Note**<br/>
> The `jactl-vertx` test jar is built as an "uber" jar and includes the dependencies it needs (including the
> The `jactl-vertx` test jar is built as a "fat" jar and includes the dependencies it needs (including the
> Vert.x libraries) so we don't need to separately list the Vert.x jars as well.
To register these additional functions with the Jactl runtime we need to have created classes that have
Expand All @@ -416,8 +416,8 @@ We then need to tell the runtime the name of these classes so that these static
will in turn register the functions.

For the `jactl-vertx` library, there are two classes that handle the registration of these functions/methods:
* `jactl.vertx.JsonFunctions`
* `jactl.vertx.example.VertxFunctions`
* `jactl.vertx.VertxFunctions`
* `jactl.vertx.example.ExampleFunctions`

We therefore need to list these classes in the `functionClasses` list of our `.jactlrc` file.

Expand All @@ -427,8 +427,8 @@ the Jactl REPL and the Jactl commandline script execution to use Vert.x and thes
environmentClass = 'jactl.vertx.JactlVertxEnv'
extraJars = [ '~/projects/jactl-vertx/build/libs/jactl-vertx-{{ site.content.jactl_version }}.jar',
'~/projects/jactl-vertx/build/libs/jactl-vertx-{{ site.content.jactl_version }}-tests.jar' ]
functionClasses = [ 'jactl.vertx.JsonFunctions',
'jactl.vertx.example.VertxFunctions' ]
functionClasses = [ 'jactl.vertx.VertxFunctions',
'jactl.vertx.example.ExampleFunctions' ]
```

> **Note**<br/>
Expand All @@ -447,12 +447,12 @@ extraJars = [ "$LIBS/jactl-vertx-${VERSION}.jar",
"$LIBS/jactl-vertx-${VERSION}-tests.jar" ]
// List the function registration classes
functionClasses = [ 'jactl.vertx.JsonFunctions',
'jactl.vertx.example.VertxFunctions' ]
functionClasses = [ 'jactl.vertx.VertxFunctions',
'jactl.vertx.example.ExampleFunctions' ]
```

> **Note**<br/>
> The extra jars can also be provided via the normal way of specifying in them your Java classpath if you
> The extra jars can also be provided via the normal way of specifying them in your Java classpath if you
> prefer to do it that way.
To integrate with additional libraries, just add the jars to the `extraJars` list and add any function
Expand Down
Loading

0 comments on commit 4b4cfc5

Please sign in to comment.