Skip to content

Commit

Permalink
Merge pull request #55 from sentrysoftware/feature/update-README-site…
Browse files Browse the repository at this point in the history 
…-CONTRIBUTE

Updated documentation
  • Loading branch information
@bertysentry
bertysentry authored Dec 21, 2023
2 parents af485f3 + 3954c77 commit 749022a
Show file tree
Hide file tree
Showing 6 changed files with 300 additions and 307 deletions.
88 changes: 36 additions & 52 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,79 +1,63 @@
# Contributing

## Boost vs LGPL vs GPL

The original code from Danny Daglas was under the Boost Software License. The current code is now mainly under LGPL, which means it's actually GPLv3, but can be used in non-GPL projects.

**Important:**
## How to build

* The `Jawk.jar`` executable artifact is released under strict GPLv3.
* The `jawk`` Maven artifact is released under LGPL and can be used in non-GPL projects.
Requirements:

Each file includes a license header. Make sure to always include this header.
* [Java 11](https://adoptium.net/)
* [Maven 3.x](https://maven.apache.org/)

To update all Java files to include the header, simply use the command below:
As usual with Maven, you compile, build and test with:

```bash
$ mvn license:update-file-header
mvn verify
```

## How to build
2 artifacts are built:

Jawk uses Maven 2+ as build system, which you have to install first.
If you did so, you can:
* `jawk-<VERSION>.jar`, to be used in downstream projects requiring Jawk
* `jawk-<VERSION>-standalone.jar`, an executable JAR that behaves like `awk` or `gawk`

compile & package:
The [documentation](sentrysoftware.github.io/Jawk) is generated with Maven too:

mvn package

execute:
```bash
mvn site
```

mvn exec:java
For more information about Maven-generated documentation, visit [Maven Site plugin](https://maven.apache.org/plugins/maven-site-plugin/) and [Sentry Maven Skin](https://sentrysoftware.github.io/sentry-maven-skin/).

create project documentation (to be found under `target/site/index.html`):
## Development workflows

mvn site
Please follow this workflow to contribute to this project:

Jawk relies on [BCEL](http://commons.apache.org/bcel/) for parsing AWK scripts.
* Create an issue describing either the problem you're trying to fix, or the feature you would like to add.
* Wait for a feedback from the team, to validate your suggested change will be approved by the maintainer.
* Fork the repository.
* Create a `feature/issue-<NUMBER>-short-description` from the `main` branch.
* **Make sure the project builds with your changes and passes the unit tests!**
* Commit with a clear and concise messages: `Fix issue #NUMBER: ...`.
* Create Pull Request from your branch to the main branch of this repository.
* Wait for the feedback and review!

In this repository, we prefer **merging** over **rebasing**, and **tabs** over **spaces**. Don't fight against it.

## Release

### Prepare "target/" for the release process

mvn release:clean

### Prepare the release
* asks for the release and new snapshot versions to use (for all modules)
* packages
* signs with GPG
* commits
* tags
* pushes to origin
The release to [Maven Central](https://central.sonatype.com/) must be performed using the *Release to Maven Central* GitHub Action, which relies on the shared [Maven Central Release](https://github.com/sentrysoftware/workflows/blob/main/README.md#maven-central-release).

mvn release:prepare
## Licenses

### Perform the release
* checks-out the release tag
* builds
* deploy into Sonatype staging repository

mvn release:perform
The original code from Danny Daglas was under the Boost Software License. The current code is now mainly under LGPL, which means it's actually GPLv3, but can be used in non-GPL projects.

### Promote it on Maven
Moves it from the Sonatype staging to the main Sonatype repo.
**Important:**

1. using the Nexus staging plugin:
* The `Jawk.jar` executable artifact is released under strict GPLv3.
* The `jawk` Maven artifact is released under LGPL and can be used in non-GPL projects.

mvn nexus:staging-close
mvn nexus:staging-release
Each file includes a license header. Make sure to always include this header.

2. ... alternatively, using the web-interface:
* firefox https://oss.sonatype.org
* login
* got to the "Staging Repositories" tab
* select "org.sentrysoftware..."
* "Close" it
* select "org.sentrysoftware.jawk..." again
* "Release" it
To update all Java files to include the header, simply use the command below:

```bash
mvn license:update-file-header
```
193 changes: 9 additions & 184 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Jawk

![GitHub release (with filter)](https://img.shields.io/github/v/release/sentrysoftware/jawk)
![Build](https://img.shields.io/github/actions/workflow/status/sentrysoftware/jawk/deploy.yml)
![GitHub top language](https://img.shields.io/github/languages/top/sentrysoftware/jawk)
![License](https://img.shields.io/github/license/sentrysoftware/jawk)

Jawk is a pure Java implementation of [AWK](https://en.wikipedia.org/wiki/AWK). It executes the specified AWK scripts to parse and process text input, and generate a text output. Jawk can be used as a CLI, but more importantly it can be invoked from within your Java project.

This project is forked from the excellent [Jawk project](https://jawk.sourceforge.net/) that was maintained by [hoijui on GitHub](https://github.com/hoijui/Jawk).
Expand All @@ -8,192 +13,12 @@ This project is forked from the excellent [Jawk project](https://jawk.sourceforg

## Run Jawk CLI

It's very simple:

* Download the [latest release](releases)
* Make sure to have Java installed on your system ([download](https://adoptium.net/))
* Execute **Jawk.jar** just like the "traditional" AWK

Processing of *stdin*:

```bash
$ echo "hello world" | java -jar Jawk.jar '{print $2 ", " $1 "!"}'

world, hello!
```

Execute on Windows (beware of double-double quotes!):

```bash
C:\> echo "hello world" | java -jar Jawk.jar "{print $2 "", "" $1 ""!""}"

world, hello!
```

Classic processing of an input file:

```bash
$ java -jar Jawk.jar -F : '{print $1 "," $6}' /etc/passwd

root,/root
daemon,/usr/sbin
bin,/bin
sys,/dev
sync,/bin
games,/usr/games
man,/var/cache/man
lp,/var/spool/lpd
mail,/var/mail
```

Execute a script file:

**example.awk**:

```awk
BEGIN {
totalUsed = 0
totalAvailable = 0
}
$6 !~ "wsl" && $3 ~ "[0-9]+" {
totalUsed += $3
totalAvailable += $4
}
END {
printf "Total Used: %.1f GB\n", totalUsed / 1048576
printf "Total Available: %.1f GB\n", totalAvailable / 1048576
}
```

```bash
$ df -kP | java -jar Jawk.jar -f example.awk

Total Used: 559.8 GB
Total Available: 2048.0 GB
```

Matrix in your terminal (Linux):

```bash
$ while :;do echo $LINES $COLUMNS $(( $RANDOM % $COLUMNS)) $(printf "\U$(($RANDOM % 500))");sleep 0.05;done|java -jar Jawk.jar '{a[$3]=0;for (x in a){o=a[x];a[x]=a[x]+1;printf "\033[%s;%sH\033[2;32m%s",o,x,$4;printf "\033[%s;%sH\033[1;37m%s\033[0;0H",a[x],x,$4;if (a[x]>=$1){a[x]=0;}}}'
```
See [Jawk CLI documentation](https://sentrysoftware.github.io/Jawk/cli.html)

## Run AWK inside Java

Add the below repository to the list of repositories in your [Maven settings](https://maven.apache.org/settings.html):
```xml
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/sentrysoftware/Jawk</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
```
Add Jawk in the list of dependencies in your [Maven **pom.xml**](https://maven.apache.org/pom.html):
```xml
<dependencies>
<!-- [...] -->
<dependency>
<groupId>org.sentrysoftware</groupId>
<artifactId>jawk</artifactId>
<version>2.1.00-SNAPSHOT</version> <!-- Use the latest version released -->
</dependency>
</dependencies>
```
Invoke AWK scripts files on input files:
```java
/**
* Executes the specified AWK script
* <p>
* @param scriptFile File containing the AWK script to execute
* @param inputFileList List of files that contain the input to be parsed by the AWK script
* @return the printed output of the script as a String
* @throws ExitException when the AWK script forces its exit with a specified code
* @throws IOException on I/O problems
*/
private String runAwk(File scriptFile, List<String> inputFileList) throws IOException, ExitException {

AwkSettings settings = new AwkSettings();

// Set the input files
settings.getNameValueOrFileNames().addAll(inputFileList);

// Create the OutputStream, to collect the result as a String
ByteArrayOutputStream resultBytesStream = new ByteArrayOutputStream();
settings.setOutputStream(new PrintStream(resultBytesStream));

// Sets the AWK script to execute
settings.addScriptSource(new ScriptFileSource(scriptFile.getAbsolutePath()));

// Execute the awk script against the specified input
Awk awk = new Awk();
awk.invoke(settings);

// Return the result as a string
return resultBytesStream.toString(StandardCharsets.UTF_8);

}
```
Execute AWK script (as String) on String input:
```java
/**
* Executes the specified script against the specified input
* <p>
* @param script AWK script to execute (as a String)
* @param input Text to process (as a String)
* @return result as a String
* @throws ExitException when the AWK script forces its exit with a specified code
* @throws IOException on I/O problems
*/
private String runAwk(String script, String input) throws IOException, ExitException {

AwkSettings settings = new AwkSettings();

// Set the input files
settings.setInput(new ByteArrayInputStream(input.getBytes(StandardCharsets.UTF_8)));

// We force \n as the Record Separator (RS) because even if running on Windows
// we're passing Java strings, where end of lines are simple \n
settings.setDefaultRS("\n");
// Create the OutputStream, to collect the result as a String
ByteArrayOutputStream resultBytesStream = new ByteArrayOutputStream();
settings.setOutputStream(new UniformPrintStream(resultBytesStream));
// Sets the AWK script to execute
settings.addScriptSource(new ScriptSource("Body", new StringReader(script), false));
// Execute the awk script against the specified input
Awk awk = new Awk();
awk.invoke(settings);
// Return the result as a string
return resultBytesStream.toString(StandardCharsets.UTF_8);
}
```
## Differences with `gawk`
List...
## Differences with the original Jawk
See [AWK in Java documentation](https://sentrysoftware.github.io/Jawk/java.html)

There's a growing list of things that make our version diverge from the original Jawk written by Danny Daglas, and maintained by Robin Vobruba:
## Contributing

* Replaced [Logback](https://logback.qos.ch/) with the [SimpleLogger](https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html) that comes with [SLF4J](https://www.slf4j.org/)
* Removed the AWK-to-JVM bytecode compiler
* Removed the Socket extension (to get a smaller jar)
* Improved performance in parsing inputs and printed output
* Support for long integers
* Support for octal and hexadecimal notation in strings (allowing `ESC`` characters to do fancy terminal effects)
* Artifact *groupId* and package is `org.sentrysoftware`
* Added gawk's suite of unit tests
* License is LGPL for the Maven artifact
See [CONTRIBUDING.md](CONTRIBUTING.md).
Loading

0 comments on commit 749022a

Please sign in to comment.