mirrors/janet
1
0
Fork 0
mirror of https://github.com/janet-lang/janet synced 2024-12-28 09:20:26 +00:00
Code Issues 1 Releases Wiki Activity

Change name to janet.

Calvin Rose 2018-09-05 22:22:39 -04:00
parent 749a642427
commit 9f45345eaa
1 changed files with 25 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Introduction.md

@ -1,36 +1,36 @@
# Hello, world! # Hello, world!
Following tradition, a simple Dst program will print "Hello, world!". Following tradition, a simple Janet program will print "Hello, world!".
``` ```
(print "Hello, world!") (print "Hello, world!")
``` ```
Put the following code in a file named `hello.dst`, and run `./dst hello.dst`. Put the following code in a file named `hello.janet`, and run `./janet hello.janet`.
The words "Hello, world!" should be printed to the console, and then the program The words "Hello, world!" should be printed to the console, and then the program
should immediately exit. You now have a working dst program! should immediately exit. You now have a working janet program!
Alternatively, run the program `./dst` without any arguments to enter a REPL, Alternatively, run the program `./janet` without any arguments to enter a REPL,
or read eval print loop. This is a mode where Dst functions like a calculator, or read eval print loop. This is a mode where Janet functions like a calculator,
reading some input from the user, evaluating it, and printing out the result, all reading some input from the user, evaluating it, and printing out the result, all
in an inifinte loop. This is a useful mode for exploring or prototyping in Dst. in an inifinte loop. This is a useful mode for exploring or prototyping in Janet.
This hello world program is about the simplest program one can write, and consists of only This hello world program is about the simplest program one can write, and consists of only
a few pieces of syntax. This first element is the `print` symbol. This is a function a few pieces of syntax. This first element is the `print` symbol. This is a function
that simply prints its arguments to the console. The second argument is the that simply prints its arguments to the console. The second argument is the
string literal "Hello, world!", which is the one and only argument to the string literal "Hello, world!", which is the one and only argument to the
print function. Lastly, the print symbol and the string literal are wrapped print function. Lastly, the print symbol and the string literal are wrapped
in parentheses, forming a tuple. In Dst, parentheses and brackets are interchangeable, in parentheses, forming a tuple. In Janet, parentheses and brackets are interchangeable,
brackets are used mostly when the resulting tuple is not a function call. The tuple brackets are used mostly when the resulting tuple is not a function call. The tuple
above indicates that the function `print` is to be called with one argument, `"Hello, world"`. above indicates that the function `print` is to be called with one argument, `"Hello, world"`.
Like all lisps, all operations in Dst are in prefix notation; the name of the Like all lisps, all operations in Janet are in prefix notation; the name of the
operator is the first value in the tuple, and the arguments passed to it are operator is the first value in the tuple, and the arguments passed to it are
in the rest of the tuple. in the rest of the tuple.
# A bit more - Arithmetic # A bit more - Arithmetic
Any programming language will have some way to do arithmetic. Dst is no exception, Any programming language will have some way to do arithmetic. Janet is no exception,
and supports the basic arithemtic operators and supports the basic arithemtic operators
``` ```
@ -40,11 +40,11 @@ and supports the basic arithemtic operators
``` ```
Just like the print function, all arithmetic operators are entered in Just like the print function, all arithmetic operators are entered in
prefix notation. Dst also supports the remainder operator, or `%`, which returns prefix notation. Janet also supports the remainder operator, or `%`, which returns
the remainder of division. For example, `(% 10 3)` is 1, and `(% 10.5 3)` is the remainder of division. For example, `(% 10 3)` is 1, and `(% 10.5 3)` is
1.5. The lines that begin with `#` are comments. 1.5. The lines that begin with `#` are comments.
Dst actually has two "flavors" of numbers; integers and real numbers. Integers are any Janet actually has two "flavors" of numbers; integers and real numbers. Integers are any
integer value between -2,147,483,648 and 2,147,483,647 (32 bit signed integer). integer value between -2,147,483,648 and 2,147,483,647 (32 bit signed integer).
Reals are real numbers, and are represented by IEEE-754 double precision floating point Reals are real numbers, and are represented by IEEE-754 double precision floating point
numbers. That means that they can represent any number an integer can represent, as well numbers. That means that they can represent any number an integer can represent, as well
@ -72,7 +72,7 @@ notation with a radix besides 10, use the `&` symbol to indicate the exponent ra
## Arithmetic Functions ## Arithmetic Functions
Besides the 5 main arithmetic functions, dst also supports a number of math functions Besides the 5 main arithmetic functions, janet also supports a number of math functions
taken from the C libary `<math.h>`, as well as bitwise operators that behave like they taken from the C libary `<math.h>`, as well as bitwise operators that behave like they
do in C or Java. Functions like `math.sin`, `math.cos`, `math.log`, and `math.exp` will do in C or Java. Functions like `math.sin`, `math.cos`, `math.log`, and `math.exp` will
behave as expected to a C programmer. They all take either 1 or 2 numeric arguments and behave as expected to a C programmer. They all take either 1 or 2 numeric arguments and
@ -80,7 +80,7 @@ return a real number (never an integer!)
# Strings, Keywords and Symbols # Strings, Keywords and Symbols
Dst supports several varieties of types that can be used as labels for things in Janet supports several varieties of types that can be used as labels for things in
your program. The most useful type for this purpose is the keyword type. A keyword your program. The most useful type for this purpose is the keyword type. A keyword
begins with a semicolon, and then contains 0 or more alphanumeric or a few other common begins with a semicolon, and then contains 0 or more alphanumeric or a few other common
characters. For example, `:hello`, `:my-name`, `:=`, and `:ABC123_-*&^%$` are all keywords. characters. For example, `:hello`, `:my-name`, `:=`, and `:ABC123_-*&^%$` are all keywords.
@ -114,7 +114,7 @@ code easier to reason about, it allows for many optimizations involving these ty
# Prints true # Prints true
(= :hello :hello) (= :hello :hello)
# Prints false, everything in dst is case sensitive # Prints false, everything in janet is case sensitive
(= :hello :HeLlO) (= :hello :HeLlO)
# Look up into a table - evaluates to 25 # Look up into a table - evaluates to 25
@ -126,10 +126,10 @@ code easier to reason about, it allows for many optimizations involving these ty
``` ```
Strings can be used similarly to keywords, but there primary usage is for defining either text Strings can be used similarly to keywords, but there primary usage is for defining either text
or arbitrary sequences of bytes. Strings (and symbols) in dst are what is sometimes known as or arbitrary sequences of bytes. Strings (and symbols) in janet are what is sometimes known as
"8-bit clean"; they can hold any number of bytes, and are completely unaware of things like character "8-bit clean"; they can hold any number of bytes, and are completely unaware of things like character
encodings. This is completely compatible with ASCII and UTF-8, two of the most common character encodings. This is completely compatible with ASCII and UTF-8, two of the most common character
encodings. By being encoding agnostic, dst strings can be very simple, fast, and useful for encodings. By being encoding agnostic, janet strings can be very simple, fast, and useful for
for other uses besides holding text. for other uses besides holding text.
Literal text can be entered inside quotes, as we have seen above. Literal text can be entered inside quotes, as we have seen above.
@ -153,8 +153,8 @@ Line 2
# Functions # Functions
Dst is a functional language - that means that one of the basic building blocks of your Janet is a functional language - that means that one of the basic building blocks of your
program will be defining functions (the other is using data structures). Because dst program will be defining functions (the other is using data structures). Because janet
is a Lisp, functions are values just like numbers or strings - they can be passed around and is a Lisp, functions are values just like numbers or strings - they can be passed around and
created as needed. created as needed.
@ -217,7 +217,7 @@ the corresponding
(myfun 3 4) # -> 10 (myfun 3 4) # -> 10
``` ```
Dst has many macros provided for you (and you can write your own). Janet has many macros provided for you (and you can write your own).
Macros are just functions that take your source code Macros are just functions that take your source code
and transform it into some other source code, usually automating some repetitive pattern for you. and transform it into some other source code, usually automating some repetitive pattern for you.
@ -259,7 +259,7 @@ a function by passing a string the def or var command.
Defs and vars (collectively known as bindings) live inside what is called a scope. A scope is Defs and vars (collectively known as bindings) live inside what is called a scope. A scope is
simply where the bindings are valid. If a binding is referenced outside of its scope, the compiler simply where the bindings are valid. If a binding is referenced outside of its scope, the compiler
will throw an error. Scopes are useful for organizing your bindings and my extension your programs. will throw an error. Scopes are useful for organizing your bindings and my extension your programs.
There are two main ways to create a scope in Dst. There are two main ways to create a scope in Janet.
The first is to use the `do` special form. `do` executes a series of statements in a scope The first is to use the `do` special form. `do` executes a series of statements in a scope
and evaluates to the last statement. Bindings create inside the form do not escape outside and evaluates to the last statement. Bindings create inside the form do not escape outside
@ -305,7 +305,7 @@ but using do with multiple defs is fine as well.
# Data Structures # Data Structures
Once you have a handle on functions and the primitive value types, you may be wondering how Once you have a handle on functions and the primitive value types, you may be wondering how
to work with collections of things. Dst has a small number of core data structure types to work with collections of things. Janet has a small number of core data structure types
that are very versatile. Tables, Structs, Arrays, Tuples, Strings, and Buffers, are the 6 main that are very versatile. Tables, Structs, Arrays, Tuples, Strings, and Buffers, are the 6 main
built in data structure types. These data structures can be arranged in a useful table describing built in data structure types. These data structures can be arranged in a useful table describing
there relationship to each other. there relationship to each other.
@ -365,7 +365,7 @@ itself, and the second parameter is the key.
(get "hello, world" 0) # -> 104 (get "hello, world" 0) # -> 104
``` ```
In many cases, however, you do not need the `get` function at all. Dst supports destructuring, which In many cases, however, you do not need the `get` function at all. Janet supports destructuring, which
means both the `def` and `var` special forms can extract values from inside structures themselves. means both the `def` and `var` special forms can extract values from inside structures themselves.
```lisp ```lisp
@ -403,7 +403,7 @@ values in a data structure (the number of keys in a dictionary type).
# Flow Control # Flow Control
Dst has only two built in primitives to change program while inside a function. The first if the Janet has only two built in primitives to change program while inside a function. The first if the
`if` special form, which behaves as expected in most functional languages. It takes two or three parameters: `if` special form, which behaves as expected in most functional languages. It takes two or three parameters:
a condition, an expression to evaluate to if the condition is true (not nil or false), a condition, an expression to evaluate to if the condition is true (not nil or false),
and an optional condition to evaluate to when the condition is nil or false. If the optional parameter and an optional condition to evaluate to when the condition is nil or false. If the optional parameter
@ -441,7 +441,7 @@ of the loop.
(print "...")) (print "..."))
``` ```
Besides these special forms, Dst has many macros for both conditional testing and looping Besides these special forms, Janet has many macros for both conditional testing and looping
that are much better for the majority of cases. For conditional testing, the `cond`, `switch`, and that are much better for the majority of cases. For conditional testing, the `cond`, `switch`, and
`when` macros can be used to great effect. `cond` can be used for making an if-else chain, where using `when` macros can be used to great effect. `cond` can be used for making an if-else chain, where using
just raw if forms would result in many parentheses. `switch` For looping, the `loop` and `for` macro implement just raw if forms would result in many parentheses. `switch` For looping, the `loop` and `for` macro implement
@ -457,7 +457,7 @@ list comprehension, as in Python, Clojure.
# The Core Library # The Core Library
Dst has a built in core library of over 200 functions and macros at the time of writing. Janet has a built in core library of over 200 functions and macros at the time of writing.
While some of these functions may be refactored into separate modules, it is useful to get to know While some of these functions may be refactored into separate modules, it is useful to get to know
the core to avoid rewriting provided functions. the core to avoid rewriting provided functions.