diff --git a/README.md b/README.md index a513f54..651b6dd 100644 --- a/README.md +++ b/README.md @@ -22,10 +22,11 @@ The host will provide all of the extensions needed on a case-by-case basis. Scri * [Quick Start Guide](quick-start-guide) * Tutorials - * ~~[Embedding Toy](embedding-toy)~~ + * [Embedding Toy](embedding-toy) * ~~[Standard Libary](standard-library)~~ * [Types](types) * [Developing Toy](developing-toy) +* ~~[Roadmap](roadmap)~~ # Version Differences diff --git a/embedding-toy.md b/embedding-toy.md new file mode 100644 index 0000000..7af528f --- /dev/null +++ b/embedding-toy.md @@ -0,0 +1,68 @@ +# Embedding Toy + +This tutorial assumes you're using git, GCC, and make. + +To embed toy into your program, simply clone the [git repository](https://github.com/Ratstail91/Toy) into a submodule - here we'll assume you called it `Toy`. + +Toy's makefile uses the variable `TOY_OUTDIR` to define where the output of the build command will place the result. You MUST set this to a value, relative to the Toy directory. + +```make +export LIBDIR = lib +export TOY_OUTDIR = ../$(LIBDIR) +``` + +Next, you'll want to run make the from within Toy's `source`, assuming the output directory has been created. There are two options for building Toy - `library` (default) or `static`; the former will create a shared library (and a .dll file on windows), while the latter will create a static library. + +```make +toy: $(LIBDIR) + $(MAKE) -C Toy/source + +$(LIBDIR): + mkdir $(LIBDIR) +``` + +Finally, link to the outputted library, and specify the source directory to access the header files. + +```make +all: $(OBJ) + $(CC) $(CFLAGS) -o $(OUT) $(OBJ) -L../$(LIBDIR) $(LIBS) +``` + +Here's a quick example makefile template you can use: + +```make +CC=gcc + +export OUTDIR = out +export LIBDIR = lib +export TOY_OUTDIR = ../$(LIBDIR) + +IDIR+=. ./Toy/source +CFLAGS+=$(addprefix -I,$(IDIR)) +LIBS+=-ltoy + +ODIR=obj +SRC=$(wildcard *.c) +OBJ=$(addprefix $(ODIR)/,$(SRC:.c=.o)) + +OUT=./$(OUTDIR)/program + +all: toy $(OUTDIR) $(ODIR) $(OBJ) + $(CC) $(CFLAGS) -o $(OUT) $(OBJ) -L$(LIBDIR) $(LIBS) + cp $(LIBDIR)/*.dll $(OUTDIR) # for shared libraries + +toy: $(LIBDIR) + $(MAKE) -C Toy/source + +$(OUTDIR): + mkdir $(OUTDIR) + +$(LIBDIR): + mkdir $(LIBDIR) + +$(ODIR): + mkdir $(ODIR) + +$(ODIR)/%.o: %.c + $(CC) -c -o $@ $< $(CFLAGS) +``` \ No newline at end of file diff --git a/quick-start-guide.md b/quick-start-guide.md index 3a37855..590804b 100644 --- a/quick-start-guide.md +++ b/quick-start-guide.md @@ -4,33 +4,6 @@ This guide is intended to get you writing Toy code as fast as possible. As such, Toy programs begin at the top of the file, and continue until the end, unless an error is encountered. -## Import and Export - -Although hello world should be first, lets instead have a look at how you interface with the host program. The interpreter has a set of variables referred to collectively as the "exports region" - these are intended for interfacing with the host. To access these from the scripts, use `import`, like so: - -``` -import variable; - -print variable; //prints whatever literal was given "variable" as the identifier -``` - -Alternatively, to add something to the exports region, use `export`: - -``` -var variable = 1; - -export variable; -``` - -In the event of naming conflicts, you can rename imported and exported variables using the `as` keyword: - -``` -//assume "table" exists in the export region -import table as newName; - -export newName as table2; -``` - ## Hello World This prints to the stdout, and has a newline appended to the end. This can be altered by the host program. @@ -41,7 +14,7 @@ print "Hello world"; ## Names and Variables -Variables can store data of any kind, unless a type is specified. See [types](types). Names can be up to 256 characters long. +Variables can store data of any kind, unless a type is specified; see [types](types). Names can be up to 256 characters long. ``` var b = true; @@ -146,6 +119,43 @@ print greeting[::-1]; //dlrow olleH greeting[0:4] = "Goodnight"; //changes greeting to equal "Goodnight world" ``` +## Import and Export + +The interpreter has a set of variables referred to collectively as the "exports region" - these are intended for interfacing with the host. To access these from the scripts, use `import`, like so: + +``` +import variable; + +print variable; //prints whatever literal was given "variable" as the identifier +``` + +Alternatively, to add something to the exports region, use `export`: + +``` +var variable = 1; + +export variable; +``` + +In the event of naming conflicts, you can rename imported and exported variables using the `as` keyword: + +``` +//assume "table" exists in the export region +import table as newName; + +export newName as table2; +``` + +## External Libraries + +The host may, at it's own discretion, make external libraries available to the scripts. To access these, you can use the `import` keyword once again: + +``` +import standard; + +print clock(); +``` + ## Assertion Tests For testing purposes, there is the `assert` keyword. `assert` takes two arguments, separated by a comma; if the first resolves to a truthy value, then the whole statement is a no-op. Otherwise, the second argument, which MUST be a string, is displayed as an error and the script exits. @@ -158,3 +168,4 @@ assert answer == 42, "This will not be seen"; //both false and null trigger assert's exit condition assert null, "This will be seen before the script exits"; ``` + diff --git a/types.md b/types.md index 563f45a..07d0472 100644 --- a/types.md +++ b/types.md @@ -16,7 +16,7 @@ The types available are: | float | float | Any floating point number. The limits are implementation dependent | | string | string | A series of characters, forming text | | array | n/a | A series of values arranged sequentially in memory, indexable with an integer | -| array | n/a | A series of key-value pairs stored in a hash-table, indexable with the keys | +| dictionary | n/a | A series of key-value pairs stored in a hash-table, indexable with the keys | | function | fn | A chunk of reusable code, which can potentially return a value of some kind | | type | type | The type of types | | any | any | Can hold any value |