DiamondNether90/ground_fork
1
0
Fork 0
forked from ground/ground
Code Pull Requests Activity

print, println, input, ground tutorial

Browse Source
This commit is contained in:
Maxwell
2025-09-20 12:08:20 +10:00
parent 2fd344af82
commit cc896629f7
3 changed files with 360 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/syntax.md
View File

@@ -84,23 +84,23 @@ Usage: `end $intvalue`
### I/O
#### stdin
#### input (or stdin)
Allows input from the console.
Usage: `stdin &var`
Usage: `input &var`
#### stdout
#### print (or stdout)
Allows output to the console.
Usage: `stdout $value`
Usage: `print $value`
#### stdlnout
#### println (or stdlnout)
Allows output to the console, appending a new line at the end.
Usage: `stdlnout $value`
Usage: `println $value`
### Variables and Lists
@@ -254,7 +254,7 @@ Some symbols specific to this category:
* `-type`: A type reference. Can be one of the following: "-string", "-char", "-int", "-double", "-bool"
#### fun
#### fun
Defines a function. All code between `fun` and `endfun` will be included in the function.
@@ -290,7 +290,7 @@ Usage: `call !function &var
#### use (Experimental, please report bugs!)
Attempts to import another Ground program. Gets inserted wherever the use statement is. Any code (including code outside function declarations) will be executed. All functions from the library will be given a prefix, meaning functions will be registered as `!libName:functionName`.
Attempts to import another Ground program. Gets inserted wherever the use statement is. Any code (including code outside function declarations) will be executed. All functions from the library will be given a prefix, meaning functions will be registered as `!libName:functionName`.
Note: Ground will check the directory where the program is being run from when trying to find imported programs. If that fails, it will check the directory set in the $GROUND_LIBS environment variable set by your system. The '.grnd' extension is appended automatically.

349
docs/tutorial.md Normal file
View File

@@ -0,0 +1,349 @@
# Ground Tutorial
Get up and running with Ground in no time!
## First Steps
First, create a file ending in `.grnd` and open it in your favourite text editor. Then, write the following:
```
println "Hello, World!"
```
(I think you know what this does.)
(If you don't, it prints something to the console, and adds a new line at the end.)
You can test it on the console using the Ground interpreter:
```bash
ground myFile.grnd
```
But that's boring! You want to be able to do more in Ground. So, let's ask the user for something. We can write:
```
input &var
println $var
```
This will wait for the user to type something into the console and press enter, and will save it to the variable `var`. Then, we print out the variable `var`.
But how do variables work in Ground?
## Variables
In Ground, variables are used to store values. (Yeah, I know, very original.) However, variables work a bit differently. What you need to know right now are called "value references" and "direct references".
### Value References
A value reference gets the value of a variable, and inserts it into the statement currently being executed.
For example, let's assume I have a variable called `myVar`, and it has the value `"Hello from the variable!"`. If you want to access that value, you use a value reference. To use a value reference, write the variable name, but prefixed with the `$` sign.
Let's try printing out `myVar`:
```
println $myVar
```
Sidenote: Value references are inserted before each line of code is ran.
You should see "Hello from the variable!" on the console, assuming you defined `myVar` beforehand. But how do you define a variable?
### Direct References
Direct references allow you to write to a variable. To use one, prefix your desired variable name with an `&` symbol.
Ground works differently to many programming languages in that you can't write things like `myVar = 10`. Everything uses an instruction (which I'll explain in a moment). So in Ground, you'd write:
```
set &myVar 10
```
to set `myVar` to 10. Simple, right?
### Summary
* Value references let you get the variable of a value, and are prefixed with `$`.
* Direct references let you write to variables, and are prefixed with `&`.
As an example:
```
set &myVar "Hello from the variable!"
println $myVar
```
will set `myVar` to "Hello from the variable!", and print it to the console.
## Instructions
Now, I assume you want to do more than setting variables and printing them, right? Luckily for you, Ground has (at the time of writing) 35 instructions to build whatever you can think of (not to mention libraries, but that's a later topic).
First, here's how you use them:
### Using instructions
Each line of Ground code contains an instruction and arguments. For example:
```
add 9 10 &result
```
This uses the `add` keyword (which adds two things together) to add 9 and 10, and outputs the result (which would be 19) to the direct reference provided (`result`).
So each instruction works sort of like a function in most other languages.
Now you know how they work, here's a list of cool instructions:
### Cool instructions
So here's a list of some instructions keywords to know about at present:
### Mathy stuff
`add`, `subtract`, `multiply`, `divide`
These instructions all take two numbers, and operate on them (add adds, subtract subtracts, and so on), and then output the result to the provided direct reference. You can use them all like:
```
add 5 6 &addition
```
```
multiply 10 30 &myVar
```
(and so on.)
Tip: `add` works on strings for concatenation! (for those who don't know, a string is a series of characters surrounded with `"`'s)
### User interaction
`input` (or `stdin`)
This instruction takes input from the console, and saves it to the given direct reference. For example:
```
input &myVar
```
`print` (or `stdout`) and `println` (or `stdlnout`)
These instructions print out values to the console. `println` also prints a new line character after your statement. For example:
```
println "Hi there! This has a new line at the end"
print "Heyo! This doesn't have a new line at the end."
```
### Other variable stuff
`set`
Sets a variable to something.
For example:
```
set &myVar "Hi there!"
```
`gettype`
Gets the type of a variable, in the form of a string. As an example:
```
gettype $someSortOfValue &type
```
If you accessed `$type`, you'd get one of the following:
"int", "double", "bool", "string", "char".
More on types later!
## Commenting
Comments are done with a `#`. Anything after the `#` on the line is ignored.
## Control Flow
Now, I assume you want to be able to use logic in your programs, right? Ground simplifies control flow to the bare minimum.
### Labels
A label is a point in your Ground code you can jump to. To set one, instead of writing an instruction, you can do something like this:
```
@myLabel
```
This will allow you to jump back to that point in code at any time.
### Jumping around
Jump to labels with the `jump` instruction.
```
# Infinite loop!
@myLabel
jump %myLabel
```
But what does `%myLabel` mean? This is the third reference type: a line reference. It tells Ground which line to look at.
You can also use `if`, however `if` works differently:
```
@myLabel
if $myCondition %myLabel
```
This essentialy says "if `myCondition` is true, then jump to `myLabel`". But how do you compute conditions?
### More instructions!
Here are some useful instructions to compute a condition:
`equal`, `inequal`
These compare two values, and puts a boolean in a variable once they're compared.
Example:
```
# Prints out true
equal "Hello!" "Hello!" &condition
println $condition
# Prints out false
equal 10 20 &condition
println $condition
# Prints out true
inequal "Hi there!" "Hello there!" &condition
println $condition
```
`equal` and `inequal` work on most regular values.
`greater`, `lesser`
These instructions check if the first provided value is greater or lesser than the second provided value. As an example:
```
# Prints out true
greater 10 5 &condition
println $condition
```
### So how do I use these?
Labels, `if`, and `jump` can be used to create what would be if and while statements in other languages. Here's a loop that counts to 10:
```
set &counter 0
@loopStart
# Add one to our counter and print it out
add $counter 1 &counter
println $counter
# Check if we've hit 10 yet
equal $counter 10 &condition
# If we have, go to the end of the loop
if $condition %loopEnd
# Otherwise, go back to the start
jump %loopStart
@loopEnd
```
And here's a conditional if statement that checks if a user guessed the right password:
```
# Ask the user what the password is
print "Password: "
input &password
# Check if they got it right
equal $password "supersecurepassword" &condition
if $condition %rightPassword
jump %wrongPassword
@rightPassword
println "Correct!"
jump %end
@wrongPassword
println "Incorrect!"
jump %end
@end
```
## Building a meaningful program
Now we have all the building blocks to create a simple program!
Let's write a program that loops until the user tells us the right answer to a question. Here's how we do it:
First let's create a label so we can loop back to the start of our program:
```
@begin
```
Then we ask the user for their answer:
```
print "Do you like cheese?"
input &userInput
```
After this, we can check for the desired answer:
```
equal $userInput "yes" &condition
if $condition %success
```
Now, if the user answers "yes" to our question, they will be sent to the `%success` label. But we need to handle what happens if they don't say what we want them to.
So we can tell them that they said the wrong thing, and jump back to the start of the program.
```
println "That's a pity"
jump %begin
```
At last, we should handle what happens when we get the input we want:
```
@success
println "Yay!"
```
Try running that program!
Here's the full text of what we wrote:
```
@begin
print "Do you like cheese?"
input &userInput
equal $userInput "yes" &condition
if $condition %success
println "That's a pity"
jump %begin
@success
println "Yay!"
```
## Next Steps
Now you've completed the basic tutorial! This will probably be expanded in future, but for now you can look at [the syntax guide](https://chookspace.com/ground/ground/src/branch/master/docs/syntax.md) for more features to use.

3
src/main.cpp
View File

@@ -2338,8 +2338,11 @@ vector<Instruction> parser(vector<vector<string>> in) {
newInst.args.push_back(newFnRef);
}
else if (i == "stdin") newInst.inst = Instructions::Stdin;
else if (i == "input") newInst.inst = Instructions::Stdin;
else if (i == "stdout") newInst.inst = Instructions::Stdout;
else if (i == "print") newInst.inst = Instructions::Stdout;
else if (i == "stdlnout") newInst.inst = Instructions::Stdlnout;
else if (i == "println") newInst.inst = Instructions::Stdlnout;
else if (i == "error") newInst.inst = Instructions::Error;
else if (i == "try") newInst.inst = Instructions::Try;
else if (i == "catch") newInst.inst = Instructions::Catch;