Skip to content

Commit 4b4cfc5

Browse files
jaccomocjaccomoc
committed
#33: Documentation updates
1 parent 626c07a commit 4b4cfc5

File tree

12 files changed

+1207
-490
lines changed

12 files changed

+1207
-490
lines changed

‎build.gradle

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@
1717
plugins {
1818
id 'java-library'
1919
id 'maven-publish'
20-
id 'com.github.johnrengelman.shadow' version '8.1.0'
20+
id 'com.github.johnrengelman.shadow' version '8.1.1'
2121
id 'java'
2222
id 'signing'
2323
}
2424

2525
group 'io.jactl'
26-
version '1.3.0-SNAPSHOT'
26+
version '1.3.0'
2727

2828
repositories {
2929
mavenCentral()
@@ -38,8 +38,8 @@ sourceSets {
3838
}
3939

4040
dependencies {
41-
implementation 'org.ow2.asm:asm:9.3'
42-
implementation 'org.ow2.asm:asm-util:9.3'
41+
implementation 'org.ow2.asm:asm:9.6'
42+
implementation 'org.ow2.asm:asm-util:9.6'
4343
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.7.0'
4444
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.7.0'
4545
}

‎docs/README.md

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,19 @@ def fib(x) { x <= 2 ? 1 : fib(x-1) + fib(x-2) }
3232
println "fib(20) = ${fib(20)}"
3333
```
3434

35+
A more advance example that takes a file of markdown and extracts the top level headings to generate a table
36+
of contents:
37+
```groovy
38+
// Sanitise text to make suitable for a link
39+
def linkify = { s/ /-/g; s/[^\w-]//g }
40+
41+
// Find all top level headings in input and generate markdown for table of contents:
42+
stream(nextLine).filter{ /^# /r }
43+
.map{ s/# // }
44+
.map{ "* [$it](#${ linkify(it.toLowerCase()) })" }
45+
.each{ println it }
46+
```
47+
3548
### Compiles to Java bytecode
3649
Jactl scripts compile to bytecode to take advantage of the performance capabilities of the JVM.
3750

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

119+
See [Language Features](https://jactl.io/language-features) for an overview of the language features.
120+
106121
## Download
107122

108123
To run command line scripts you only need the Jactl jar which can be downloaded from Maven Central:
109-
[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)
124+
[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)
110125

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

118133
* Java 11+
119134
* Gradle 8.0.2
120-
* ASM 9.3
135+
* ASM 9.6
121136

122137
### Build
123138

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

145160
In the `dependencies` section of your `build.gradle` file:
146161
```groovy
147-
implementation group: 'io.jactl', name: 'jactl', version: '1.1.0'
162+
implementation group: 'io.jactl', name: 'jactl', version: '1.3.0'
148163
```
149164

150165
### Maven
@@ -154,20 +169,18 @@ In the `dependencies` section of your `pom.xml`:
154169
<dependency>
155170
<groupId>io.jactl</groupId>
156171
<artifactId>jactl</artifactId>
157-
<version>1.1.0</version>
172+
<version>1.3.0</version>
158173
</dependency>
159174
```
160175

161176
## Learn More
162177

163-
See the [Jactl REPL project](https://github.com/jaccomoc/jactl-repl) for how to download and run the Jactl REPL.
164-
165-
The [Jactl Language Guide](https://jaccomoc.github.io/jactl/language-guide) describes the Jactl Language.
178+
The [Jactl Documentation Site](https://jactl.io) has the complete documentation including a language guide, and
179+
an integration guide.
180+
It should be your first port of call.
166181

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

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

172-
The [Jactl-Vertx library](https://github.com/jaccomoc/jactl-vertx) provides some basic Vert.x integration capabilities
173-
as well as JSON functions, a function for sending a web request, and an example application.

‎docs/_config.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ plugins:
3636
- jekyll-feed
3737

3838
content:
39-
jactl_version: 1.2.0
39+
jactl_version: 1.3.0
4040

4141
# Exclude from processing.
4242
# The following items will not be processed, by default.

‎docs/about.markdown

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,15 @@ to provide customisations and extensions that had the following characteristics:
4545
I wanted a language that looked completely synchronous but which, under the covers, took care of all the asynchronous
4646
behaviour.
4747

48+
* **Checkpointing**
49+
50+
Ability for script execution state to be checkpointed where necessary and for this state to be able to be persisted
51+
or replicated so that scripts can be restored and resumed from where they were up to when a failure occurs.
52+
4853
The final motivation for writing a new language compiler was that I was looking for something fun to work on and
49-
at some point I had stumbled across a marvellous book called _Crafting Interpreters_ by Robert Nystrom
50-
and this inspired me to want to write my own compiler.
51-
I highly recommend the book and there is even a free web version available from the
52-
[Crafting Interpreters site](https://craftinginterpreters.com/).
54+
at some point I had stumbled across a marvellous book called [Crafting Interpreters](https://craftinginterpreters.com/)
55+
by Robert Nystrom and this inspired me to want to write my own compiler.
56+
I highly recommend the book: as well as being a good introduction to compiler design, it is also a fun read.
5357

5458
# Who is it for?
5559

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

6367
Other uses would be to provide a customisation mechanism for:
64-
* **Database engine extensions**
65-
* **Real-time applications**
68+
* **Game Engines**
69+
* **Database Engine extensions**
70+
* **Real-time Applications**
6671
* **Backend customisations for complex multi-tenant web applications**
6772
* **FaaS (Function as a Service)**
6873

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

7277
# Getting Started
7378

79+
To get a feel for how the language looks and the type of language features that Jactl offers
80+
see the [Language Features](/language-features) page.
81+
7482
You can download the Jactl library and find the source code for Jactl at GitHub: [jactl](https://github.com/jaccomoc/jactl)
7583

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

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

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

‎docs/index.markdown

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ layout: home
66

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

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

70-
## Example
73+
## Simple Example
7174

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

92+
## More Advanced Example
93+
94+
Here is a more advanced example which streams the input as lines, searches for markdown headings and generates
95+
a table of contents:
96+
```groovy
97+
// Sanitise text to make suitable for a link
98+
def linkify = { s/ /-/g; s/[^\w-]//g }
99+
100+
// Find all top level headings in input and generate markdown for table of contents:
101+
stream(nextLine).filter{ /^# /r }
102+
.map{ s/# // }
103+
.map{ "* [$it](#${ linkify(it.toLowerCase()) })" }
104+
.each{ println it }
105+
```
106+
89107
## Getting Started
90108

91-
See the [Jactl REPL project](https://github.com/jaccomoc/jactl-repl) for how to download and run the Jactl REPL
92-
which provides a quick, interactive, way to run Jactl code.
109+
To get a feel for how the language looks and the type of language features that Jactl offers
110+
see the [Language Features](/language-features) page.
111+
112+
You can download the Jactl library and find the source code for Jactl at GitHub: [jactl](https://github.com/jaccomoc/jactl)
93113

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

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

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

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

104-
You can find the source code for Jactl at GitHub: [jactl](https://github.com/jaccomoc/jactl)
124+
To learn more about the language itself read the [Language Guide](/language-guide).

‎docs/pages/command-line-scripts.md

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -381,33 +381,33 @@ arg: args
381381

382382
## `.jactlrc` File
383383

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

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

393-
| Variable | Type | Default Value | Description |
394-
|:--------------------|:-------|:-------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
395-
| `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. |
396-
| `extraJars` | List | `[]` | A list of file names for any additional JARs that should be added to the classpath. |
397-
| `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. |
393+
| Variable | Type | Default Value | Description |
394+
|:--------------------|:-------|:---------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
395+
| `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. |
396+
| `extraJars` | List | `[]` | A list of file names for any additional JARs that should be added to the classpath. |
397+
| `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. |
398398

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

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

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

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

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

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

434434
> **Note**<br/>
@@ -447,12 +447,12 @@ extraJars = [ "$LIBS/jactl-vertx-${VERSION}.jar",
447447
"$LIBS/jactl-vertx-${VERSION}-tests.jar" ]
448448
449449
// List the function registration classes
450-
functionClasses = [ 'jactl.vertx.JsonFunctions',
451-
'jactl.vertx.example.VertxFunctions' ]
450+
functionClasses = [ 'jactl.vertx.VertxFunctions',
451+
'jactl.vertx.example.ExampleFunctions' ]
452452
```
453453

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

0 commit comments

Comments
 (0)