Skip to content

feat(docs): Add comprehensive CLI documentation suite #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mtorres11 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(docs): Add comprehensive CLI documentation suite #301

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3cf474e
feat(docs): Add comprehensive CLI documentation suite
mtorres-RMS Oct 2, 2025
39a802e
Address PR feedback: improve CLI documentation
mtorres-RMS Oct 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions fusion/src/cli_quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Get up and running with the Ion Fusion CLI in minutes. This guide covers install
### Option 1: Build from Source (Recommended)

**Prerequisites:**
- Java 8 or later ([Amazon Corretto](https://aws.amazon.com/corretto/) recommended)
- Java 8 or later ([Corretto](https://aws.amazon.com/corretto/) recommended)
- Git

**Steps:**
Expand Down Expand Up @@ -114,7 +114,7 @@ fusion repl

### Data Processing
```bash
# Process JSON-like data
# Process Ion data
echo '{"count": 5}' | fusion eval '(define data (read)) (+ (. data "count") 10)'
```

Expand Down Expand Up @@ -142,7 +142,7 @@ echo "21" | fusion load process.fusion
## Key Concepts

### Ion Data Format
Fusion uses Amazon Ion as its data format:
Fusion uses [Amazon Ion](https://ion-fusion.dev/) as its data format:
Copy link
Copy Markdown
Contributor

@SharkBaitDLS SharkBaitDLS Oct 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the unclear comment -- I mean we should link to the Amazon Ion official site (i.e https://amazon-ion.github.io/ion-docs/) not the Fusion one

```fusion
null ; Null value
true false ; Booleans
Expand Down Expand Up @@ -210,9 +210,7 @@ fusion help <command> # Detailed command help
```

### Community
Comment thread
mtorres11 marked this conversation as resolved.
- [GitHub Issues](https://github.com/ion-fusion/fusion-java/issues) - Bug reports and feature requests
- [Discussions](https://github.com/orgs/ion-fusion/discussions) - Questions and community help
- [Slack](https://join.slack.com/t/ion-fusion/shared_invite/zt-2y0jr8vh2-bZLa66hdyZ3ykHcgOcYkcA) - Real-time chat
Visit the [Ion Fusion Community](https://ion-fusion.dev/community/) page for support resources, discussions, and ways to get involved.

### Documentation
- [CLI Reference](cli_reference.html) - Complete command reference
Expand Down
2 changes: 1 addition & 1 deletion fusion/src/cli_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -462,7 +462,7 @@ OutOfMemoryError
**Large Data Processing:**
Comment thread
mtorres11 marked this conversation as resolved.
- Use streaming operations when possible
- Process data in chunks rather than loading everything into memory
- Consider using Ion binary format for better performance
- Use efficient operations like struct lookups with `elt` over nested access with `.`

**Module Loading:**
- Organize modules efficiently to minimize loading time
Expand Down
27 changes: 21 additions & 6 deletions fusion/src/cli_troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,12 +70,21 @@ Error: Could not find or load main class dev.ionfusion.fusion.cli.Cli

2. **Ensure Java 8 or later is installed:**
```bash
# Install Amazon Corretto (recommended)
# Install Corretto (recommended)
# macOS with Homebrew:
Comment thread
mtorres11 marked this conversation as resolved.
brew install --cask corretto8

# Ubuntu/Debian:
# macOS with MacPorts:
sudo port install openjdk8-corretto

# Ubuntu/Debian (OpenJDK):
sudo apt-get install openjdk-8-jdk
Comment thread
mtorres11 marked this conversation as resolved.

# Ubuntu/Debian (Corretto):
wget -O- https://apt.corretto.aws/corretto.key | sudo apt-key add -
sudo add-apt-repository 'deb https://apt.corretto.aws stable main'
sudo apt-get update
sudo apt-get install java-1.8.0-amazon-corretto-jdk
```

3. **Check JAVA_HOME environment variable:**
Expand Down Expand Up @@ -375,18 +384,24 @@ Data processing is slower than expected.

Comment on lines +352 to +384
Copy link
Copy Markdown
Member

@toddjonker toddjonker Oct 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, these bits are not CLI specific.

I really don't want to end up with similar/same content in multiple documents, that increases maintenance burden. Better to cross-link generously. (Best to have fluid documents that can transclude relevent content, but that's not possible today.)

**Solutions:**
Comment thread
mtorres11 marked this conversation as resolved.

1. **Use Ion binary format:**
1. **Use efficient Fusion operations:**
```bash
# Convert to binary for faster processing
fusion eval '(ionize_to_blob data)' > data.10n
# Use struct lookups with elt over nested access
fusion eval '(elt data "field")' # instead of (. data "field")
```
Comment on lines +387 to +391
Copy link
Copy Markdown
Member

@toddjonker toddjonker Oct 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should be recommending this kind of micro-optimization. At the very least, we should have data that shows it's worth recommending, and when.


2. **Optimize algorithms:**
2. **Avoid deeply nested loops:**
```bash
# Use built-in functions when possible
fusion require '/fusion/list' ';' eval '(map process-fn data)'
```

3. **Optimize algorithms:**
```bash
# Use performant operations like struct lookups
fusion require '/fusion/struct' ';' eval '(struct_get data "key")'
```

3. **Profile with coverage tools:**
```bash
fusion --repositories ./modules load --profile script.fusion
Expand Down
10 changes: 3 additions & 7 deletions fusion/src/howto_build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ fusion version
### Method 1: Build from Source (Recommended)

**Prerequisites:**
- Java 8 or later ([Amazon Corretto][] recommended)
- [Git][]
- Java 8 or later ([Corretto](https://aws.amazon.com/corretto/) recommended)
- [Git](https://git-scm.com/)
- Internet connection (for downloading dependencies)

**Advantages:**
Expand Down Expand Up @@ -163,7 +163,7 @@ export JAVA_HOME=/path/to/java8

**Java Requirements:**
- **Version:** Java 8 or later (Java 11+ recommended for better performance)
- **Distribution:** Any OpenJDK distribution (Amazon Corretto, AdoptOpenJDK, etc.)
- **Distribution:** Any OpenJDK distribution (Corretto, AdoptOpenJDK, etc.)

### Build Troubleshooting

Expand Down Expand Up @@ -369,7 +369,3 @@ With Ion Fusion installed, you're ready to start coding:
- **[Discussions](https://github.com/orgs/ion-fusion/discussions)** - Questions and help

Happy coding with Ion Fusion!


[Amazon Corretto]: https://aws.amazon.com/corretto
[Git]: https://git-scm.com/
4 changes: 2 additions & 2 deletions fusion/src/tutorial_cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ export PATH=$PATH:$PWD/build/install/fusion/bin
- Unpack and add `bin` directory to your `PATH`

**Requirements:**
- Java runtime, version 8 or later ([Amazon Corretto][] recommended)
- Java runtime, version 8 or later ([Corretto][] recommended)
- `java` must be on your shell's `PATH`

**Verify Installation:**
Expand Down Expand Up @@ -453,7 +453,7 @@ Consider using Fusion for:
Happy coding with Ion Fusion!


[Amazon Corretto]: https://aws.amazon.com/corretto
[Corretto]: https://aws.amazon.com/corretto
[CONTRIBUTORS]: https://github.com/ion-fusion/fusion-java/blob/main/CONTRIBUTORS.md
[SDK]: https://github.com/ion-fusion/fusion-java/releases
[sexp]: https://amazon-ion.github.io/ion-docs/docs/spec.html#sexp
Expand Down
1 change: 0 additions & 1 deletion gradle/gradle.properties
View file
Open in desktop

This file was deleted.

34 changes: 0 additions & 34 deletions setup-java8-gradle.sh
View file
Open in desktop

This file was deleted.