Skip to content

Commit 5e2e3c6

Browse files
yahyafatiyahyafati
committed
Added README.md and CONTRIBUTING.md files
1 parent 9e14c28 commit 5e2e3c6

File tree

5 files changed

+284
-24
lines changed

5 files changed

+284
-24
lines changed

‎CONTRIBUTING.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Contributing to AshJ
2+
3+
Thank you for your interest in contributing to AshJ! By contributing, you’re helping to improve a dynamic, lightweight
4+
programming language that’s open to everyone. Whether you’re reporting a bug, proposing a feature, or submitting a pull
5+
request, your contributions are valuable.
6+
7+
## Table of Contents
8+
9+
- [Getting Started](#getting-started)
10+
- [How to Contribute](#how-to-contribute)
11+
- [Reporting Bugs](#reporting-bugs)
12+
- [Suggesting Enhancements](#suggesting-enhancements)
13+
- [Pull Requests](#pull-requests)
14+
- [Code Style](#code-style)
15+
- [Testing](#testing)
16+
- [Branching Model](#branching-model)
17+
- [License](#license)
18+
19+
## Getting Started
20+
21+
1. **Fork the Repository**: Start by forking the repository to your GitHub account.
22+
2. **Clone Your Fork**: Clone your forked repository to your local machine.
23+
24+
```bash
25+
git clone https://github.com/yahyafati/ashj-lang.git
26+
cd ashj
27+
```
28+
29+
3. **Create a New Branch**: Create a new branch for your work.
30+
31+
```bash
32+
git checkout -b feature/your-feature-name
33+
```
34+
35+
4. **Make Your Changes**: Start making changes to the codebase.
36+
37+
## How to Contribute
38+
39+
### Reporting Bugs
40+
41+
If you find a bug in AshJ, we’d love to hear about it. To report a bug:
42+
43+
1. **Check Existing Issues**: Before submitting a new issue, please check
44+
the [issue tracker](https://github.com/yahyafati/ashj-lang/issues) to see if the bug has already been reported.
45+
46+
2. **Submit a New Issue**: If the bug is not listed, create a new issue and include:
47+
- A clear and descriptive title.
48+
- A detailed description of the bug.
49+
- Steps to reproduce the bug.
50+
- Expected and actual results.
51+
- Any relevant logs or screenshots.
52+
53+
### Suggesting Enhancements
54+
55+
If you have an idea for a new feature or an improvement to existing functionality:
56+
57+
1. **Check Existing Issues/Discussions**: See if your suggestion is already being discussed in
58+
the [issue tracker](https://github.com/yahyafati/ashj-lang/issues)
59+
or [discussions](https://github.com/yahyafati/ashj-lang/discussions).
60+
61+
2. **Submit a New Issue**: If your suggestion is new, submit an issue with:
62+
- A clear and descriptive title.
63+
- A detailed explanation of the feature or enhancement.
64+
- Any relevant examples or use cases.
65+
66+
### Pull Requests
67+
68+
1. **Fork and Clone**: Make sure your fork is up to date with the latest `main` branch from the original repository.
69+
70+
```bash
71+
git pull upstream main
72+
```
73+
74+
2. **Commit Your Changes**: Write clear, descriptive commit messages and group related changes into a single commit.
75+
76+
```bash
77+
git commit -m "Add feature X"
78+
```
79+
80+
3. **Push Your Branch**: Push your branch to your forked repository.
81+
82+
```bash
83+
git push origin feature/your-feature-name
84+
```
85+
86+
4. **Open a Pull Request**: Go to the original repository on GitHub and open a pull request. Provide a detailed
87+
description of your changes and link to any relevant issues.
88+
89+
## Code Style
90+
91+
Please adhere to the following guidelines to maintain a consistent code style:
92+
93+
- **Indentation**: Use 4 spaces for indentation.
94+
- **Line Length**: Limit lines to 80 characters.
95+
- **Naming Conventions**: Use `camelCase` for variables and functions, and `PascalCase` for classes.
96+
- **Comments**: Use comments to explain why something is done, not what is done.
97+
98+
## Testing
99+
100+
Before submitting a pull request, ensure that your changes are covered by tests and that all tests pass:
101+
102+
1. **Run Tests**: Use the provided test suite to run all tests.
103+
104+
```bash
105+
./run_tests.sh
106+
```
107+
108+
2. **Add Tests**: If you’re adding a new feature, include corresponding tests in the `tests` directory.
109+
110+
## Branching Model
111+
112+
We follow a simple branching model:
113+
114+
- **main**: The stable branch containing the latest release.
115+
- **feature/your-feature-name**: Feature branches for new development.
116+
- **bugfix/your-bugfix-name**: Branches for bug fixes.
117+
118+
## License
119+
120+
By contributing to AshJ, you agree that your contributions will be licensed under the MIT License.

‎README.md

+157-5
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,161 @@
1-
# Ash-j Programming Language
1+
# ashj Programming Language
22

3-
**Ash-j** is a java implementation of the Ash programming language. jAsh is hugely influenced by **jlox**.
3+
Welcome to **ashj**, a lightweight, interpreted, object-oriented programming language. ashj is inspired
4+
by [Lox](http://www.craftinginterpreters.com/), a language developed in the book *Crafting Interpreters* by Robert
5+
Nystrom. ashj takes the core concepts of Lox and adds a unique twist, making it a powerful tool for developers
6+
interested in simplicity and expressiveness.
47

5-
## Difference from jlox
8+
## Table of Contents
69

7-
1. Added escape character support
10+
- [Introduction](#introduction)
11+
- [Getting Started](#getting-started)
12+
- [Features](#features)
13+
- [Installation](#installation)
14+
- [Usage](#usage)
15+
- [Examples](#examples)
16+
- [Contributing](#contributing)
17+
- [License](#license)
818

9-
_Thanks to Robert Nystorm and his amazing book Crafting interpreters for making this possible._
19+
## Introduction
20+
21+
ashj is a dynamic, interpreted programming language that supports object-oriented programming, functional programming
22+
paradigms, and more. It's designed to be simple and easy to learn, making it an excellent choice for beginners, as well
23+
as a convenient scripting language for experienced developers.
24+
25+
Inspired by Lox, ashj retains the elegance and minimalism of its predecessor while introducing improvements and
26+
enhancements tailored for modern development.
27+
28+
AshJ is implemented in **Java** and utilizes an **Abstract Syntax Tree (AST)** for interpreting code. This design makes
29+
it straightforward to extend and maintain. Additionally, a **C bytecode implementation** of AshJ, named **Ash**, is
30+
available [here](https://github.com/yahyafati/ash-lang), offering a more performance-oriented alternative.
31+
32+
## Getting Started
33+
34+
### Prerequisites
35+
36+
- **Java 8** or later installed on your machine.
37+
38+
### Installation
39+
40+
Download the latest version of ashj from the [releases page](https://github.com/yahyafati/ashj-lang/releases). Once
41+
downloaded, you can run the installer for your operating system:
42+
43+
- **Windows**: Run the `.exe` installer.
44+
- **macOS**: Run the `.pkg` installer.
45+
- **Linux**: Run the `.deb` or `.rpm` package installer.
46+
47+
### Running ashj
48+
49+
After installation, you can run ashj from the command line:
50+
51+
```bash
52+
ashj path/to/your/script.ashj
53+
```
54+
55+
Or start an interactive REPL session:
56+
57+
```bash
58+
ashj
59+
```
60+
61+
## Features
62+
63+
- **Object-Oriented**: Supports classes and inheritance, allowing for the creation of complex data structures.
64+
- **First-Class Functions**: Functions in ashj can be passed around as first-class citizens, allowing for higher-order
65+
functions and functional programming techniques.
66+
- **Dynamic Typing**: Variables in ashj are dynamically typed, making it flexible and easy to use.
67+
- **Garbage Collection**: Automatic memory management through garbage collection.
68+
- **Lexical Scoping**: Supports block-scoped variables.
69+
- **Lightweight**: Minimalist language design for quick execution and fast development cycles.
70+
71+
## Usage
72+
73+
### Basic Syntax
74+
75+
Here’s a quick overview of the syntax in ashj:
76+
77+
```java
78+
// Variables
79+
var name = "ashj";
80+
var age = 3 + 4;
81+
82+
// Functions
83+
fun greet() {
84+
print "Hello, " + name + "!";
85+
}
86+
87+
greet(); // Outputs: Hello, ashj!
88+
89+
// Classes
90+
class Animal {
91+
init(type) {
92+
this.type = type;
93+
}
94+
95+
speak() {
96+
print "This is a " + this.type;
97+
}
98+
}
99+
100+
var dog = Animal("Dog");
101+
dog.
102+
103+
speak(); // Outputs: This is a Dog
104+
```
105+
106+
### Control Structures
107+
108+
```java
109+
// If-Else Statements
110+
if(age >18){
111+
print "Adult";
112+
}else{
113+
print "Not an Adult";
114+
}
115+
116+
// While Loop
117+
var count = 0;
118+
while(count< 3){
119+
print count;
120+
count =count +1;
121+
}
122+
123+
// For Loop
124+
for(
125+
var i = 0;
126+
i< 5;i =i +1){
127+
print i;
128+
}
129+
```
130+
131+
## Examples
132+
133+
To see more examples, check out the `examples` directory in this repository. You can run these examples using the ashj
134+
interpreter:
135+
136+
```bash
137+
ashj examples/hello_world.ashj
138+
```
139+
140+
## Contributing
141+
142+
Contributions are welcome! If you have ideas for new features or have found bugs, please open an issue or submit a pull
143+
request. See the `CONTRIBUTING.md` file for more details.
144+
145+
## License
146+
147+
ashj is licensed under the MIT License. See the `LICENSE` file for more information.
148+
149+
Certainly! Here’s how you can include an **Acknowledgements** section in your `README.md` file:
150+
151+
---
152+
153+
## Acknowledgements
154+
155+
AshJ would not have been possible without the inspiration and guidance provided by Robert Nystrom's book, *Crafting
156+
Interpreters*. This book offers a comprehensive guide to building interpreters from scratch, and its implementation of
157+
Lox served as the foundation for AshJ.
158+
159+
A special thanks to Robert Nystrom for his incredible work in the programming community and for making *Crafting
160+
Interpreters* freely available to everyone. If you're interested in understanding the inner workings of interpreters, we
161+
highly recommend checking out his book at [craftinginterpreters.com](http://www.craftinginterpreters.com/).

‎src/main/java/com/yahya/interpreter/Ash.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ private static void runPrompt() throws IOException {
9393

9494
public static void main(String[] args) throws IOException {
9595
if (args.length > 1) {
96-
System.out.println("Usage: jlox [script]");
96+
System.out.println("Usage: ashj [script]");
9797
System.exit(64); // 64 is the exit code for command line usage error
9898
} else if (args.length == 1) {
9999
runFile(args[0]);

‎src/main/java/com/yahya/interpreter/ash/Scanner.java

+3-3
Original file line numberDiff line numberDiff line change
@@ -106,9 +106,9 @@ private void scanToken() {
106106
private void string() {
107107
while (peek() != '"' && !isAtEnd()) {
108108
if (peek() == '\n') line++; // so handles multi-line strings
109-
else if (peek() == '\\') {
110-
advance(); // escape the next character because of the escape character
111-
}
109+
// else if (peek() == '\\') {
110+
// advance(); // escape the next character because of the escape character
111+
// }
112112
advance();
113113
}
114114
if (isAtEnd()) {

‎test.ash

+3-15
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,4 @@
1-
class Animal {
1+
var s = "\This is so cool!
2+
";
23

3-
name() {
4-
return "Animal";
5-
}
6-
}
7-
8-
class Dog < Animal {
9-
10-
name() {
11-
return "Dog";
12-
}
13-
}
14-
15-
var dog = Dog();
16-
print dog.name();
4+
print s;

0 commit comments

Comments
 (0)