diff --git a/Introduction.md b/Introduction.md index 7c400c9..440fe48 100644 --- a/Introduction.md +++ b/Introduction.md @@ -1,36 +1,36 @@ # 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!") ``` -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 -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, -or read eval print loop. This is a mode where Dst functions like a calculator, +Alternatively, run the program `./janet` without any arguments to enter a REPL, +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 -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 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 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 -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 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 in the rest of the tuple. # 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 ``` @@ -40,11 +40,11 @@ and supports the basic arithemtic operators ``` 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 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). 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 @@ -72,7 +72,7 @@ notation with a radix besides 10, use the `&` symbol to indicate the exponent ra ## 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 ``, 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 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 -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 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. @@ -114,7 +114,7 @@ code easier to reason about, it allows for many optimizations involving these ty # Prints true (= :hello :hello) -# Prints false, everything in dst is case sensitive +# Prints false, everything in janet is case sensitive (= :hello :HeLlO) # 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 -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 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. Literal text can be entered inside quotes, as we have seen above. @@ -153,8 +153,8 @@ Line 2 # Functions -Dst 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 +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 janet is a Lisp, functions are values just like numbers or strings - they can be passed around and created as needed. @@ -217,7 +217,7 @@ the corresponding (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 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 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. -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 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 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 built in data structure types. These data structures can be arranged in a useful table describing there relationship to each other. @@ -365,7 +365,7 @@ itself, and the second parameter is the key. (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. ```lisp @@ -403,7 +403,7 @@ values in a data structure (the number of keys in a dictionary type). # 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: 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 @@ -441,7 +441,7 @@ of the loop. (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 `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 @@ -457,7 +457,7 @@ list comprehension, as in Python, Clojure. # 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 the core to avoid rewriting provided functions.