diff options
| -rw-r--r-- | compiler/installer.ini | 1 | ||||
| -rw-r--r-- | doc/lib.txt | 47 | ||||
| -rw-r--r-- | doc/nimsuggest.txt | 174 | ||||
| -rw-r--r-- | koch.nim | 4 | ||||
| -rw-r--r-- | web/documentation.txt | 21 | ||||
| -rw-r--r-- | web/download.txt | 8 | ||||
| -rw-r--r-- | web/learn.txt | 6 | ||||
| -rw-r--r-- | web/news.txt | 8 | ||||
| -rw-r--r-- | web/website.ini | 6 |
9 files changed, 218 insertions, 57 deletions
diff --git a/compiler/installer.ini b/compiler/installer.ini index d5ff52c5d..4ee50f2ff 100644 --- a/compiler/installer.ini +++ b/compiler/installer.ini @@ -219,6 +219,7 @@ Files: "tests/varstmt/*.nim" Files: "tests/vm/*.nim" Files: "tests/readme.txt" Files: "tests/testament/css/*.css" +Files: "tests/testament/*.cfg" Files: "lib/pure/unidecode/unidecode.dat" [Windows] diff --git a/doc/lib.txt b/doc/lib.txt index 385e7a91a..1c0278068 100644 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -37,7 +37,7 @@ Core * `unsigned <unsigned.html>`_ This module implements basic arithmetic operators for unsigned integers. - To discourage users from using unsigned integers, it's not part + To discourage users from using unsigned integers, it's not part of ``system``, but an extra import. * `threads <threads.html>`_ @@ -45,7 +45,7 @@ Core import it explicitly. * `channels <channels.html>`_ - Nim message passing support for threads. **Note**: This is part of the + Nim message passing support for threads. **Note**: This is part of the system module. Do not import it explicitly. * `locks <locks.html>`_ @@ -55,7 +55,7 @@ Core Contains the AST API and documentation of Nim for writing macros. * `typeinfo <typeinfo.html>`_ - Provides (unsafe) access to Nim's run time type information. + Provides (unsafe) access to Nim's run time type information. * `typetraits <typetraits.html>`_ This module defines compile-time reflection procs for working with types. @@ -110,9 +110,9 @@ String handling * `unicode <unicode.html>`_ This module provides support to handle the Unicode UTF-8 encoding. - + * `encodings <encodings.html>`_ - Converts between different character encodings. On UNIX, this uses + Converts between different character encodings. On UNIX, this uses the ``iconv`` library, on Windows the Windows API. * `pegs <pegs.html>`_ @@ -159,7 +159,7 @@ Generic Operating System Services may provide other implementations for this standard stream interface. * `marshal <marshal.html>`_ - Contains procs for serialization and deseralization of arbitrary Nim + Contains procs for serialization and deseralization of arbitrary Nim data structures. * `terminal <terminal.html>`_ @@ -168,7 +168,7 @@ Generic Operating System Services sequences and does not depend on any other module. * `memfiles <memfiles.html>`_ - This module provides support for memory mapped files (Posix's ``mmap``) + This module provides support for memory mapped files (Posix's ``mmap``) on the different operating systems. * `fsmonitor <fsmonitor.html>`_ @@ -228,7 +228,7 @@ Internet Protocols and Support This module implements a simple HTTP client. * `smtp <smtp.html>`_ - This module implement a simple SMTP client. + This module implement a simple SMTP client. * `ftpclient <ftpclient.html>`_ This module implements an FTP client. @@ -346,7 +346,7 @@ XML Processing This module parses an HTML document and creates its XML tree representation. * `htmlgen <htmlgen.html>`_ - This module implements a simple XML and HTML code + This module implements a simple XML and HTML code generator. Each commonly used HTML tag has a corresponding macro that generates a string with its HTML representation. @@ -381,7 +381,7 @@ Miscellaneous * `oids <oids.html>`_ An OID is a global ID that consists of a timestamp, - a unique counter and a random value. This combination should suffice to + a unique counter and a random value. This combination should suffice to produce a globally distributed unique ID. This implementation was extracted from the Mongodb interface and it thus binary compatible with a Mongo OID. @@ -453,12 +453,8 @@ Other * `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. - * `ssl <ssl.html>`_ - This module provides an easy to use sockets-style + This module provides an easy to use sockets-style Nim interface to the OpenSSL library. * `rdstdin <rdstdin.html>`_ @@ -513,25 +509,6 @@ Regular expressions Wrapper for the TRE library. -Graphics libraries ------------------- - -* `sdl <sdl.html>`_ - Part of the wrapper for SDL. -* `sdl_gfx <sdl_gfx.html>`_ - Part of the wrapper for SDL. -* `sdl_image <sdl_image.html>`_ - Part of the wrapper for SDL. -* `sdl_mixer <sdl_mixer.html>`_ - Part of the wrapper for SDL. -* `sdl_net <sdl_net.html>`_ - Part of the wrapper for SDL. -* `sdl_ttf <sdl_ttf.html>`_ - Part of the wrapper for SDL. -* `smpeg <smpeg.html>`_ - Part of the wrapper for SDL. - - GUI libraries ------------- @@ -591,7 +568,7 @@ Data Compression and Archiving Scientific computing -------------------- -* `libsvm <libsvm.html>`_ +* `libsvm <libsvm.html>`_ Low level wrapper for `lib svm <http://www.csie.ntu.edu.tw/~cjlin/libsvm/>`_. Nimble diff --git a/doc/nimsuggest.txt b/doc/nimsuggest.txt new file mode 100644 index 000000000..2b52196b9 --- /dev/null +++ b/doc/nimsuggest.txt @@ -0,0 +1,174 @@ +================================ + Nim IDE Integration Guide +================================ + +:Author: Unknown +:Version: |nimversion| + +.. contents:: + + +Nim differs from many other compilers in that it is really fast, +and being so fast makes it suited to provide external queries for +text editors about the source code being written. Through the +``nimsuggest`` tool, any IDE +can query a ``.nim`` source file and obtain useful information like +definition of symbols or suggestions for completion. + +This document will guide you through the available options. If you +want to look at practical examples of nimsuggest support you can look +at the +`various editor integrations <https://github.com/Araq/Nim/wiki/Editor-Support>`_ +already available. + + +Installation +============ + +Nimsuggest is available as a Nimble package but currently does not install +properly via Nimble. As nimsuggest is part of the compiler it also doesn't make +too much sense as a Nimble package. Instead we will do the building manually:: + + cd compiler/nimsuggest + nim c -d:release nimsuggest + cp nimsuggest ../../bin + # OR: copy the nimsuggest binary to where your 'nim' binary is + cd ../.. + + + +Nimsuggest invocation +===================== + +Run it via ``nimsuggest --stdin myproject.nim``. Nimsuggest is a server that +takes queries that are related to ``myproject``. There is some support so that +you can throw random ``.nim`` files which are not part of ``myproject`` at +Nimsuggest too, but usually the query refer to modules/files that are part of +``myproject``. + +``--stdin`` means that Nimsuggest reads the query from ``stdin``. This is great +for testing things out and playing with it but for an editor communication +via sockets is more reasonable so that is the default. It listens to port 6000 +by default. + + +Specifying the location of the query +------------------------------------ + +Nimsuggest than waits for queries to process. A query consists of a +cryptic 3 letter "command" ``def`` or ``con`` or ``sug`` or ``use`` followed by +a location. A query location consists of: + + +``file.nim`` + This is the name of the module or include file the query refers to. + +``dirtyfile.nim`` + This is optional. + + The ``file`` paramater is enough for static analysis, but IDEs + tend to have *unsaved buffers* where the user may still be in + the middle of typing a line. In such situations the IDE can + save the current contents to a temporary file and then use the + ``dirtyfile.nim`` option to tell Nimsuggest that ``foobar.nim`` should + be taken from ``temporary/foobar.nim``. + + +``line`` + An integer with the line you are going to query. For the compiler + lines start at **1**. + +``col`` + An integer with the column you are going to query. For the + compiler columns start at **1**. + + +Definitions +----------- + +The ``def`` Nimsuggest command performs a query about the definition +of a specific symbol. If available, Nimsuggest will answer with the +type, source file, line/column information and other accessory data +if available like a docstring. With this information an IDE can +provide the typical *Jump to definition* where a user puts the +cursor on a symbol or uses the mouse to select it and is redirected +to the place where the symbol is located. + +Since Nim is implemented in Nim, one of the nice things of +this feature is that any user with an IDE supporting it can quickly +jump around the standard library implementation and see exactly +what a proc does, learning about the language and seeing real life +examples of how to write/implement specific features. + +Nimsuggest will always answer with a single definition or none if it +can't find any valid symbol matching the position of the query. + + +Suggestions +----------- + +The ``sug`` Nimsuggest command performs a query about possible +completion symbols at some point in the file. + +The typical usage scenario for this option is to call it after the +user has typed the dot character for `the object oriented call +syntax <tut2.html#method-call-syntax>`_. Nimsuggest will try to return +the suggestions sorted first by scope (from innermost to outermost) +and then by item name. + + +Invocation context +------------------ + +The ``con`` Nimsuggest command is very similar to the suggestions +command, but instead of being used after the user has typed a dot +character, this one is meant to be used after the user has typed +an opening brace to start typing parameters. + + +Symbol usages +------------- + +The ``use`` Nimsuggest command lists all usages of the symbol at +a position. IDEs can use this to find all the places in the file +where the symbol is used and offer the user to rename it in all +places at the same time. + +For this kind of query the IDE will most likely ignore all the +type/signature info provided by Nimsuggest and concentrate on the +filename, line and column position of the multiple returned answers. + + + +Parsing nimsuggest output +========================= + +Nimsuggest output is always returned on single lines separated by +tab characters (``\t``). The values of each column are: + +1. Three characters indicating the type of returned answer (e.g. + ``def`` for definition, ``sug`` for suggestion, etc). +2. Type of the symbol. This can be ``skProc``, ``skLet``, and just + about any of the enums defined in the module ``compiler/ast.nim``. +3. Full qualitifed path of the symbol. If you are querying a symbol + defined in the ``proj.nim`` file, this would have the form + ``proj.symbolName``. +4. Type/signature. For variables and enums this will contain the + type of the symbol, for procs, methods and templates this will + contain the full unique signature (e.g. ``proc (File)``). +5. Full path to the file containing the symbol. +6. Line where the symbol is located in the file. Lines start to + count at **1**. +7. Column where the symbol is located in the file. Columns start + to count at **1**. +8. Docstring for the symbol if available or the empty string. To + differentiate the docstring from end of answer, + the docstring is always provided enclosed in double quotes, and + if the docstring spans multiple lines, all following lines of the + docstring will start with a blank space to align visually with + the starting quote. + + Also, you won't find raw ``\n`` characters breaking the one + answer per line format. Instead you will need to parse sequences + in the form ``\xHH``, where *HH* is a hexadecimal value (e.g. + newlines generate the sequence ``\x0A``). diff --git a/koch.nim b/koch.nim index 142aa89f1..55019b544 100644 --- a/koch.nim +++ b/koch.nim @@ -121,8 +121,8 @@ proc nsis(args: string) = buildTool("tools/niminst/niminst", args) #buildTool("tools/nimgrep", args) # produce 'nim_debug.exe': - exec "nim c compiler" / "nim.nim" - copyExe("compiler/nim".exe, "bin/nim_debug".exe) + #exec "nim c compiler" / "nim.nim" + #copyExe("compiler/nim".exe, "bin/nim_debug".exe) exec(("tools" / "niminst" / "niminst --var:version=$# --var:mingw=mingw$#" & " nsis compiler/installer.ini") % [VersionAsString, $(sizeof(pointer)*8)]) diff --git a/web/documentation.txt b/web/documentation.txt index dbb737cd9..145a6e827 100644 --- a/web/documentation.txt +++ b/web/documentation.txt @@ -8,13 +8,13 @@ Nim's Documentation .. container:: libraries - - | `Standard Library <lib.html>`_ + - | `Standard Library <0.11.0/lib.html>`_ | This document describes Nim's standard library. - - | `Language Manual <manual.html>`_ + - | `Language Manual <0.11.0/manual.html>`_ | The Nim manual is a draft that will evolve into a proper specification. - - | `Compiler User Guide <nimc.html>`_ + - | `Compiler User Guide <0.11.0/nimc.html>`_ | The user guide lists command line arguments, special features of the compiler, etc. @@ -26,11 +26,11 @@ Nim's Documentation .. container:: tools - - | `Source Code Filters <filters.html>`_ + - | `Source Code Filters <0.11.0/filters.html>`_ | The Nim compiler supports source code filters as a simple yet powerful builtin templating system. - - | `Tools Documentation <tools.html>`_ + - | `Tools Documentation <0.11.0/tools.html>`_ | Description of some tools that come with the standard distribution. @@ -41,16 +41,17 @@ Nim's Documentation .. container:: internals - - | `Garbage Collector <gc.html>`_ + - | `Garbage Collector <0.11.0/gc.html>`_ | Additional documentation about Nim's GC and how to operate it in a realtime setting. - - | `Internal Documentation <intern.html>`_ - | The internal documentation describes how the compiler is implemented. Read - this if you want to hack the compiler. + - | `Internal Documentation <0.11.0/intern.html>`_ + | The internal documentation describes how the compiler is implemented. + Read this if you want to hack the compiler. Search Options -------------- -`Documentation Index <theindex.html>`_ - The generated index. **Index + (Ctrl+F) == Joy** +`Documentation Index <0.11.0/theindex.html>`_ - The generated +index. **Index + (Ctrl+F) == Joy** diff --git a/web/download.txt b/web/download.txt index 44f7c866a..c9bc202cd 100644 --- a/web/download.txt +++ b/web/download.txt @@ -24,8 +24,12 @@ This installation method is the preferred way for Linux, Mac OS X, and other Uni like systems. Binary packages may be provided later. -Download `nim-0.11.0.zip <download/nim-0.11.0.zip>`_, extract it and -follow these instructions: +Download one of these: + +* `nim-0.11.0.zip (28 MB) <download/nim-0.11.0.zip>`_ +* `nim-0.11.0.tar.xz (2.6MB) <download/nim-0.11.0.tar.xz>`_ + +Extract the file and follow these instructions: * sh build.sh * Add ``$your_install_dir/bin`` to your PATH. diff --git a/web/learn.txt b/web/learn.txt index 7a9600e57..a2df38cde 100644 --- a/web/learn.txt +++ b/web/learn.txt @@ -8,10 +8,10 @@ Learning Nim .. container:: tutorials - - | `Tutorial (part I) <tut1.html>`_ + - | `Tutorial (part I) <0.11.0/tut1.html>`_ | Learn the basics of Nim's types, variables, procedures, control flow, etc... - - | `Tutorial (part II) <tut2.html>`_ + - | `Tutorial (part II) <0.11.0/tut2.html>`_ | Learn Nim's more advanced features such as OOP, generics, macros, etc... @@ -52,5 +52,5 @@ Learning Nim Documentation ------------- -More examples of Nim code can be found in the `Nim Language Documentation <manual.html>`_. +More examples of Nim code can be found in the `Nim Language Documentation <0.11.0/manual.html>`_. diff --git a/web/news.txt b/web/news.txt index 3622f2161..7735f3cbf 100644 --- a/web/news.txt +++ b/web/news.txt @@ -30,7 +30,7 @@ summer 2015. What's left: * ``immediate`` templates and macros will be deprecated as these will soon be completely unnecessary, instead the ``typed`` or ``untyped`` metatypes can be used. -* The standard library needs cleanups and use the features we have for +* The standard library needs cleanups and should use the features we have for concurrency and parallelism. @@ -52,10 +52,11 @@ Changes affecting backwards compatibility doIt: echo str # Error: undeclared identifier: 'str' + This used to inject the ``str`` parameter into the scope of the body. Declare the ``doIt`` template as ``immediate, dirty`` to get the old behaviour. - Tuple field names are not ignored anymore, this caused too many problems - in practice so now the behaviour as it was for version 0.9.6: If field + in practice so now the behaviour is as it was for version 0.9.6: If field names exist for the tuple type, they are checked. - ``logging.level`` and ``logging.handlers`` are no longer exported. ``addHandler``, ``getHandlers``, ``setLogFilter`` and ``getLogFilter`` @@ -110,6 +111,9 @@ Needs to be replaced by something like this: iterator. A notable change might be that a pattern being matched at the beginning and end of a string, will result in an empty string being produced at the start and the end of the iterator. +- The compiler and nimsuggest now count columns starting with 1, not 0 for + consistency with the rest of the world. + Language Additions ------------------ diff --git a/web/website.ini b/web/website.ini index 6266f05bb..bb9f1b204 100644 --- a/web/website.ini +++ b/web/website.ini @@ -31,7 +31,7 @@ file: ticker.txt [Documentation] doc: "endb;intern;apis;lib;manual.txt;tut1;tut2;nimc;overview;filters" doc: "tools;niminst;nimgrep;gc;estp;idetools;docgen;koch;backends.txt" -doc: "nimfix.txt" +doc: "nimfix.txt;nimsuggest.txt" pdf: "manual.txt;lib;tut1;tut2;nimc;niminst;gc" srcdoc2: "system.nim" srcdoc2: "core/macros;pure/marshal;core/typeinfo;core/unsigned" @@ -49,7 +49,7 @@ srcdoc2: "pure/httpserver;pure/httpclient;pure/smtp;impure/ssl;pure/fsmonitor" srcdoc2: "pure/ropes;pure/unidecode/unidecode;pure/xmldom;pure/xmldomparser" srcdoc2: "pure/xmlparser;pure/htmlparser;pure/xmltree;pure/colors;pure/mimetypes" srcdoc2: "pure/json;pure/base64;pure/scgi;pure/redis;impure/graphics" -srcdoc2: "impure/rdstdin" +srcdoc2: "impure/rdstdin;impure/dialogs" srcdoc2: "pure/collections/tables;pure/collections/sets;pure/collections/lists" srcdoc2: "pure/collections/intsets;pure/collections/queues;pure/encodings" srcdoc2: "pure/events;pure/collections/sequtils;pure/cookies" @@ -60,7 +60,7 @@ srcdoc2: "packages/docutils/rst;packages/docutils/rstast" srcdoc2: "packages/docutils/rstgen;pure/logging;pure/asyncdispatch;pure/asyncnet" srcdoc2: "pure/rawsockets;pure/asynchttpserver;pure/net;pure/selectors;pure/future" srcdoc2: "pure/asyncfile" -srcdoc2: "pure/md5" +srcdoc2: "pure/md5;pure/rationals" srcdoc2: "posix/posix" srcdoc2: "pure/fenv" srcdoc2: "pure/basic2d;pure/basic3d" |