mirror of
https://github.com/nim-lang/Nim.git
synced 2026-04-27 01:34:02 +00:00
resolved system.nim conflicts
This commit is contained in:
Andreas Rumpf
@@ -10,21 +10,21 @@ a `base type`:idx:.
|
||||
|
||||
Use case 1: SQL strings
|
||||
-----------------------
|
||||
An SQL statement that is passed from Nimrod to an SQL database might be
|
||||
An SQL statement that is passed from Nimrod to an SQL database might be
|
||||
modelled as a string. However, using string templates and filling in the
|
||||
values is vulnerable to the famous `SQL injection attack`:idx:\:
|
||||
values is vulnerable to the famous `SQL injection attack`:idx:\:
|
||||
|
||||
.. code-block:: nimrod
|
||||
proc query(db: TDbHandle, statement: TSQL) = ...
|
||||
|
||||
var
|
||||
username: string
|
||||
|
||||
|
||||
db.query("SELECT FROM users WHERE name = '$1'" % username)
|
||||
# Horrible security whole, but the compiler does not mind!
|
||||
|
||||
This can be avoided by distinguishing strings that contain SQL from strings
|
||||
that don't. Abstract types provide a means to introduce a new string type
|
||||
# Horrible security hole, but the compiler does not mind!
|
||||
|
||||
This can be avoided by distinguishing strings that contain SQL from strings
|
||||
that don't. Abstract types provide a means to introduce a new string type
|
||||
``TSQL`` that is incompatible with ``string``:
|
||||
|
||||
.. code-block:: nimrod
|
||||
@@ -35,26 +35,26 @@ that don't. Abstract types provide a means to introduce a new string type
|
||||
|
||||
var
|
||||
username: string
|
||||
|
||||
|
||||
db.query("SELECT FROM users WHERE name = '$1'" % username)
|
||||
# Error at compile time: `query` expects an SQL string!
|
||||
|
||||
|
||||
|
||||
|
||||
It is an essential property of abstract types that they **do not** imply a
|
||||
subtype relation between the abtract type and its base type. Explict type
|
||||
conversions from ``string`` to ``TSQL`` are allowed:
|
||||
conversions from ``string`` to ``TSQL`` are allowed:
|
||||
|
||||
.. code-block:: nimrod
|
||||
proc properQuote(s: string): TSQL =
|
||||
proc properQuote(s: string): TSQL =
|
||||
# quotes a string properly for an SQL statement
|
||||
...
|
||||
|
||||
proc `%` (frmt: TSQL, values: openarray[string]): TSQL =
|
||||
|
||||
proc `%` (frmt: TSQL, values: openarray[string]): TSQL =
|
||||
# quote each argument:
|
||||
var v = values.each(properQuote)
|
||||
# we need a temporary type for the type conversion :-(
|
||||
type TStrSeq = seq[string]
|
||||
# call strutils.`%`:
|
||||
# call strutils.`%`:
|
||||
result = TSQL(string(frmt) % TStrSeq(v))
|
||||
|
||||
db.query("SELECT FROM users WHERE name = $1".TSQL % username)
|
||||
@@ -68,43 +68,43 @@ for nice looking ``TSQL`` string literals.
|
||||
Use case 2: Money
|
||||
-----------------
|
||||
Different currencies should not be mixed in monetary calculations. Abstract
|
||||
types are a perfect tool to model different currencies:
|
||||
types are a perfect tool to model different currencies:
|
||||
|
||||
.. code-block:: nimrod
|
||||
type
|
||||
TDollar = abstract int
|
||||
TEuro = abstract int
|
||||
|
||||
|
||||
var
|
||||
d: TDollar
|
||||
e: TEuro
|
||||
|
||||
echo d + 12
|
||||
|
||||
echo d + 12
|
||||
# Error: cannot add a number with no unit with a ``TDollar``
|
||||
|
||||
Unfortunetaly, ``d + 12.TDollar`` is not allowed either,
|
||||
Unfortunetaly, ``d + 12.TDollar`` is not allowed either,
|
||||
because ``+`` is defined for ``int`` (among others), not for ``TDollar``. So
|
||||
we define our own ``+`` for dollars:
|
||||
we define our own ``+`` for dollars:
|
||||
|
||||
.. code-block::
|
||||
proc `+` (x, y: TDollar): TDollar =
|
||||
.. code-block::
|
||||
proc `+` (x, y: TDollar): TDollar =
|
||||
result = TDollar(int(x) + int(y))
|
||||
|
||||
It does not make sense to multiply a dollar with a dollar, but with a
|
||||
number without unit; and the same holds for division:
|
||||
|
||||
.. code-block::
|
||||
proc `*` (x: TDollar, y: int): TDollar =
|
||||
.. code-block::
|
||||
proc `*` (x: TDollar, y: int): TDollar =
|
||||
result = TDollar(int(x) * y)
|
||||
|
||||
proc `*` (x: int, y: TDollar): TDollar =
|
||||
proc `*` (x: int, y: TDollar): TDollar =
|
||||
result = TDollar(x * int(y))
|
||||
|
||||
|
||||
proc `div` ...
|
||||
|
||||
This quickly gets tedious. The implementations are trivial and the compiler
|
||||
This quickly gets tedious. The implementations are trivial and the compiler
|
||||
should not generate all this code only to optimize it away later - after all
|
||||
``+`` for dollars should produce the same binary code as ``+`` for ints.
|
||||
``+`` for dollars should produce the same binary code as ``+`` for ints.
|
||||
The pragma ``borrow`` has been designed to solve this problem; in principle
|
||||
it generates the trivial implementation for us:
|
||||
|
||||
@@ -113,40 +113,40 @@ it generates the trivial implementation for us:
|
||||
proc `*` (x: int, y: TDollar): TDollar {.borrow.}
|
||||
proc `div` (x: TDollar, y: int): TDollar {.borrow.}
|
||||
|
||||
The ``borrow`` pragma makes the compiler use the same implementation as
|
||||
The ``borrow`` pragma makes the compiler to use the same implementation as
|
||||
the proc that deals with the abstract type's base type, so no code is
|
||||
generated.
|
||||
generated.
|
||||
|
||||
But it seems we still have to repeat all this boilerplate code for
|
||||
the ``TEuro`` currency. Fortunately, Nimrod has a template mechanism:
|
||||
the ``TEuro`` currency. Fortunately, Nimrod has a template mechanism:
|
||||
|
||||
.. code-block:: nimrod
|
||||
template Additive(typ: typeDesc): stmt =
|
||||
proc `+` *(x, y: typ): typ {.borrow.}
|
||||
proc `-` *(x, y: typ): typ {.borrow.}
|
||||
|
||||
|
||||
# unary operators:
|
||||
proc `+` *(x: typ): typ {.borrow.}
|
||||
proc `-` *(x: typ): typ {.borrow.}
|
||||
|
||||
template Multiplicative(typ, base: typeDesc): stmt =
|
||||
|
||||
template Multiplicative(typ, base: typeDesc): stmt =
|
||||
proc `*` *(x: typ, y: base): typ {.borrow.}
|
||||
proc `*` *(x: base, y: typ): typ {.borrow.}
|
||||
proc `div` *(x: typ, y: base): typ {.borrow.}
|
||||
proc `mod` *(x: typ, y: base): typ {.borrow.}
|
||||
|
||||
template Comparable(typ: typeDesc): stmt =
|
||||
|
||||
template Comparable(typ: typeDesc): stmt =
|
||||
proc `<` * (x, y: typ): bool {.borrow.}
|
||||
proc `<=` * (x, y: typ): bool {.borrow.}
|
||||
proc `==` * (x, y: typ): bool {.borrow.}
|
||||
|
||||
template DefineCurrency(typ, base: expr): stmt =
|
||||
|
||||
template DefineCurrency(typ, base: expr): stmt =
|
||||
type
|
||||
typ* = abstract base
|
||||
Additive(typ)
|
||||
Multiplicative(typ, base)
|
||||
Comparable(typ)
|
||||
|
||||
|
||||
DefineCurrency(TDollar, int)
|
||||
DefineCurrency(TEuro, int)
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ explicit like in Haskell?
|
||||
The idea is that side effects and partial evaluation belong together:
|
||||
Iff a proc is side effect free and all its argument are evaluable at
|
||||
compile time, it can be evaluated by the compiler. However, really
|
||||
difficult is the ``newString`` proc: If it is simply wrapped, it
|
||||
difficult is the ``newString`` proc: If it is simply wrapped, it
|
||||
should not be evaluated at compile time! On other occasions it can
|
||||
and should be evaluted:
|
||||
|
||||
@@ -20,22 +20,22 @@ and should be evaluted:
|
||||
result[i] = toUpper(s[i])
|
||||
|
||||
No, it really can always be evaluated. The code generator should transform
|
||||
``s = "\0\0\0..."`` back into ``s = newString(...)``.
|
||||
``s = "\0\0\0..."`` back into ``s = newString(...)``.
|
||||
|
||||
|
||||
``new`` cannot be evaluated at compile time either.
|
||||
``new`` cannot be evaluated at compile time either.
|
||||
|
||||
|
||||
Raise statement
|
||||
===============
|
||||
|
||||
It is impractical to consider ``raise`` a statement with side effects.
|
||||
It is impractical to consider ``raise`` as a statement with side effects.
|
||||
|
||||
|
||||
Solution
|
||||
========
|
||||
|
||||
Being side effect free does not suffice for compile time evaluation. However,
|
||||
the evaluator can attempt to evaluate at compile time.
|
||||
the evaluator can attempt to evaluate at compile time.
|
||||
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ available for the debugger.
|
||||
|
||||
If you start your program the debugger will immediately show
|
||||
a prompt on the console. You can now enter a command. The next sections
|
||||
deal with the possible commands. As usual for Nimrod for all commands
|
||||
deal with the possible commands. As usual in Nimrod in all commands
|
||||
underscores and case do not matter. Optional components of a command
|
||||
are listed in brackets ``[...]`` here.
|
||||
|
||||
|
||||
76
doc/lib.txt
76
doc/lib.txt
@@ -12,7 +12,7 @@ Nimrod Standard Library
|
||||
Though the Nimrod Standard Library is still evolving, it is already quite
|
||||
usable. It is divided into *pure libraries*, *impure libraries* and *wrappers*.
|
||||
|
||||
Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary
|
||||
Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary
|
||||
while impure libraries do. A wrapper is an impure library that is a very
|
||||
low-level interface to a C library.
|
||||
|
||||
@@ -31,7 +31,7 @@ Core
|
||||
implicitly by the compiler. Do not import it directly. It relies on compiler
|
||||
magic to work.
|
||||
|
||||
* `macros <macros.html>`_
|
||||
* `macros <macros.html>`_
|
||||
Contains the AST API and documentation of Nimrod for writing macros.
|
||||
|
||||
|
||||
@@ -39,8 +39,8 @@ String handling
|
||||
---------------
|
||||
|
||||
* `strutils <strutils.html>`_
|
||||
This module contains common string handling operations like converting a
|
||||
string into uppercase, splitting a string into substrings, searching for
|
||||
This module contains common string handling operations like changing
|
||||
case of a string, splitting a string into substrings, searching for
|
||||
substrings, replacing substrings.
|
||||
|
||||
* `parseutils <parseutils.html>`_
|
||||
@@ -52,7 +52,7 @@ String handling
|
||||
style-insensitive mode. An efficient string substitution operator ``%``
|
||||
for the string table is also provided.
|
||||
|
||||
* `unicode <unicode.html>`_
|
||||
* `unicode <unicode.html>`_
|
||||
This module provides support to handle the Unicode UTF-8 encoding.
|
||||
|
||||
* `re <re.html>`_
|
||||
@@ -67,11 +67,11 @@ String handling
|
||||
Ropes can represent very long strings efficiently; especially concatenation
|
||||
is done in O(1) instead of O(n).
|
||||
|
||||
* `unidecode <unidecode.html>`_
|
||||
* `unidecode <unidecode.html>`_
|
||||
This module provides Unicode to ASCII transliterations:
|
||||
It finds the sequence of ASCII characters that is the closest approximation
|
||||
to the Unicode string.
|
||||
|
||||
|
||||
|
||||
Generic Operating System Services
|
||||
---------------------------------
|
||||
@@ -97,8 +97,8 @@ Generic Operating System Services
|
||||
may provide other implementations for this standard stream interface.
|
||||
|
||||
* `terminal <terminal.html>`_
|
||||
This module contains a few procedures to control the *terminal*
|
||||
(also called *console*). The implementation simply uses ANSI escape
|
||||
This module contains a few procedures to control the *terminal*
|
||||
(also called *console*). The implementation simply uses ANSI escape
|
||||
sequences and does not depend on any other module.
|
||||
|
||||
|
||||
@@ -117,20 +117,20 @@ Internet Protocols and Support
|
||||
------------------------------
|
||||
|
||||
* `cgi <cgi.html>`_
|
||||
This module implements helpers for CGI applictions.
|
||||
This module implements helpers for CGI applictions.
|
||||
|
||||
* `sockets <sockets.html>`_
|
||||
This module implements a simple portable type-safe sockets layer.
|
||||
|
||||
* `browsers <browsers.html>`_
|
||||
This module implements procs for opening URLs with the user's default
|
||||
This module implements procs for opening URLs with the user's default
|
||||
browser.
|
||||
|
||||
|
||||
* `httpserver <httpserver.html>`_
|
||||
This module implements a simple HTTP server.
|
||||
|
||||
|
||||
* `httpclient <httpclient.html>`_
|
||||
This module implements a simple HTTP client.
|
||||
This module implements a simple HTTP client.
|
||||
|
||||
|
||||
Parsers
|
||||
@@ -149,14 +149,14 @@ Parsers
|
||||
as in the Nimrod programming language.
|
||||
|
||||
* `parsexml <parsexml.html>`_
|
||||
The ``parsexml`` module implements a simple high performance XML/HTML parser.
|
||||
The ``parsexml`` module implements a simple high performance XML/HTML parser.
|
||||
The only encoding that is supported is UTF-8. The parser has been designed
|
||||
to be somewhat error correcting, so that even some "wild HTML" found on the
|
||||
web can be parsed with it.
|
||||
to be somewhat error correcting, so that even some "wild HTML" found on the
|
||||
Web can be parsed with it.
|
||||
|
||||
* `parsecsv <parsecsv.html>`_
|
||||
* `parsecsv <parsecsv.html>`_
|
||||
The ``parsecsv`` module implements a simple high performance CSV parser.
|
||||
|
||||
|
||||
* `parsesql <parsesql.html>`_
|
||||
The ``parsesql`` module implements a simple high performance SQL parser.
|
||||
|
||||
@@ -168,20 +168,20 @@ Parsers
|
||||
XML Processing
|
||||
--------------
|
||||
|
||||
* `xmldom <xmldom.html>`_
|
||||
* `xmldom <xmldom.html>`_
|
||||
This module implements the XML DOM Level 2.
|
||||
|
||||
* `xmldomparser <xmldomparser.html>`_
|
||||
This module parses an XML Document into a XML DOM Document representation.
|
||||
|
||||
* `xmltree <xmltree.html>`_
|
||||
A simple XML tree. More efficient and simpler than the DOM. It also
|
||||
A simple XML tree. More efficient and simpler than the DOM. It also
|
||||
contains a macro for XML/HTML code generation.
|
||||
|
||||
* `xmlparser <xmlparser.html>`_
|
||||
* `xmlparser <xmlparser.html>`_
|
||||
This module parses an XML document and creates its XML tree representation.
|
||||
|
||||
* `htmlparser <htmlparser.html>`_
|
||||
|
||||
* `htmlparser <htmlparser.html>`_
|
||||
This module parses an HTML document and creates its XML tree representation.
|
||||
|
||||
|
||||
@@ -199,8 +199,8 @@ Cryptography and Hashing
|
||||
Multimedia support
|
||||
------------------
|
||||
|
||||
* `colors <colors.html>`_
|
||||
This module implements color handling for Nimrod. It is used by
|
||||
* `colors <colors.html>`_
|
||||
This module implements color handling for Nimrod. It is used by
|
||||
the ``graphics`` module.
|
||||
|
||||
|
||||
@@ -211,7 +211,7 @@ Impure libraries
|
||||
* `graphics <graphics.html>`_
|
||||
This module implements graphical output for Nimrod; the current
|
||||
implementation uses SDL but the interface is meant to support multiple
|
||||
backends some day.
|
||||
backends some day.
|
||||
|
||||
* `dialogs <dialogs.html>`_
|
||||
This module implements portable dialogs for Nimrod; the implementation
|
||||
@@ -220,10 +220,10 @@ Impure libraries
|
||||
|
||||
* `zipfiles <zipfiles.html>`_
|
||||
This module implements a zip archive creator/reader/modifier.
|
||||
|
||||
|
||||
* `web <web.html>`_
|
||||
This module contains simple high-level procedures for dealing with the
|
||||
web like loading the contents of a web page from an URL.
|
||||
Web like loading the contents of a Web page from an URL.
|
||||
|
||||
|
||||
Database support
|
||||
@@ -232,11 +232,11 @@ Database support
|
||||
* `db_postgres <db_postgres.html>`_
|
||||
A higher level PostgreSQL database wrapper. The same interface is implemented
|
||||
for other databases too.
|
||||
|
||||
|
||||
* `db_mysql <db_mysql.html>`_
|
||||
A higher level mySQL database wrapper. The same interface is implemented
|
||||
A higher level MySQL database wrapper. The same interface is implemented
|
||||
for other databases too.
|
||||
|
||||
|
||||
* `db_sqlite <db_sqlite.html>`_
|
||||
A higher level SQLite database wrapper. The same interface is implemented
|
||||
for other databases too.
|
||||
@@ -255,7 +255,7 @@ not contained in the distribution. You can then find them on the website.
|
||||
Contains a wrapper for the Win32 API.
|
||||
* `mysql <mysql.html>`_
|
||||
Contains a wrapper for the mySQL API.
|
||||
* `sqlite3 <sqlite3.html>`_
|
||||
* `sqlite3 <sqlite3.html>`_
|
||||
Contains a wrapper for SQLite 3 API.
|
||||
* `libcurl <libcurl.html>`_
|
||||
Contains a wrapper for the libcurl library.
|
||||
@@ -317,14 +317,14 @@ not contained in the distribution. You can then find them on the website.
|
||||
Part of the wrapper for Lua.
|
||||
* `lauxlib <lauxlib.html>`_
|
||||
Part of the wrapper for Lua.
|
||||
* `tcl <tcl.html>`_
|
||||
* `tcl <tcl.html>`_
|
||||
Wrapper for the TCL programming language.
|
||||
* `python <python.html>`_
|
||||
Wrapper for the Python programming language.
|
||||
* `odbcsql <odbcsql.html>`_
|
||||
interface to the ODBC driver.
|
||||
* `zlib <zlib.html>`_
|
||||
Wrapper for the zlib library.
|
||||
Wrapper for the zlib library.
|
||||
* `sdl <sdl.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `sdl_gfx <sdl_gfx.html>`_
|
||||
@@ -379,7 +379,7 @@ not contained in the distribution. You can then find them on the website.
|
||||
Part of the wrapper for X11.
|
||||
* `libzip <libzip.html>`_
|
||||
Interface to the `lib zip <http://www.nih.at/libzip/index.html>`_ library by
|
||||
Dieter Baron and Thomas Klausner.
|
||||
* `iup <iup.html>`_
|
||||
Dieter Baron and Thomas Klausner.
|
||||
* `iup <iup.html>`_
|
||||
Wrapper of the IUP GUI library.
|
||||
|
||||
|
||||
|
||||
5529
doc/manual.txt
5529
doc/manual.txt
File diff suppressed because it is too large
Load Diff
478
doc/nimrodc.txt
478
doc/nimrodc.txt
@@ -1,239 +1,239 @@
|
||||
===================================
|
||||
Nimrod Compiler User Guide
|
||||
===================================
|
||||
|
||||
:Author: Andreas Rumpf
|
||||
:Version: |nimrodversion|
|
||||
|
||||
.. contents::
|
||||
|
||||
"Look at you, hacker. A pathetic creature of meat and bone, panting and
|
||||
sweating as you run through my corridors. How can you challenge a perfect,
|
||||
immortal machine?"
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This document describes the usage of the *Nimrod compiler*
|
||||
on the different supported platforms. It is not a definition of the Nimrod
|
||||
programming language (therefore is the `manual <manual>`_).
|
||||
|
||||
Nimrod is free software; it is licensed under the
|
||||
`GNU General Public License <gpl.html>`_.
|
||||
|
||||
|
||||
Compiler Usage
|
||||
==============
|
||||
|
||||
Command line switches
|
||||
---------------------
|
||||
Basis command line switches are:
|
||||
|
||||
.. include:: ../data/basicopt.txt
|
||||
|
||||
Advanced command line switches are:
|
||||
|
||||
.. include:: ../data/advopt.txt
|
||||
|
||||
|
||||
Configuration file
|
||||
------------------
|
||||
The default configuration file is ``nimrod.cfg``. The ``nimrod`` executable
|
||||
looks for it in the following directories (in this order):
|
||||
|
||||
1. ``/home/$user/.config/nimrod.cfg`` (UNIX) or ``%APPDATA%/nimrod.cfg`` (Windows)
|
||||
2. ``$nimrod/config/nimrod.cfg`` (UNIX, Windows)
|
||||
3. ``/etc/nimrod.cfg`` (UNIX)
|
||||
|
||||
The search stops as soon as a configuration file has been found. The reading
|
||||
of ``nimrod.cfg`` can be suppressed by the ``--skipCfg`` command line option.
|
||||
|
||||
**Note:** The *project file name* is the name of the ``.nim`` file that is
|
||||
passed as a command line argument to the compiler.
|
||||
|
||||
Configuration settings can be overwritten in a project specific
|
||||
configuration file that is read automatically. This specific file has to
|
||||
be in the same directory as the project and be of the same name, except
|
||||
that its extension should be ``.cfg``.
|
||||
|
||||
Command line settings have priority over configuration file settings.
|
||||
|
||||
|
||||
Generated C code directory
|
||||
--------------------------
|
||||
The generated files that Nimrod produces all go into a subdirectory called
|
||||
``nimcache`` in your project directory. This makes it easy to delete all
|
||||
generated files.
|
||||
|
||||
However, the generated C code is not platform independant. C code generated for
|
||||
Linux does not compile on Windows, for instance. The comment on top of the
|
||||
C file lists the OS, CPU and CC the file has been compiled for.
|
||||
|
||||
|
||||
Additional Features
|
||||
===================
|
||||
|
||||
This section describes Nimrod's additional features that are not listed in the
|
||||
Nimrod manual. Some of the features here only make sense for the C code
|
||||
generator and are subject to change.
|
||||
|
||||
|
||||
NoDecl pragma
|
||||
-------------
|
||||
The `noDecl`:idx: pragma can be applied to almost any symbol (variable, proc,
|
||||
type, etc.) and is sometimes useful for interoperability with C:
|
||||
It tells Nimrod that it should not generate a declaration for the symbol in
|
||||
the C code. For example:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
var
|
||||
EACCES {.importc, noDecl.}: cint # pretend EACCES was a variable, as
|
||||
# Nimrod does not know its value
|
||||
|
||||
However, the ``header`` pragma is often the better alternative.
|
||||
|
||||
**Note**: This will not work for the LLVM backend.
|
||||
|
||||
|
||||
Header pragma
|
||||
-------------
|
||||
The `header`:idx: pragma is very similar to the ``noDecl`` pragma: It can be
|
||||
applied to almost any symbol and specifies that it should not be declared
|
||||
and instead the generated code should contain an ``#include``:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
type
|
||||
PFile {.importc: "FILE*", header: "<stdio.h>".} = distinct pointer
|
||||
# import C's FILE* type; Nimrod will treat it as a new pointer type
|
||||
|
||||
The ``header`` pragma always expects a string constant. The string contant
|
||||
contains the header file: As usual for C, a system header file is enclosed
|
||||
in angle brackets: ``<>``. If no angle brackets are given, Nimrod
|
||||
encloses the header file in ``""`` in the generated C code.
|
||||
|
||||
**Note**: This will not work for the LLVM backend.
|
||||
|
||||
|
||||
LineDir option
|
||||
--------------
|
||||
The `lineDir`:idx: option can be turned on or off. If turned on the
|
||||
generated C code contains ``#line`` directives. This may be helpful for
|
||||
debugging with GDB.
|
||||
|
||||
|
||||
StackTrace option
|
||||
-----------------
|
||||
If the `stackTrace`:idx: option is turned on, the generated C contains code to
|
||||
ensure that proper stack traces are given if the program crashes or an
|
||||
uncaught exception is raised.
|
||||
|
||||
|
||||
LineTrace option
|
||||
----------------
|
||||
The `lineTrace`:idx: option implies the ``stackTrace`` option. If turned on,
|
||||
the generated C contains code to ensure that proper stack traces with line
|
||||
number information are given if the program crashes or an uncaught exception
|
||||
is raised.
|
||||
|
||||
Debugger option
|
||||
---------------
|
||||
The `debugger`:idx: option enables or disables the *Embedded Nimrod Debugger*.
|
||||
See the documentation of endb_ for further information.
|
||||
|
||||
|
||||
Breakpoint pragma
|
||||
-----------------
|
||||
The *breakpoint* pragma was specially added for the sake of debugging with
|
||||
ENDB. See the documentation of `endb <endb.html>`_ for further information.
|
||||
|
||||
|
||||
Volatile pragma
|
||||
---------------
|
||||
The `volatile`:idx: pragma is for variables only. It declares the variable as
|
||||
``volatile``, whatever that means in C/C++.
|
||||
|
||||
**Note**: This pragma will not exist for the LLVM backend.
|
||||
|
||||
|
||||
Debugging with Nimrod
|
||||
=====================
|
||||
|
||||
Nimrod comes with its own *Embedded Nimrod Debugger*. See
|
||||
the documentation of endb_ for further information.
|
||||
|
||||
|
||||
Optimizing for Nimrod
|
||||
=====================
|
||||
|
||||
Nimrod has no separate optimizer, but the C code that is produced is very
|
||||
efficient. Most C compilers have excellent optimizers, so usually it is
|
||||
not needed to optimize one's code. Nimrod has been designed to encourage
|
||||
efficient code: The most readable code in Nimrod is often the most efficient
|
||||
too.
|
||||
|
||||
However, sometimes one has to optimize. Do it in the following order:
|
||||
|
||||
1. switch off the embedded debugger (it is **slow**!)
|
||||
2. turn on the optimizer and turn off runtime checks
|
||||
3. profile your code to find where the bottlenecks are
|
||||
4. try to find a better algorithm
|
||||
5. do low-level optimizations
|
||||
|
||||
This section can only help you with the last item.
|
||||
|
||||
|
||||
Optimizing string handling
|
||||
--------------------------
|
||||
|
||||
String assignments are sometimes expensive in Nimrod: They are required to
|
||||
copy the whole string. However, the compiler is often smart enough to not copy
|
||||
strings. Due to the argument passing semantics, strings are never copied when
|
||||
passed to subroutines. The compiler does not copy strings that are a result from
|
||||
a procedure call, because the callee returns a new string anyway.
|
||||
Thus it is efficient to do:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
var s = procA() # assignment will not copy the string; procA allocates a new
|
||||
# string already
|
||||
|
||||
However it is not efficient to do:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
var s = varA # assignment has to copy the whole string into a new buffer!
|
||||
|
||||
..
|
||||
String case statements are optimized too. A hashing scheme is used for them
|
||||
if several different string constants are used. This is likely to be more
|
||||
efficient than any hand-coded scheme.
|
||||
|
||||
|
||||
..
|
||||
The ECMAScript code generator
|
||||
=============================
|
||||
|
||||
Note: As of version 0.7.0 the ECMAScript code generator is not maintained any
|
||||
longer. Help if you are interested.
|
||||
|
||||
Note: I use the term `ECMAScript`:idx: here instead of `JavaScript`:idx:,
|
||||
since it is the proper term.
|
||||
|
||||
The ECMAScript code generator is experimental!
|
||||
|
||||
Nimrod targets ECMAScript 1.5 which is supported by any widely used browser.
|
||||
Since ECMAScript does not have a portable means to include another module,
|
||||
Nimrod just generates a long ``.js`` file.
|
||||
|
||||
Features or modules that the ECMAScript platform does not support are not
|
||||
available. This includes:
|
||||
|
||||
* manual memory management (``alloc``, etc.)
|
||||
* casting and other unsafe operations (``cast`` operator, ``zeroMem``, etc.)
|
||||
* file management
|
||||
* most modules of the Standard library
|
||||
* proper 64 bit integer arithmetic
|
||||
* proper unsigned integer arithmetic
|
||||
|
||||
However, the modules `strutils`:idx:, `math`:idx:, and `times`:idx: are
|
||||
available! To access the DOM, use the `dom`:idx: module that is only
|
||||
available for the ECMAScript platform.
|
||||
===================================
|
||||
Nimrod Compiler User Guide
|
||||
===================================
|
||||
|
||||
:Author: Andreas Rumpf
|
||||
:Version: |nimrodversion|
|
||||
|
||||
.. contents::
|
||||
|
||||
"Look at you, hacker. A pathetic creature of meat and bone, panting and
|
||||
sweating as you run through my corridors. How can you challenge a perfect,
|
||||
immortal machine?"
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This document describes the usage of the *Nimrod compiler*
|
||||
on the different supported platforms. It is not a definition of the Nimrod
|
||||
programming language (therefore is the `manual <manual>`_).
|
||||
|
||||
Nimrod is free software; it is licensed under the
|
||||
`GNU General Public License <gpl.html>`_.
|
||||
|
||||
|
||||
Compiler Usage
|
||||
==============
|
||||
|
||||
Command line switches
|
||||
---------------------
|
||||
Basis command line switches are:
|
||||
|
||||
.. include:: ../data/basicopt.txt
|
||||
|
||||
Advanced command line switches are:
|
||||
|
||||
.. include:: ../data/advopt.txt
|
||||
|
||||
|
||||
Configuration file
|
||||
------------------
|
||||
The default configuration file is ``nimrod.cfg``. The ``nimrod`` executable
|
||||
looks for it in the following directories (in this order):
|
||||
|
||||
1. ``/home/$user/.config/nimrod.cfg`` (UNIX) or ``%APPDATA%/nimrod.cfg`` (Windows)
|
||||
2. ``$nimrod/config/nimrod.cfg`` (UNIX), ``%NIMROD%/config/nimrod.cfg`` (Windows)
|
||||
3. ``/etc/nimrod.cfg`` (UNIX)
|
||||
|
||||
The search stops as soon as a configuration file has been found. The reading
|
||||
of ``nimrod.cfg`` can be suppressed by the ``--skipCfg`` command line option.
|
||||
|
||||
**Note:** The *project file name* is the name of the ``.nim`` file that is
|
||||
passed as a command line argument to the compiler.
|
||||
|
||||
Configuration settings can be overwritten individually in a project specific
|
||||
configuration file that is read automatically. This specific file has to
|
||||
be in the same directory as the project and be of the same name, except
|
||||
that its extension should be ``.cfg``.
|
||||
|
||||
Command line settings have priority over configuration file settings.
|
||||
|
||||
|
||||
Generated C code directory
|
||||
--------------------------
|
||||
The generated files that Nimrod produces all go into a subdirectory called
|
||||
``nimcache`` in your project directory. This makes it easy to delete all
|
||||
generated files.
|
||||
|
||||
However, the generated C code is not platform independant. C code generated for
|
||||
Linux does not compile on Windows, for instance. The comment on top of the
|
||||
C file lists the OS, CPU and CC the file has been compiled for.
|
||||
|
||||
|
||||
Additional Features
|
||||
===================
|
||||
|
||||
This section describes Nimrod's additional features that are not listed in the
|
||||
Nimrod manual. Some of the features here only make sense for the C code
|
||||
generator and are subject to change.
|
||||
|
||||
|
||||
NoDecl pragma
|
||||
-------------
|
||||
The `noDecl`:idx: pragma can be applied to almost any symbol (variable, proc,
|
||||
type, etc.) and is sometimes useful for interoperability with C:
|
||||
It tells Nimrod that it should not generate a declaration for the symbol in
|
||||
the C code. For example:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
var
|
||||
EACCES {.importc, noDecl.}: cint # pretend EACCES was a variable, as
|
||||
# Nimrod does not know its value
|
||||
|
||||
However, the ``header`` pragma is often the better alternative.
|
||||
|
||||
**Note**: This will not work for the LLVM backend.
|
||||
|
||||
|
||||
Header pragma
|
||||
-------------
|
||||
The `header`:idx: pragma is very similar to the ``noDecl`` pragma: It can be
|
||||
applied to almost any symbol and specifies that it should not be declared
|
||||
and instead the generated code should contain an ``#include``:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
type
|
||||
PFile {.importc: "FILE*", header: "<stdio.h>".} = distinct pointer
|
||||
# import C's FILE* type; Nimrod will treat it as a new pointer type
|
||||
|
||||
The ``header`` pragma always expects a string constant. The string contant
|
||||
contains the header file: As usual for C, a system header file is enclosed
|
||||
in angle brackets: ``<>``. If no angle brackets are given, Nimrod
|
||||
encloses the header file in ``""`` in the generated C code.
|
||||
|
||||
**Note**: This will not work for the LLVM backend.
|
||||
|
||||
|
||||
LineDir option
|
||||
--------------
|
||||
The `lineDir`:idx: option can be turned on or off. If turned on the
|
||||
generated C code contains ``#line`` directives. This may be helpful for
|
||||
debugging with GDB.
|
||||
|
||||
|
||||
StackTrace option
|
||||
-----------------
|
||||
If the `stackTrace`:idx: option is turned on, the generated C contains code to
|
||||
ensure that proper stack traces are given if the program crashes or an
|
||||
uncaught exception is raised.
|
||||
|
||||
|
||||
LineTrace option
|
||||
----------------
|
||||
The `lineTrace`:idx: option implies the ``stackTrace`` option. If turned on,
|
||||
the generated C contains code to ensure that proper stack traces with line
|
||||
number information are given if the program crashes or an uncaught exception
|
||||
is raised.
|
||||
|
||||
Debugger option
|
||||
---------------
|
||||
The `debugger`:idx: option enables or disables the *Embedded Nimrod Debugger*.
|
||||
See the documentation of endb_ for further information.
|
||||
|
||||
|
||||
Breakpoint pragma
|
||||
-----------------
|
||||
The *breakpoint* pragma was specially added for the sake of debugging with
|
||||
ENDB. See the documentation of `endb <endb.html>`_ for further information.
|
||||
|
||||
|
||||
Volatile pragma
|
||||
---------------
|
||||
The `volatile`:idx: pragma is for variables only. It declares the variable as
|
||||
``volatile``, whatever that means in C/C++.
|
||||
|
||||
**Note**: This pragma will not exist for the LLVM backend.
|
||||
|
||||
|
||||
Debugging with Nimrod
|
||||
=====================
|
||||
|
||||
Nimrod comes with its own *Embedded Nimrod Debugger*. See
|
||||
the documentation of endb_ for further information.
|
||||
|
||||
|
||||
Optimizing for Nimrod
|
||||
=====================
|
||||
|
||||
Nimrod has no separate optimizer, but the C code that is produced is very
|
||||
efficient. Most C compilers have excellent optimizers, so usually it is
|
||||
not needed to optimize one's code. Nimrod has been designed to encourage
|
||||
efficient code: The most readable code in Nimrod is often the most efficient
|
||||
too.
|
||||
|
||||
However, sometimes one has to optimize. Do it in the following order:
|
||||
|
||||
1. switch off the embedded debugger (it is **slow**!)
|
||||
2. turn on the optimizer and turn off runtime checks
|
||||
3. profile your code to find where the bottlenecks are
|
||||
4. try to find a better algorithm
|
||||
5. do low-level optimizations
|
||||
|
||||
This section can only help you with the last item.
|
||||
|
||||
|
||||
Optimizing string handling
|
||||
--------------------------
|
||||
|
||||
String assignments are sometimes expensive in Nimrod: They are required to
|
||||
copy the whole string. However, the compiler is often smart enough to not copy
|
||||
strings. Due to the argument passing semantics, strings are never copied when
|
||||
passed to subroutines. The compiler does not copy strings that are a result from
|
||||
a procedure call, because the callee returns a new string anyway.
|
||||
Thus it is efficient to do:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
var s = procA() # assignment will not copy the string; procA allocates a new
|
||||
# string already
|
||||
|
||||
However it is not efficient to do:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
var s = varA # assignment has to copy the whole string into a new buffer!
|
||||
|
||||
..
|
||||
String case statements are optimized too. A hashing scheme is used for them
|
||||
if several different string constants are used. This is likely to be more
|
||||
efficient than any hand-coded scheme.
|
||||
|
||||
|
||||
..
|
||||
The ECMAScript code generator
|
||||
=============================
|
||||
|
||||
Note: As of version 0.7.0 the ECMAScript code generator is not maintained any
|
||||
longer. Help if you are interested.
|
||||
|
||||
Note: I use the term `ECMAScript`:idx: here instead of `JavaScript`:idx:,
|
||||
since it is the proper term.
|
||||
|
||||
The ECMAScript code generator is experimental!
|
||||
|
||||
Nimrod targets ECMAScript 1.5 which is supported by any widely used browser.
|
||||
Since ECMAScript does not have a portable means to include another module,
|
||||
Nimrod just generates a long ``.js`` file.
|
||||
|
||||
Features or modules that the ECMAScript platform does not support are not
|
||||
available. This includes:
|
||||
|
||||
* manual memory management (``alloc``, etc.)
|
||||
* casting and other unsafe operations (``cast`` operator, ``zeroMem``, etc.)
|
||||
* file management
|
||||
* most modules of the Standard library
|
||||
* proper 64 bit integer arithmetic
|
||||
* proper unsigned integer arithmetic
|
||||
|
||||
However, the modules `strutils`:idx:, `math`:idx:, and `times`:idx: are
|
||||
available! To access the DOM, use the `dom`:idx: module that is only
|
||||
available for the ECMAScript platform.
|
||||
|
||||
22
doc/rst.txt
22
doc/rst.txt
@@ -5,16 +5,16 @@
|
||||
:Author: Andreas Rumpf
|
||||
:Version: |nimrodversion|
|
||||
|
||||
.. contents::
|
||||
.. contents::
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This document describes the subset of `Docutils`_' `reStructuredText`_ as it
|
||||
This document describes the subset of `Docutils`_' `reStructuredText`_ as it
|
||||
has been implemented in the Nimrod compiler for generating documentation.
|
||||
Elements of |rst| that are not listed here have not been implemented.
|
||||
Elements of |rst| that are not listed here have not been implemented.
|
||||
Unfortunately, the specification of |rst| is quite vague, so Nimrod is not as
|
||||
compatible to the original implementation as one would like.
|
||||
compatible to the original implementation as one would like.
|
||||
|
||||
Even though Nimrod's |rst| parser does not parse all constructs, it is pretty
|
||||
usable. The missing features can easily be circumvented. An indication of this
|
||||
@@ -26,13 +26,13 @@ Docutils' parser.)
|
||||
Inline elements
|
||||
===============
|
||||
|
||||
Ordinary text may contain *inline elements*.
|
||||
Ordinary text may contain *inline elements*.
|
||||
|
||||
|
||||
Bullet lists
|
||||
============
|
||||
|
||||
*Bullet lists* look like this::
|
||||
*Bullet lists* look like this::
|
||||
|
||||
* Item 1
|
||||
* Item 2 that
|
||||
@@ -60,8 +60,8 @@ Enumerated lists
|
||||
*Enumerated lists*
|
||||
|
||||
|
||||
Defintion lists
|
||||
===============
|
||||
Definition lists
|
||||
================
|
||||
|
||||
Save this code to the file "greeting.nim". Now compile and run it:
|
||||
|
||||
@@ -77,14 +77,14 @@ appending them after the filename that is to be compiled and run:
|
||||
Tables
|
||||
======
|
||||
|
||||
Nimrod only implements simple tables of the form::
|
||||
Nimrod only implements simple tables of the form::
|
||||
|
||||
================== =============== ===================
|
||||
header 1 header 2 header n
|
||||
================== =============== ===================
|
||||
Cell 1 Cell 2 Cell 3
|
||||
Cell 4 Cell 5; any Cell 6
|
||||
cell that is
|
||||
cell that is
|
||||
not in column 1
|
||||
may span over
|
||||
multiple lines
|
||||
@@ -97,7 +97,7 @@ header 1 header 2 header n
|
||||
================== =============== ===================
|
||||
Cell 1 Cell 2 Cell 3
|
||||
Cell 4 Cell 5; any Cell 6
|
||||
cell that is
|
||||
cell that is
|
||||
not in column 1
|
||||
may span over
|
||||
multiple lines
|
||||
|
||||
Reference in New Issue
Block a user