From a16e6bd22a4c238765bcf692ddfd3f86c39c4612 Mon Sep 17 00:00:00 2001 From: Dominik Picheta Date: Thu, 6 Dec 2012 19:46:24 +0000 Subject: Updated readme. --- readme.txt | 82 ++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 21 deletions(-) (limited to 'readme.txt') diff --git a/readme.txt b/readme.txt index c4d3b2ba7..1391c530a 100755 --- a/readme.txt +++ b/readme.txt @@ -1,21 +1,61 @@ -=========================================================== - Nimrod Compiler -=========================================================== - -This is the **Nimrod Compiler**. Nimrod is a new statically typed, imperative -programming language, that supports procedural, functional, object oriented and -generic programming styles while remaining simple and efficient. A special -feature that Nimrod inherited from Lisp is that Nimrod's abstract syntax tree -(AST) is part of the specification - this allows a powerful macro system which -can be used to create domain specific languages. - -*Nimrod* is a compiled, garbage-collected systems programming language -which has an excellent productivity/performance ratio. Nimrod's design -focuses on efficiency, expressiveness, elegance (in the order of -priority). - -See the file ``install.txt`` for installation instructions. See the file -``doc/intern.txt`` for the internal documentation for developers. - -Copyright (c) 2004-2012 Andreas Rumpf. -All rights reserved. +# Nimrod Compiler +This repo contains the Nimrod compiler, Nimrod's stdlib, tools and documentation. + +## Compiling +Compiling the Nimrod compiler is quite straightforward. Because +the Nimrod compiler itself is written in the Nimrod programming language +the C source of an older version of the compiler are needed to bootstrap the +latest version. The C sources are however included with this repository under +the build directory. + +Pre-compiled snapshots of the compiler are also available on +[Nimbuild](http://build.nimrod-code.org/). Your platform however may not currently +be built for. + +The compiler currently supports the following platform and architecture combinations: + + * Windows (Windows XP or greater) - x86 and x86_64 + * Linux (most, if not all, distributions) - x86, x86_64, ppc64 and armv6l + * Mac OS X 10.04 or higher - x86, x86_64 and ppc64 + +In reality a lot more are supported, however they are not tested regularly. + +To build from source you will need: + + * gcc 3.x or later recommended. Other alternatives which may work + are: clang, Visual C++, Intel's C++ compiler + * unzip + * git or wget + +If you are on a fairly modern *nix system, the following steps should work: + +``` +$ git clone git://github.com/Araq/Nimrod.git +$ cd Nimrod +$ unzip build/csources.zip +$ ./build.sh +$ bin/nimrod c koch +$ ./koch boot -d:release +``` + +The install script (``install.sh``) may then be used to install Nimrod, or you +can simply add it to your PATH. + +The above steps can be performed on Windows in a similar fashion, the +``build.bat`` and ``build64.bat`` (for x86_64 systems) are provided to be used +instead of ``build.sh``. + +## Getting help +A [forum](http://forum.nimrod-code.org/) is available if you have any questions, +and you can also get help in the IRC channel on [Freenode](irc://irc.freenode.net/nimrod) in #nimrod. + +## License +The compiler is licensed under the GPLv2 license, the standard library is +licensed under the LGPL license with a linking exception so that you can link +to it statically. This means that you can use any license for your own programs +developed with Nimrod, allowing you to create commercial applications. + +Read copying.txt for more details. + +Copyright (c) 2004-2012 Andreas Rumpf. +All rights reserved. \ No newline at end of file -- cgit 1.4.1-2-gfad0 From 40b611cc2f7d5cf4972dfb92fc63f0bb350adf89 Mon Sep 17 00:00:00 2001 From: Araq Date: Fri, 7 Dec 2012 17:43:15 +0100 Subject: documentation improvements --- doc/manual.txt | 296 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- readme.md | 13 ++- readme.txt | 13 ++- todo.txt | 4 +- 4 files changed, 309 insertions(+), 17 deletions(-) (limited to 'readme.txt') diff --git a/doc/manual.txt b/doc/manual.txt index 5ea3575ee..4d0c3b01b 100755 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -593,7 +593,7 @@ widening type conversion are *implicit*: myInt16 + myInt # of type ``int`` myInt16 + 2i32 # of type ``int32`` -However, ``int`` literals are implicitely convertible to a smaller integer type +However, ``int`` literals are implicitly convertible to a smaller integer type if the literal's value fits this smaller type and such a conversion is less expensive than other implicit conversions, so ``myInt16 + 34`` produces an ``int16`` result. @@ -1847,7 +1847,7 @@ Syntax:: staticStmt ::= 'static' ':' stmt A `static`:idx: statement/expression can be used to enforce compile -time evaluation explicitely. Enforced compile time evaluation can even evaluate +time evaluation explicitly. Enforced compile time evaluation can even evaluate code that has side effects: .. code-block:: @@ -2479,7 +2479,7 @@ returned value is an l-value and can be modified by the caller: WriteAccessToG() = 6 assert g == 6 -It is a compile time error if the implicitely introduced pointer could be +It is a compile time error if the implicitly introduced pointer could be used to access a location beyond its lifetime: .. code-block:: nimrod @@ -3398,7 +3398,7 @@ template cannot be accessed in the instantiation context: template newException*(exceptn: typeDesc, message: string): expr = var - e: ref exceptn # e is implicitely gensym'ed here + e: ref exceptn # e is implicitly gensym'ed here new(e) e.msg = message e @@ -3699,8 +3699,294 @@ types that will match the typedesc param: The constraint can be a concrete type or a type class. +Term rewriting macros +===================== + +`Term rewriting macros`:idx: are macros or templates that have not only +a *name* but also a *pattern* that is searched for after the semantic checking +phase of the compiler: This means they provide an easy way to enhance the +compilation pipeline with user defined optimizations: + +.. code-block:: nimrod + template optMul{`*`(a, 2)}(a: int): int = a+a + + let x = 3 + echo x * 2 + +The compiler now rewrites ``x * 2`` as ``x + x``. The code inside the +curlies is the pattern to match against. The operators ``*``, ``**``, +``|``, ``~`` have a special meaning in patterns if they are written in infix +notation, so to match verbatim against ``*`` the ordinary function call syntax +needs to be used. + + +Unfortunately optimizations are hard to get right and even the tiny example +is **wrong**: + +.. code-block:: nimrod + template optMul{`*`(a, 2)}(a: int): int = a+a + + proc f(): int = + echo "side effect!" + result = 55 + + echo f() * 2 + +We cannot duplicate 'a' if it denotes an expression that has a side effect! +Fortunately Nimrod supports side effect analysis: + +.. code-block:: nimrod + template optMul{`*`(a, 2)}(a: int{noSideEffect}): int = a+a + + proc f(): int = + echo "side effect!" + result = 55 + + echo f() * 2 # not optimized ;-) + +So what about ``2 * a``? We should tell the compiler ``*`` is commutative. We +cannot really do that however as the following code only swaps arguments +blindly: + +.. code-block:: nimrod + template mulIsCommutative{`*`(a, b)}(a, b: int): int = b*a + +What optimizers really need to do is a *canonicalization*: + +.. code-block:: nimrod + template canonMul{`*`(a, b)}(a: int{lit}, b: int): int = b*a + +The ``int{lit}`` parameter pattern matches against an expression of +type ``int``, but only if it's a literal. + + + +Parameter constraints +--------------------- + +The `parameter constraint`:idx: expression can use the operators ``|`` (or), +``&`` (and) and ``~`` (not) and the following predicates: + +=================== ===================================================== +Predicate Meaning +=================== ===================================================== +``atom`` The matching node has no children. +``lit`` The matching node is a literal like "abc", 12. +``sym`` The matching node must be a symbol (a bound + identifier). +``ident`` The matching node must be an identifier (an unbound + identifier). +``call`` The matching AST must be a call/apply expression. +``lvalue`` The matching AST must be an lvalue. +``sideeffect`` The matching AST must have a side effect. +``nosideeffect`` The matching AST must have no side effect. +``param`` A symbol which is a parameter. +``genericparam`` A symbol which is a generic parameter. +``module`` A symbol which is a module. +``type`` A symbol which is a type. +``var`` A symbol which is a variable. +``let`` A symbol which is a ``let`` variable. +``const`` A symbol which is a constant. +``result`` The special ``result`` variable. +``proc`` A symbol which is a proc. +``method`` A symbol which is a method. +``iterator`` A symbol which is an iterator. +``converter`` A symbol which is a converter. +``macro`` A symbol which is a macro. +``template`` A symbol which is a template. +``field`` A symbol which is a field in a tuple or an object. +``enumfield`` A symbol which is a field in an enumeration. +``forvar`` A for loop variable. +``label`` A label (used in ``block`` statements). +``nk*`` The matching AST must have the specified kind. + (Example: ``nkIfStmt`` denotes an ``if`` statement.) +``alias`` States that the marked parameter needs to alias + with *some* other parameter. +``noalias`` States that *every* other parameter must not alias + with the marked parameter. +=================== ===================================================== + +The ``alias`` and ``noalias`` predicates refer not only to the matching AST, +but also to every other bound parameter; syntactially they need to occur after +the ordinary AST predicates: + +.. code-block:: nimrod + template ex{a = b + c}(a: int{noalias}, b, c: int) = + # this transformation is only valid if 'b' and 'c' do not alias 'a': + a = b + inc a, b + + +Pattern operators +----------------- + +The operators ``*``, ``**``, ``|``, ``~`` have a special meaning in patterns +if they are written in infix notation. + + +The ``|`` operator +~~~~~~~~~~~~~~~~~~ + +The ``|`` operator if used as infix operator creates an ordered choice: + +.. code-block:: nimrod + template t{0|1}(): expr = 3 + let a = 1 + # outputs 3: + echo a + +The matching is performed after the compiler performed some optimizations like +constant folding, so the following does not work: + +.. code-block:: nimrod + template t{0|1}(): expr = 3 + # outputs 1: + echo 1 + +The reason is that the compiler already transformed the 1 into "1" for +the ``echo`` statement. However, a term rewriting macro should not change the +semantics anyway. In fact they can be deactived with the ``--patterns:off`` +command line option or temporarily with the ``patterns`` pragma. + + +The ``{}`` operator +~~~~~~~~~~~~~~~~~~~ + +A pattern expression can be bound to a pattern parameter via the ``expr{param}`` +notation: + +.. code-block:: nimrod + template t{(0|1|2){x}}(x: expr): expr = x+1 + let a = 1 + # outputs 2: + echo a + + +The ``~`` operator +~~~~~~~~~~~~~~~~~~ + +The ``~`` operator is the **not** operator in patterns: + +.. code-block:: nimrod + template t{x = (~x){y} and (~x){z}}(x, y, z: bool): stmt = + x = y + if x: x = z + + var + a = false + b = true + c = false + a = b and c + echo a + + +The ``*`` operator +~~~~~~~~~~~~~~~~~~ + +The ``*`` operator can *flatten* a nested binary expression like ``a & b & c`` +to ``&(a, b, c)``: + +.. code-block:: nimrod + var + calls = 0 + + proc `&&`(s: varargs[string]): string = + result = s[0] + for i in 1..len(s)-1: result.add s[i] + inc calls + + template optConc{ `&&` * a }(a: string): expr = &&a + + let space = " " + echo "my" && (space & "awe" && "some " ) && "concat" + + # check that it's been optimized properly: + doAssert calls == 1 + + +The second operator of `*` must be a parameter; it is used to gather all the +arguments. The expression ``"my" && (space & "awe" && "some " ) && "concat"`` +is passed to ``optConc`` in ``a`` as a special list (of kind ``nkArgList``) +which is flattened into a call expression; thus the invocation of ``optConc`` +produces: + +.. code-block:: nimrod + `&&`("my", space & "awe", "some ", "concat") + + +The ``**`` operator +~~~~~~~~~~~~~~~~~~~ + +The ``**`` is much like the ``*`` operator, except that it gathers not only +all the arguments, but also the matched operators in reverse polish notation: + +.. code-block:: nimrod + import macros + + type + TMatrix = object + dummy: int + + proc `*`(a, b: TMatrix): TMatrix = nil + proc `+`(a, b: TMatrix): TMatrix = nil + proc `-`(a, b: TMatrix): TMatrix = nil + proc `$`(a: TMatrix): string = result = $a.dummy + proc mat21(): TMatrix = + result.dummy = 21 + + macro optM{ (`+`|`-`|`*`) ** a }(a: TMatrix): expr = + echo treeRepr(a) + result = newCall(bindSym"mat21") + + var x, y, z: TMatrix + + echo x + y * z - x + +This passes the expression ``x + y * z - x`` to the ``optM`` macro as +an ``nnkArgList`` node containing:: + + Arglist + Sym "x" + Sym "y" + Sym "z" + Sym "*" + Sym "+" + Sym "x" + Sym "-" + +(Which is the reverse polish notation of ``x + y * z - x``.) + + +Parameters +---------- + +Parameters in a pattern are type checked in the matching process. If a +parameter is of the type ``varargs`` it is treated specially and it can match +0 or more arguments in the AST to be matched against: + +.. code-block:: nimrod + template optWrite{ + write(f, x) + ((write|writeln){w})(f, y) + }(x, y: varargs[expr], f: TFile, w: expr) = + w(f, x, y) + + + +AST based overloading +===================== + +Parameter constraints can also be used for ordinary routine parameters; these +constraints affect ordinary overloading resolution then: + + + +However, the constraints ``alias`` and ``noalias`` are not available in +ordinary routines. + + Modules -------- +======= Nimrod supports splitting a program into pieces by a `module`:idx: concept. Each module needs to be in its own file and has its own `namespace`:idx:. Modules enable `information hiding`:idx: and `separate compilation`:idx:. diff --git a/readme.md b/readme.md index 1391c530a..fe4542b56 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,6 @@ # Nimrod Compiler -This repo contains the Nimrod compiler, Nimrod's stdlib, tools and documentation. +This repo contains the Nimrod compiler, Nimrod's stdlib, tools and +documentation. ## Compiling Compiling the Nimrod compiler is quite straightforward. Because @@ -9,10 +10,11 @@ latest version. The C sources are however included with this repository under the build directory. Pre-compiled snapshots of the compiler are also available on -[Nimbuild](http://build.nimrod-code.org/). Your platform however may not currently -be built for. +[Nimbuild](http://build.nimrod-code.org/). Your platform however may not +currently be built for. -The compiler currently supports the following platform and architecture combinations: +The compiler currently supports the following platform and architecture +combinations: * Windows (Windows XP or greater) - x86 and x86_64 * Linux (most, if not all, distributions) - x86, x86_64, ppc64 and armv6l @@ -47,7 +49,8 @@ instead of ``build.sh``. ## Getting help A [forum](http://forum.nimrod-code.org/) is available if you have any questions, -and you can also get help in the IRC channel on [Freenode](irc://irc.freenode.net/nimrod) in #nimrod. +and you can also get help in the IRC channel +on [Freenode](irc://irc.freenode.net/nimrod) in #nimrod. ## License The compiler is licensed under the GPLv2 license, the standard library is diff --git a/readme.txt b/readme.txt index 1391c530a..fe4542b56 100755 --- a/readme.txt +++ b/readme.txt @@ -1,5 +1,6 @@ # Nimrod Compiler -This repo contains the Nimrod compiler, Nimrod's stdlib, tools and documentation. +This repo contains the Nimrod compiler, Nimrod's stdlib, tools and +documentation. ## Compiling Compiling the Nimrod compiler is quite straightforward. Because @@ -9,10 +10,11 @@ latest version. The C sources are however included with this repository under the build directory. Pre-compiled snapshots of the compiler are also available on -[Nimbuild](http://build.nimrod-code.org/). Your platform however may not currently -be built for. +[Nimbuild](http://build.nimrod-code.org/). Your platform however may not +currently be built for. -The compiler currently supports the following platform and architecture combinations: +The compiler currently supports the following platform and architecture +combinations: * Windows (Windows XP or greater) - x86 and x86_64 * Linux (most, if not all, distributions) - x86, x86_64, ppc64 and armv6l @@ -47,7 +49,8 @@ instead of ``build.sh``. ## Getting help A [forum](http://forum.nimrod-code.org/) is available if you have any questions, -and you can also get help in the IRC channel on [Freenode](irc://irc.freenode.net/nimrod) in #nimrod. +and you can also get help in the IRC channel +on [Freenode](irc://irc.freenode.net/nimrod) in #nimrod. ## License The compiler is licensed under the GPLv2 license, the standard library is diff --git a/todo.txt b/todo.txt index 66d76926e..3854102c2 100755 --- a/todo.txt +++ b/todo.txt @@ -1,12 +1,12 @@ version 0.9.2 ============= -- overloading based on ASTs +- document overloading based on ASTs - implement ``partial`` pragma for partial evaluation: easily done with AST overloading - ``hoist`` pragma for loop hoisting: can be easily done with AST overloading + global - - document overloading based on ASTs + - move semantics - test&finish first class iterators: * nested iterators -- cgit 1.4.1-2-gfad0 From da825a0fe2842468f7e925de1f088e62c74bcd9b Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Sun, 16 Dec 2012 03:57:17 +0900 Subject: cd to build/, before trying to extract csources.zip --- readme.md | 6 ++++-- readme.txt | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) (limited to 'readme.txt') diff --git a/readme.md b/readme.md index fe4542b56..d5cb35820 100644 --- a/readme.md +++ b/readme.md @@ -34,7 +34,9 @@ If you are on a fairly modern *nix system, the following steps should work: ``` $ git clone git://github.com/Araq/Nimrod.git $ cd Nimrod -$ unzip build/csources.zip +$ cd build +$ unzip csources.zip +$ cd .. $ ./build.sh $ bin/nimrod c koch $ ./koch boot -d:release @@ -61,4 +63,4 @@ developed with Nimrod, allowing you to create commercial applications. Read copying.txt for more details. Copyright (c) 2004-2012 Andreas Rumpf. -All rights reserved. \ No newline at end of file +All rights reserved. diff --git a/readme.txt b/readme.txt index fe4542b56..d5cb35820 100755 --- a/readme.txt +++ b/readme.txt @@ -34,7 +34,9 @@ If you are on a fairly modern *nix system, the following steps should work: ``` $ git clone git://github.com/Araq/Nimrod.git $ cd Nimrod -$ unzip build/csources.zip +$ cd build +$ unzip csources.zip +$ cd .. $ ./build.sh $ bin/nimrod c koch $ ./koch boot -d:release @@ -61,4 +63,4 @@ developed with Nimrod, allowing you to create commercial applications. Read copying.txt for more details. Copyright (c) 2004-2012 Andreas Rumpf. -All rights reserved. \ No newline at end of file +All rights reserved. -- cgit 1.4.1-2-gfad0 From 3c73654acaff5aef6f5ca60facf2bf43c00a4e36 Mon Sep 17 00:00:00 2001 From: Araq Date: Tue, 8 Jan 2013 07:54:23 +0100 Subject: Copyright 2012 -> 2013 --- compiler/commands.nim | 4 ++-- compiler/main.nim | 2 +- compiler/nimrod.nim | 2 +- koch.nim | 4 ++-- lib/system/sysio.nim | 2 +- readme.md | 2 +- readme.txt | 2 +- web/news.txt | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) (limited to 'readme.txt') diff --git a/compiler/commands.nim b/compiler/commands.nim index 8c0e9a784..d999dc065 100755 --- a/compiler/commands.nim +++ b/compiler/commands.nim @@ -1,7 +1,7 @@ # # # The Nimrod Compiler -# (c) Copyright 2012 Andreas Rumpf +# (c) Copyright 2013 Andreas Rumpf # # See the file "copying.txt", included in this # distribution, for details about the copyright. @@ -27,7 +27,7 @@ proc processSwitch*(switch, arg: string, pass: TCmdlinePass, info: TLineInfo) const HelpMessage = "Nimrod Compiler Version $1 (" & compileDate & ") [$2: $3]\n" & - "Copyright (c) 2004-2012 by Andreas Rumpf\n" + "Copyright (c) 2004-2013 by Andreas Rumpf\n" const Usage = slurp"doc/basicopt.txt".replace("//", "") diff --git a/compiler/main.nim b/compiler/main.nim index 93def6f09..517bceb3c 100755 --- a/compiler/main.nim +++ b/compiler/main.nim @@ -1,7 +1,7 @@ # # # The Nimrod Compiler -# (c) Copyright 2012 Andreas Rumpf +# (c) Copyright 2013 Andreas Rumpf # # See the file "copying.txt", included in this # distribution, for details about the copyright. diff --git a/compiler/nimrod.nim b/compiler/nimrod.nim index 1a73bcca0..24b8518d7 100755 --- a/compiler/nimrod.nim +++ b/compiler/nimrod.nim @@ -1,7 +1,7 @@ # # # The Nimrod Compiler -# (c) Copyright 2012 Andreas Rumpf +# (c) Copyright 2013 Andreas Rumpf # # See the file "copying.txt", included in this # distribution, for details about the copyright. diff --git a/koch.nim b/koch.nim index b01de94cb..2a22d7ca5 100755 --- a/koch.nim +++ b/koch.nim @@ -1,7 +1,7 @@ # # # Maintenance program for Nimrod -# (c) Copyright 2012 Andreas Rumpf +# (c) Copyright 2013 Andreas Rumpf # # See the file "copying.txt", included in this # distribution, for details about the copyright. @@ -26,7 +26,7 @@ const +-----------------------------------------------------------------+ | Maintenance program for Nimrod | | Version $1| -| (c) 2012 Andreas Rumpf | +| (c) 2013 Andreas Rumpf | +-----------------------------------------------------------------+ Build time: $2, $3 diff --git a/lib/system/sysio.nim b/lib/system/sysio.nim index 9055cca40..c7accbac0 100755 --- a/lib/system/sysio.nim +++ b/lib/system/sysio.nim @@ -1,7 +1,7 @@ # # # Nimrod's Runtime Library -# (c) Copyright 2012 Andreas Rumpf +# (c) Copyright 2013 Andreas Rumpf # # See the file "copying.txt", included in this # distribution, for details about the copyright. diff --git a/readme.md b/readme.md index d5cb35820..3e39b5f77 100644 --- a/readme.md +++ b/readme.md @@ -62,5 +62,5 @@ developed with Nimrod, allowing you to create commercial applications. Read copying.txt for more details. -Copyright (c) 2004-2012 Andreas Rumpf. +Copyright (c) 2004-2013 Andreas Rumpf. All rights reserved. diff --git a/readme.txt b/readme.txt index d5cb35820..3e39b5f77 100755 --- a/readme.txt +++ b/readme.txt @@ -62,5 +62,5 @@ developed with Nimrod, allowing you to create commercial applications. Read copying.txt for more details. -Copyright (c) 2004-2012 Andreas Rumpf. +Copyright (c) 2004-2013 Andreas Rumpf. All rights reserved. diff --git a/web/news.txt b/web/news.txt index 802825515..824e0c3a3 100755 --- a/web/news.txt +++ b/web/news.txt @@ -2,7 +2,7 @@ News ==== -2012-XX-XX Version 0.9.2 released +2013-XX-XX Version 0.9.2 released ================================= Version 0.9.2 has been released! Get it `here `_. -- cgit 1.4.1-2-gfad0