From a79b13fdeaae5d8bf29efd575b513995e035f41d Mon Sep 17 00:00:00 2001 From: Alexandre Terrasa Date: Wed, 22 Aug 2018 21:48:10 -0400 Subject: [PATCH 1/2] CLEAN READMES Signed-off-by: Alexandre Terrasa --- lib/actors/README.md | 72 --- lib/ai/README.md | 14 - lib/android/README.md | 164 ------- lib/app/README.md | 208 --------- lib/core/README.md | 46 -- lib/gamnit/README.md | 63 --- lib/geometry/README.md | 56 --- lib/github/README.md | 71 --- lib/ios/README.md | 33 -- lib/json/README.md | 239 ---------- lib/markdown/README.md | 33 -- lib/nitcorn/README.md | 89 ---- lib/nlp/README.md | 72 --- lib/popcorn/README.md | 855 ------------------------------------ lib/posix/README.md | 5 - lib/pthreads/README.md | 32 -- lib/sdl2/README.md | 13 - lib/serialization/README.md | 309 ------------- lib/vsm/README.md | 103 ----- 19 files changed, 2477 deletions(-) delete mode 100644 lib/actors/README.md delete mode 100644 lib/ai/README.md delete mode 100644 lib/android/README.md delete mode 100644 lib/app/README.md delete mode 100644 lib/core/README.md delete mode 100644 lib/gamnit/README.md delete mode 100644 lib/geometry/README.md delete mode 100644 lib/github/README.md delete mode 100644 lib/ios/README.md delete mode 100644 lib/json/README.md delete mode 100644 lib/markdown/README.md delete mode 100644 lib/nitcorn/README.md delete mode 100644 lib/nlp/README.md delete mode 100644 lib/popcorn/README.md delete mode 100644 lib/posix/README.md delete mode 100644 lib/pthreads/README.md delete mode 100644 lib/sdl2/README.md delete mode 100644 lib/serialization/README.md delete mode 100644 lib/vsm/README.md diff --git a/lib/actors/README.md b/lib/actors/README.md deleted file mode 100644 index f99f1aab0f..0000000000 --- a/lib/actors/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# Nit Actor Model - -This group introduces the `actors` module which contains the abstraction of a Nit Actor Model, -based on Celluloid (https://github.com/celluloid/celluloid). - -## What is an actor ? - -An actor is an entity which receives messages and does some kind of computation based on it. -An actor has a mailbox in which it receives its messages, and process them one at a time. - - -## `actor` annotation - -The `actors` module introduces the annotation `actor` which is to be used on classes. -This annotation transform a normal Nit class into an actor. - -In practice, it adds a new property `async` to the annotated class. -When using `async` on your annotated class, this means that you want your calls to be asynchronous, -executed by the actor. - -For instance, if you call `a.async.foo` and `foo` doesn't have a return value, it will send -a message to the mailbox of the actor attached to `a` which will process it asynchronously. - -On the other hand, if you call `a.async.bar` and `bar` returns an`Int`, it will still send -a message to the actor, but you'll get a `Future[Int]` to be able to retrieve the value. -When using `join` on the future, the calling thread will wait until the value of the future is set. - -## Managing actors - -When you annotate a class with `actor` and create an instance of it with `new`, the actor is not -automatically created (which means you can completely skip the use of the actors if you -don't need them for a specific program). - -The `async` added property is actually created lazily when you use it. - -Actors are not automatically garbage collected, but you have solutions to terminate them -if you need to. For this, you need to use the `async` property of your annotated class : - -* `async.terminate` sends a shutdown message to the actor telling him to stop, so he'll finish -processing every other messages in his mailbox before terminating properly. Every other messages sent -to this actor after he received the shutdown message won't be processed. -* `async.terminate_now` sends a shutdown message too, but this time it places it first, so -if the actor is processing one message now, the next one will be the shutdown message, discarding -every messages in its mailbox. -* `async.wait_termination` wait for the actor to terminate properly. This call is synchronous. -* `async.kill`. If you really need this actor to stop, without any regards of what he was doing -or in which state he'll leave the memory, you can with this call. it's synchronous but not really -blocking, since it's direcly canceling the native pthread associated to the actor. - -For now, there isn't any mecanism to recreate and actor after it was terminated. -Sending messages after terminating it results in unspecified behaviour. - -## Waiting for all actors to finish processing - -Let's imagine you create a whole bunch of actors and make them do things asynchronously from the main thread. -You don't want your program to exit right after giving work to your actors. -To prevent that, we added a mecanism that waits before all your actors finished all their messages -before quitting. - -It's materialized by the `active_actors` property added to `Sys` which is a `ReverseBlockingQueue`. -In short, the `is_empty` method on this list is blocking until the list is effectively empty. -When every actors finished working, and we're sure they won't even send another message to another -actor, `active_actors` is empty. - -You can use this property as a mean of synchronisation in some specific cases (for example if you're -using actors for fork/join parallelism instead of concurrency). - - -## Examples - -You can find example of differents small programs implemented with Nit actors in the `examples` -directory. For a really simple example, you can check `examples/simple`. diff --git a/lib/ai/README.md b/lib/ai/README.md deleted file mode 100644 index f9997e14cd..0000000000 --- a/lib/ai/README.md +++ /dev/null @@ -1,14 +0,0 @@ -Simple library for basic artificial intelligence algorithms - -This library provides some frameworks for basic algorithms used for artificial intelligence. -It offers simple generic classes to extends. - -Contents: - -* see `backtrack` -* see `search` - -See the `examples` subdirectory for examples: - -* `examples/queens.nit` -* `examples/puzzle.nit` diff --git a/lib/android/README.md b/lib/android/README.md deleted file mode 100644 index ffd961cc5d..0000000000 --- a/lib/android/README.md +++ /dev/null @@ -1,164 +0,0 @@ -Android platform support and APIs - -# Compilation for Android - -The compiler generates an APK file as the output when the `android` -module is imported by the compilation target. The path to the generated -file can be specified using the `-o` and `--dir` options. - -# Host system configuration - -To compile Android apps from a 64 bits GNU/Linux host you can reuse an existing Android Studio -installation or make a clean install with command line tools only. - -Note that this guide supports only 64 bits GNU/Linux hosts with support for a Java 8 JDK, -it may be possible to support other platforms with some tweaks. - -1. Install the required SDK packages using one of these two methods: - - a. Using Android Studio, open `Tools > Android > SDK Manager`, in the SDK Tools tab, - install "Android SDK Build-Tools", CMake and NDK. - - b. From the command line, run this script for a quick setup without Android Studio. - You will probably need to tweak it to you system or update the download URL - to the latest SDK tools from https://developer.android.com/studio/index.html#command-tools - - ~~~ - # Fetch and extract SDK tools - mkdir -p ~/Android/Sdk - cd ~/Android/Sdk - wget https://dl.google.com/android/repository/sdk-tools-linux-3859397.zip - unzip sdk-tools-linux-3859397.zip - - # Update tools - tools/bin/sdkmanager --update - - # Accept the licenses - tools/bin/sdkmanager --licenses - - # Install the basic build tools - tools/bin/sdkmanager "build-tools;27.0.0" ndk-bundle - ~~~ - -3. Set the environment variable ANDROID_HOME to the SDK installation directory, usually `~/Android/Sdk/`. - Use the following command to setup the variable for bash. - - ~~~ - echo "export ANDROID_HOME=~/Android/Sdk/" >> ~/.bashrc - ~~~ - -4. Install Java 8 JDK, on Debian/Ubuntu systems you can use the following command: - - ~~~ - sudo apt install openjdk-8-jdk - ~~~ - -# Configure the Android application - -The _app.nit_ framework and this project offers some services to -customize the generated Android application. - -## Annotations - -* All _app.nit_ annotations are applied to Android projects: - `app_name`, `app_namespace` and `app_version`. - - See: `../app/README.md` - -* Custom information can be added to the Android manifest file -using the annotations `android_manifest`, `android_manifest_application` -and `android_manifest_activity`. - - Example usage to specify an extra permission: - - ~~~ - android_manifest """""" - ~~~ - -* The API version target can be specified with `android_api_min`, -`android_api_max` and `android_api_target`. These take a single -integer as argument. They are applied in the Android manifest as -`minSdkVesion`, `targetSdkVersion` and `maxSdkVersion`. - - See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html - -* The annotation `android_activity` defines a Java class used as an - entry point to your application. As of now, this annotation should - only be used by low-level implementations of Nit on Android. - Its usefulness will be extended in the future to customize user applications. - -## Android implementation - -There is two core implementation for Nit apps on Android. -`android::nit_activity` is used by apps with standard windows and native UI controls. -`android::game` is used by, well, games and the game frameworks `mnit` and `gamnit`. - -Clients don't have to select the core implementation, it is imported by other relevant modules. -For example, a module importing `app::ui` and `android` will trigger the importation of `android::nit_activity`. - -## Lock app orientation - -Importing `android::landscape` or `android::portrait` locks the generated -application in the specified orientation. This can be useful for games and -other multimedia applications. - -## Resources and application icon - -Resources specific to the Android platform should be placed in an `android/` folder at the root of the project. -The folder should adopt the structure of a normal Android project, e.g., a custom XML resource file can be placed -at `android/res/values/color.xml` to be compiled with the Android application. - -The application icon should also be placed in the `android/` folder. -Place the classic bitmap version at `android/res/mipmap-hdpi/ic_launcher.png` (and others), -and the adaptive version at `android/res/mipmap-anydpi-v26/ic_launcher.xml`. -The Nit compiler detects these files and uses them as the application icon. - -Additional `android/` folders may be placed next to more specific Nit modules to change the Android resources -for application variants. The more specific resources will have priority over the project level `android/` files. - -# Compilation modes - -There are two compilation modes for the Android platform, debug and release. -Theses modes are also applied to the generated Android projects. -The compilation mode is specified as an argument to `nitc`, only -`--release` can be specified as debug is the default behavior. - -## Debug mode - -Debug mode enables compiling to an APK file without handling signing keys -and their password. The APK file can be installed to a local device with -USB debugging enabled, but it cannot be published on the Play Store. - -By default, `nitc` will compile Android applications in debug mode. - -## Release mode - -Building in release mode will use your private key to sign the -APK file, it can then be published on the Play Store. - -1. Have a keystore with a valid key to sign your APK file. - - To create a new keystore, avoid using the default values of `jarsigner` -as they change between versions of the Java SDK. You should instead use a -command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS` -with the desired values. - - ~~~ - keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000 - ~~~ - -2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and -optionally `TSA_SERVER`. These settings can be set in a startup script such as -`~/.bashrc` or in a local Makefile. - - You can use the following commands by replacing the right-hand values -to your own configuration. - - ~~~ - export KEYSTORE=keystore_path - export KEY_ALIAS=key_alias - export TSA_SERVER=timestamp_authority_server_url # Optional - ~~~ - -3. Call `nitc` with the `--release` options. You will be prompted for the -required passwords as needed by `jarsigner`. diff --git a/lib/app/README.md b/lib/app/README.md deleted file mode 100644 index 4baecf4e75..0000000000 --- a/lib/app/README.md +++ /dev/null @@ -1,208 +0,0 @@ -_app.nit_, a framework for portable applications - -The framework provides services to manage common needs of modern mobile applications: - -* Life-cycle -* User interface -* Persistence -* Async HTTP requests -* Package metadata -* Compilation and packaging - -The features offered by _app.nit_ are common to all platforms, but -may not be available on all devices. - -# Application Life-Cycle - -The _app.nit_ application life-cycle is compatible with all target platforms. -It relies on the following sequence of events, represented here by their callback method name: - -1. `on_create`: The application is being created. - You should build the UI at this time and launch services. - -2. `on_resume`: The app enters the active state, it is in the foreground and interactive. - -3. `on_pause`: The app becomes inactive and it leaves the foreground. - It may still be visible in the background. - -4. `on_stop`: The app is completely hidden. - It may then be destroyed (without warning) or go back to the active state with `on_restart`. - -5. `on_restart`: The app goes back to the inactive state. - You can revert what was done by `on_stop`. - -![_app.nit_ life-cycle](doc/app-nit-lifecycle.png) - -Life-cycle events related to saving and restoring the application state are provided by two special callback methods: - -* `on_save_state`: The app may be destroyed soon, save its state for a future `on_restore_state`. - There is more on how it can be done in the `app::data_store` section. - -* `on_restore_state`: The app is launching, restore its state from a previous `on_save_state`. - -These events are synchronized to the native platforms applications -The `App` instance is the first to be notified of these events. -Other UI elements, from the `ui` submodule, are notified of the same events using a simple depth first visit. -So all UI elements can react separately to live-cycle events. - -# User Interface - -The `app::ui` module defines an abstract API to build a portable graphical application. -The API is composed of interactive `Control`s, visible `View`s and an active `Window`. - -Here is a subset of the most useful controls and views: - -* The classic pushable `Button` with text (usually rectangular). - -* `TextInput` is a field for the user to enter text. - -* `HorizontalLayout` and `VerticalLayout` organize other controls in order. - -Each control is notified of input events by callbacks to `on_event`. -All controls have observers that are also notified of the events. -So there is two ways to customize the behavior on a given event: - -* Create a subclass of the wanted `Control`, let's say `Button`, and specialize `on_event`. - -* Add an observer to a `Button` instance, and implement `on_event` in the observer. - -## Usage Example - -The example at `examples/ui_example.nit` shows off most features of `app::ui` in a minimal program. -You can also take a look at the calculator (`../../examples/calculator/src/calculator.nit`) which is a concrete usage example. - -## Platform-specific UI - -You can go beyond the portable UI API of _app.nit_ by using the natives services of a platform. - -The suggested approach is to use platform specific modules to customize the application on a precise platform. -See the calculator example for an adaptation of the UI on Android, -the interesting module is in this repository at ../../examples/calculator/src/android_calculator.nit - -# Persistent State with data\_store - -_app.nit_ offers the submodule `app::data_store` to easily save the application state and user preferences. -The service is accessible by the method `App::data_store`. The `DataStore` itself defines 2 methods: - -* `DataStore::[]=` saves and associates any serializable instances to a `String` key. -Pass `null` to clear the value associated to a key. - -* `DataStore::[]` returns the object associated to a `String` key. -It returns `null` if nothing is associated to the key. - -## Usage Example - -~~~ -import app::data_store - -redef class App - var user_name: String - - redef fun on_save_state - do - app.data_store["first run"] = false - app.data_store["user name"] = user_name - - super # call `on_save_state` on all attached instances of `AppComponent` - end - - redef fun on_restore_state - do - var first_run = app.data_store["first run"] - if first_run != true then - print "It's the first run of this application" - end - - var user_name = app.data_store["user name"] - if user_name isa String then - self.user_name = user_name - else self.user_name = "Undefined" - - super - end -end -~~~ - -# Async HTTP request - -The module `app::http_request` provides services to execute asynchronous HTTP request. -The class `AsyncHttpRequest` hides the complex parallel logic and -lets the user implement methods acting only on the UI thread. -See the documentation of `AsyncHttpRequest` for more information and -the full example at `examples/http_request_example.nit`. - -# Metadata annotations - -The _app.nit_ framework defines three annotations to customize the application package. - -* `app_name` takes a single argument, the visible name of the application. - This name is used for launchers and window title. - By default, the name of the target module. - -* `app_namespace` specifies the full namespace (or package name) of the application package. - This value usually identify the application uniquely on application stores. - It should not change once the application has benn published. - By default, the namespace is `org.nitlanguage.{module_name}`. - -* `app_version` specifies the version of the application package. - This annotation expects at least one argument, usually we use three version numbers: - the major, minor and revision. - The special function `git_revision` will use the prefix of the hash of the latest git commit. - By default, the version is 0.1. - -* `app_files` tells the compiler where to find platform specific resource files associated to a module. - By default, only the root of the project is searched for the folders `android` and `ios`. - The `android` folder is used as base for the generated Android project, - it can be used to specify the resource files, libs and even Java source files. - The `ios` folder is searched for icons only. - - Each argument of `app_files` is a relative path to a folder containing extra `android` or `ios` folders. - If there is no arguments, the parent folder of the annotated module is used. - In case of name conflicts in the resource files, the files from the project root have the lowest priority, - those associated to modules lower in the importation hierarchy have higher priority. - -## Usage Example - -~~~ -module my_module is - app_name "My App" - app_namespace "org.example.my_app" - app_version(1, 0, git_revision) -end -~~~ - -# Compiling and Packaging an Application - -The Nit compiler detects the target platform from the importations and generates the appropriate application format and package. - -Applications using only the portable services of _app.nit_ require some special care at compilation. -Such an application, let's say `calculator.nit`, does not depend on a specific platform and use the portable UI. -The target platform must be specified to the compiler for it to produce the correct application package. -There is two main ways to achieve this goal: - -* The mixin option (`-m module`) imports an additional module before compiling. - It can be used to load platform specific implementations of the _app.nit_ portable UI. - - ~~~ - # GNU/Linux version, using GTK - nitc calculator.nit -m linux - - # Android version - nitc calculator.nit -m android - - # iOS version - nitc calculator.nit -m ios - ~~~ - -* A common alternative for larger projects is to use platform specific modules. - Continuing with the calculator example, it is adapted for Android by the module `android_calculator.nit`. - This module imports both `calculator` and `android`, it can then use Android specific code. - - ~~~ - module android_calculator - - import calculator - import android - - # ... - ~~~ diff --git a/lib/core/README.md b/lib/core/README.md deleted file mode 100644 index 2501758b02..0000000000 --- a/lib/core/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Nit common library of core classes and methods - -Core classes and methods used by default by Nit programs and libraries. - -## Core Basic Types and Operations - -[[doc: kernel]] - -### Object - -[[doc: Object]] - -#### Equality - -[[doc: core::Object::==]] -[[doc: core::Object::!=]] -[[doc: core::Object::hash]] -[[doc: core::Object::is_same_instance]] -[[doc: core::Object::object_id]] - -#### Debuging - -[[doc: core::Object::output]] -[[doc: core::Object::output_class_name]] -[[doc: core::Object::is_same_type]] - -### Sys - -[[doc: Sys]] - -#### Program Execution - -[[doc: core::Sys::main]] -[[doc: core::Sys::run]] - -### Other - -[[defs: kernel]] - -## Core Collections - -[[doc: core::collection]] - -## String and Text manipulation - -[[doc: core::text]] diff --git a/lib/gamnit/README.md b/lib/gamnit/README.md deleted file mode 100644 index 68370d96bf..0000000000 --- a/lib/gamnit/README.md +++ /dev/null @@ -1,63 +0,0 @@ -Portable game and multimedia framework for Nit - -_gamnit_ is a modular framework to create portable 2D or 3D apps in Nit. -It is based on the portability framework _app.nit_ and the OpenGL ES 2.0 standard. - -# System configuration - -To compile the _gamnit_ apps packaged with the Nit repository on GNU/Linux you need to install the dev version of a few libraries and some tools. -On Debian 8.2, this command should install everything needed: - -~~~ -apt-get install libgles2-mesa-dev libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev inkscape -~~~ - -On Windows 64 bits, using msys2, you can install the required packages with: - -~~~ -pacman -S mingw-w64-x86_64-angleproject-git mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_image mingw-w64-x86_64-SDL2_mixer -~~~ - -While macOS isn't supported, it can create iOS apps. -You need to install and setup Xcode, and you may install the GLSL shader validation tool via `brew`: - -~~~ -brew install glslang -~~~ - -# Services by submodules - -_gamnit_ is modular, different services of the framework are available through different submodules: - -* The main entrypoint `gamnit` provides low-level abstractions over some services of OpenGL ES 2.0, like textures, shaders and programs. - It defines the basic methods to implement in order to obtain a working game: - `App::frame_core` to update the screen and `App::accept_event` to receive user inputs. - -* `flat` provides an easy to use API for 2D games based on sprites. - Clients of this API redefine `App::update` to update the game logic and fill lists of sprites with objects to draw. - - `App::sprites` lists the sprites of the game world, they are drawn form the point of view of the `world_camera`. - This camera can be moved around in the world by updating the x and y of its `position`, - and the zoom can easily be set using `reset_depth(desired_world_units_on_y)` or the `z` of its `position` - - `App::ui_sprites` lists the UI sprites drawn from the point of view of `ui_camera`. - By default, this camera is pixel-perfect with the origin in the top left corner of the window. - However to support screens with different DPI, it is recommended to standardize - the display size using `reset_depth(height_of_reference_display)`. - -* `depth` defines an API for 3D games based on instances of `Actor`. - - This framework is build upon `flat`, see the doc of this submodule first (just above). - As such, clients should still implement `update` with the game logic, and fill `ui_sprites` for UI elements. - - At each frame, elements in the list `actors` are drawn to screen. - Each `Actor` is composed of a `Model` and other information specific to this instance: - position in the world, rotation and scaling. - -* `limit_fps` refines existing services of _gamnit_ to limit the framerate to a customizable value. - -* `keys` provides `app.pressed_keys` keeping track of the currently pressed keys. - -* `model_parsers` provides services to read and parse models from the asset folder. - -* `network` provides a simple communication framework for multiplayer client/server games. diff --git a/lib/geometry/README.md b/lib/geometry/README.md deleted file mode 100644 index 3e20f59775..0000000000 --- a/lib/geometry/README.md +++ /dev/null @@ -1,56 +0,0 @@ -Basic geometry data structures and services. - -# Points and Lines - -The very basics of geometry needs, for two and three-dimensional space. - -# Boxes and detection collision - -Boxes module introduces Bounding boxes for Points and Lines and services to detect collision or inclusion between boxes. -It means a simple and fast way to test collision but not really accurate since it uses bounding boxes. - -# Quadtrees - -A QuadTree is a tree data structure in which each internal node has exactly four children -They're most often used to partition two-dimensional space by recursively subdividing -it into four quadrants or regions. - -* They decompose space into adaptable cells -* Each cell has a maximum capacity. When maximum is reached, the cell splits. - -Quadtrees are using Boxed objects to determine their distribution in the 2D space. - -This API provides two different types of Quadtree : Static and Dynamic (respectively `SQuadTree` and `DQuadTree`). - -* Static: When you create the QuadTree, you need to specify the region that it will cover - -* Dynamic: You just need to fill the quadtree with objects, and when the threshold is reached, -it will automatically divide the current region, depending on the distribution of objects already in the region. - -# Polygons - -Some basic polygon services. - -This module contains interesting algorithms for `ConvexPolygon`only at the moment. A Convex polygon can be defined as follow : - -* All its interior angles are less than 180°. this means that all the vertices of the polygon -will point outwards, away from the interior of the shape. - -* Every point on every line segment between two points inside or on the boundary of the polygon -remains inside or on the boundary. - -* The polygon is entirely contained in a closed half-plane defined by each of its edges. - -* For each edge, the interior points are all on the same side of the line that the edge defines. - -* The angle at each vertex contains all other vertices in its edges and interior. - -A polygon which is not convex is called concave. Convex polygon are used because most -geometric problems are simpler and faster on convex objects than on non-convex ones. - -Services provided : - -* Point in convex polygon -* Intersection of convex polygon -* Convex hull of a set of points -* Triangulation of polygon diff --git a/lib/github/README.md b/lib/github/README.md deleted file mode 100644 index 18814ee4da..0000000000 --- a/lib/github/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# Nit wrapper for Github API - -This module provides a Nit object oriented interface to access the Github api. - -## Accessing the API - -[[doc: GithubAPI]] - -### Authentification - -[[doc: auth]] - -Token can also be recovered from user config with `get_github_oauth`. - -[[doc: get_github_oauth]] - -### Retrieving user data - -[[doc: load_user]] -[[doc: User]] -[[defs: User]] - -### Retrieving repo data - -[[doc: load_repo]] -[[doc: Repo]] -[[defs: Repo]] - -### Other data - -[[defs: github::api]] - -### Advanced uses - -#### Caching - -[[doc: cache]] - -#### Custom requests - -[[doc: github::GithubAPI::get]] - -#### Change the user agent - -[[doc: github::GithubAPI::user_agent]] - -#### Debugging - -[[doc: verbose_lvl]] - -#### Using with GitLab - -If URL scheme of GitLab API follows the one of Github API, it may be possible to -configure this wrapper to use a custom URL. - -[[doc: api_url]] - -## Creating hooks - -Using this API you can create Github hooks able to respond to actions performed -on a repository. - -[[doc: hooks]] - -## Dealing with events - -GithubAPI can trigger different events depending on the hook configuration. - -[[doc: GithubEvent]] - -[[defs: github::events]] diff --git a/lib/ios/README.md b/lib/ios/README.md deleted file mode 100644 index e4f7cfe2d7..0000000000 --- a/lib/ios/README.md +++ /dev/null @@ -1,33 +0,0 @@ -iOS support for _app.nit_ - -# System configuration - -Configure your system for OS X by installing Xcode and brew. -Follow the instructions in `README.md` at the root of the repository. - -Optionally, install ios-sim to run compiled apps in the simulator: `brew install ios-sim` - -# Compile and run a simple application - -Let's use the `hello_ios` example in the folder `lib/ios/examples/`. - -Compile with: `nitc hello_world.nit` - -Run in the simulator with: `ios-sim hello_world.app` - -# Sample portable applications - -See the calculator example at `examples/calculator` and the Tnitter client at `contrib/tnitter/` -for portable applications working on GNU/Linux, OS X, iOS and Android. - -# Application icon - -To associate icons to your application, create the directory `ios/AppIcon.appiconset` and fill it with standard icons and `Contents.json`. -These files can be generated in a number of different ways: - -* Using the tool `svg_to_icons` packaged with the Nit repository at `contrib/inkscape_tools/bin/svg_to_icons`. - -* Using Xcode to assign images to each slot, create the folder and the file `Contents.json`. - -* Write or modify the file `Contents.json` manually. - It is in Json format and easily readable. diff --git a/lib/json/README.md b/lib/json/README.md deleted file mode 100644 index 94539c3e0e..0000000000 --- a/lib/json/README.md +++ /dev/null @@ -1,239 +0,0 @@ -read and write JSON formatted text - -These services can be useful to communicate with a remote server or client, -save data locally or even debug and understand the structure of a Nit object. -There is a single API to write JSON, and three API to read depending on the use case. - -# Write JSON - -Writing Nit objects to JSON format can be useful to communicate with a remote service, -save data locally or even debug and understand the structure of an object. -There is two related services to write JSON object, the method -`serialize_to_json` and the object `JsonSerializer`. -The method `serialize_to_json` is actually a shortcut to `JsonSerializer`, both -share the same features. - -## Write plain JSON - -Passing the argument `plain=true` to `serialize_to_json` generates plain and clean JSON. -This format is non-Nit program, it cannot be fully deserialized back to Nit objects. -The argument `pretty=true` generates JSON for humans, with more spaces and line breaks. - -The Nit objects to write must subclass `Serializable` and implement its services. -Most classes from the `core` library are already supported, including collections, numeric values, etc. -For your local objects, you can annotate them with `serialize` to automate subclassing -`Serializable` and the implementation of its services. - -### Example - -~~~ -class Person - serialize - - var name: String - var year_of_birth: Int - var next_of_kin: nullable Person -end - -var bob = new Person("Bob", 1986) -assert bob.serialize_to_json(pretty=true, plain=true) == """ -{ - "name": "Bob", - "year_of_birth": 1986, - "next_of_kin": null -}""" - -var alice = new Person("Alice", 1978, bob) -assert alice.serialize_to_json(pretty=true, plain=true) == """ -{ - "name": "Alice", - "year_of_birth": 1978, - "next_of_kin": { - "name": "Bob", - "year_of_birth": 1986, - "next_of_kin": null - } -}""" - -# You can also build JSON objects as a `Map` -var charlie = new Map[String, nullable Serializable] -charlie["name"] = "Charlie" -charlie["year_of_birth"] = 1968 -charlie["next_of_kin"] = alice -assert charlie.serialize_to_json(pretty=true, plain=true) == """ -{ - "name": "Charlie", - "year_of_birth": 1968, - "next_of_kin": { - "name": "Alice", - "year_of_birth": 1978, - "next_of_kin": { - "name": "Bob", - "year_of_birth": 1986, - "next_of_kin": null - } - } -}""" -~~~ - -## Write JSON with metadata - -By default, `serialize_to_json` and `JsonSerializer` include metadate in the generated JSON. -This metadata is used by `JsonDeserializer` when reading the JSON code to recreate -the Nit object with the exact original type. -The metadata allows to avoid repeating an object and its resolves cycles in the serialized objects. - -For more information on Nit serialization, see: ../serialization/README.md - - -# Read JSON - -There are a total of 3 API to read JSON: -* `JsonDeserializer` reads JSON to recreate complex Nit objects (discussed here), -* the module `json::dynamic` provides an easy API to explore JSON objects, -* the module `json::static` offers a low-level service to parse JSON and create basic Nit objects. - -The class `JsonDeserializer` reads JSON code to recreate objects. -It can use the metadata in the JSON code, to recreate precise Nit objects. -Otherwise, JSON objects are recreated to simple Nit types: `Map`, `Array`, etc. -Errors are reported to the attribute `JsonDeserializer::errors`. - -The type to recreate is either declared or inferred: - -1. The JSON object defines a `__class` key with the name of the Nit class as value. - This attribute is generated by the `JsonSerializer` with other metadata, - it can also be specified by other external tools. -2. A refinement of `JsonDeserializer::class_name_heuristic` identifies the Nit class. -3. If all else fails, `JsonDeserializer` uses the static type of the attribute, - or the type name passed to `deserialize`. - -The method `deserialize_json` is a shortcut to `JsonDeserializer` which prints -errors to the console. It is fit only for small scripts and other quick and dirty usage. - -### Example - -~~~ -class Triangle - serialize - - var corners = new Array[Point] - redef var to_s is serialize_as("name") -end - -class Point - serialize - - var x: Int - var y: Int -end - -# Metadata on each JSON object tells the deserializer what is its Nit type, -# and it supports special types such as generic collections. -var json_with_metadata = """{ - "__class": "Triangle", - "corners": {"__class": "Array[Point]", - "__items": [{"__class": "Point", "x": 0, "y": 0}, - {"__class": "Point", "x": 3, "y": 0}, - {"__class": "Point", "x": 2, "y": 2}]}, - "name": "some triangle" -}""" - -var deserializer = new JsonDeserializer(json_with_metadata) -var object = deserializer.deserialize -assert deserializer.errors.is_empty -assert object != null - -# However most non-Nit services won't add the metadata and instead produce plain JSON. -# Without a "__class", the deserializer relies on `class_name_heuristic` and the static type. -# The type of the root object to deserialize can be specified by an argument passed to `deserialize`. -var plain_json = """{ - "corners": [{"x": 0, "y": 0}, - {"x": 3, "y": 0}, - {"x": 2, "y": 2}], - "name": "the same triangle" -}""" - -deserializer = new JsonDeserializer(plain_json) -object = deserializer.deserialize("Triangle") -assert deserializer.errors.is_empty # If false, `object` is invalid -~~~ - -### Missing attributes and default values - -When reading JSON, some attributes expected by Nit classes may be missing. -The JSON object may come from an external API using optional attributes or -from a previous version of your program without the attributes. -When an attribute is not found, the deserialization engine acts in one of three ways: - -1. If the attribute has a default value or if it is annotated by `lazy`, - the engine leave the attribute to the default value. No error is raised. -2. If the static type of the attribute is nullable, the engine sets - the attribute to `null`. No error is raised. -3. Otherwise, the engine raises an error and does not set the attribute. - The caller must check for `errors` and must not read from the attribute. - -~~~ -class MyConfig - serialize - - var width: Int # Must be in JSON or an error is raised - var height = 4 - var volume_level = 8 is lazy - var player_name: nullable String - var tmp_dir: nullable String = "/tmp" is lazy -end - -# --- -# JSON object with all expected attributes -> OK -var plain_json = """ -{ - "width": 11, - "height": 22, - "volume_level": 33, - "player_name": "Alice", - "tmp_dir": null -}""" -var deserializer = new JsonDeserializer(plain_json) -var obj = deserializer.deserialize("MyConfig") - -assert deserializer.errors.is_empty -assert obj isa MyConfig -assert obj.width == 11 -assert obj.height == 22 -assert obj.volume_level == 33 -assert obj.player_name == "Alice" -assert obj.tmp_dir == null - -# --- -# JSON object missing optional attributes -> OK -plain_json = """ -{ - "width": 11 -}""" -deserializer = new JsonDeserializer(plain_json) -obj = deserializer.deserialize("MyConfig") - -assert deserializer.errors.is_empty -assert obj isa MyConfig -assert obj.width == 11 -assert obj.height == 4 -assert obj.volume_level == 8 -assert obj.player_name == null -assert obj.tmp_dir == "/tmp" - -# --- -# JSON object missing the mandatory attribute -> Error -plain_json = """ -{ - "player_name": "Bob", -}""" -deserializer = new JsonDeserializer(plain_json) -obj = deserializer.deserialize("MyConfig") - -# There's an error, `obj` is partial -assert deserializer.errors.length == 1 - -# Still, we can access valid attributes -assert obj isa MyConfig -assert obj.player_name == "Bob" -~~~ diff --git a/lib/markdown/README.md b/lib/markdown/README.md deleted file mode 100644 index 7068bb0b49..0000000000 --- a/lib/markdown/README.md +++ /dev/null @@ -1,33 +0,0 @@ -A markdown parser for Nit. - -Markdown documentation can be found in http://daringfireball.net/projects/markdown/. -This parser is inspired by the famous TxtMark for Java (https://github.com/rjeschke/txtmark). - -## Usage - -`nitmd` can be used as a standalone tool: - -~~~bash -$ nitmd file.md -~~~ - -Or you can use it programmatically by importing the `markdown` module. - -## Differences with Markdown specification - -This parser passes all tests inside http://daringfireball.net/projects/downloads/MarkdownTest_1.0_2007-05-09.tgz execpt of two: - -1. Images.text: fails because this parser doesn't produce empty 'title' image attributes. -2. Literal quotes in titles.text: because markdown accepts unescaped quotes in titles and this is wrong. - -## Testing - -The NitUnit test suite can be found in `test_markdown.nit`. - -Minimalists tests are prefixed with `process_*`. All tests from daringfireball are prefixed with `process_daring*`. - -Run the test suite: - -~~~bash -$ nitunit lib/markdown/markdown.nit -t lib/markdown/test_markdown.nit -~~~ diff --git a/lib/nitcorn/README.md b/lib/nitcorn/README.md deleted file mode 100644 index 2db66b894a..0000000000 --- a/lib/nitcorn/README.md +++ /dev/null @@ -1,89 +0,0 @@ -Lightweight framework for Web applications development - -# Features - -Dynamic content is served by subclassing `Action` and implementing `answer`. -This method receives an `HttpRequest` and must return an `HttpResponse`. -_nitcorn_ provides `FileServer`, a simple `Action` to serve static files. - -`HttpRequest` contains the GET and POST arguments as well as session data it one exists. -The produced `HttpResponse` should contain the HTTP status code, the body, -session data to preserve or create a session, and optionally list files to append. - -Each `Action` may be associated to many instances of `Route`. -These routes can simply identify the root of a service, -but also define parameters within the URI. - -_nitcorn_ instances are configured dynamically in Nit code with the interfaces and routes created as needed. - -_nitcorn_ plays well with other Nit services and tools such as `serialization`, `mongodb`, `sqlite` and `nitiwiki`. -It also benefits from the full power of the Nit language: -class refinement can be used to customize default services and merge many applications in a single server, -and the FFI enables calling services in different languages. - -# Examples - -A minimal example follows with a custom `Action` and using `FileServer`. - -More general examples are available at `lib/nitcorn/examples/`. -For an example of a larger project merging many _nitcorn_ applications into one server, -take a look at the configuration of `http://xymus.net/` at `../contrib/xymus_net/xymus_net.nit`. - -Larger projects using _nitcorn_ can be found in the `contrib/` folder: -* _opportunity_ is a meetup planner heavily based on _nitcorn_. -* _tnitter_ is a micro-blogging platform with a simple Web and RESTful interface. -* _benitlux_ uses a custom `Action` to subscribe people to a mailing list and define a RESTful interface. - -## Simple hello world server - -~~~ -import nitcorn - -# Simple Action to display the Hello World page and the get arguments -class HelloWorldAction - super Action - - redef fun answer(http_request, turi) - do - var title = "Hello World!" - var args = http_request.get_args.join(",", ":") - - var response = new HttpResponse(200) - response.body = """ - - - - - {{{title}}} - - -

{{{title}}}

-

GET args: {{{args}}}

- -""" - return response - end -end - -# Listen on `localhost:8080` -var vh = new VirtualHost("localhost:8080") - -# Serve `http://localhost:8080/hello.html` with our custom action -vh.routes.add new Route("/hello.html", new HelloWorldAction) - -# Serve everything else under `http://localhost:8080/` using a `FileServer` with a root at "/var/www/" -vh.routes.add new Route(null, new FileServer("/var/www/")) - -# Launch server -var factory = new HttpFactory.and_libevent -factory.config.virtual_hosts.add vh -factory.run -~~~ - -# Credits - -This nitcorn library is a fork from an independent project originally created in 2013 by -Jean-Philippe Caissy, Guillaume Auger, Frederic Sevillano, Justin Michaud-Ouellette, -Stephan Michaud and Maxime Bélanger. - -It has been adapted to a library, and is currently maintained, by Alexis Laferrière. diff --git a/lib/nlp/README.md b/lib/nlp/README.md deleted file mode 100644 index 3ed2c5ead5..0000000000 --- a/lib/nlp/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# Nit wrapper for Stanford CoreNLP - -Stanford CoreNLP provides a set of natural language analysis tools which can take -raw text input and give the base forms of words, their parts of speech, whether -they are names of companies, people, etc., normalize dates, times, and numeric -quantities, and mark up the structure of sentences in terms of phrases and word -dependencies, indicate which noun phrases refer to the same entities, indicate -sentiment, etc. - -This wrapper needs the Stanford CoreNLP jars that run on Java 1.8+. - -See http://nlp.stanford.edu/software/corenlp.shtml. - -## NLPProcessor - -### Java client - -~~~nitish -var proc = new NLPProcessor("path/to/StanfordCoreNLP/jars") - -var doc = proc.process("String to analyze") - -for sentence in doc.sentences do - for token in sentence.tokens do - print "{token.lemma}: {token.pos}" - end -end -~~~ - -### NLPServer - -The NLPServer provides a wrapper around the StanfordCoreNLPServer. - -See `https://stanfordnlp.github.io/CoreNLP/corenlp-server.html`. - -~~~nitish -var cp = "/path/to/StanfordCoreNLP/jars" -var srv = new NLPServer(cp, 9000) -srv.start -~~~ - -### NLPClient - -The NLPClient is used as a NLPProcessor with a NLPServer backend. - -~~~nitish -var cli = new NLPClient("http://localhost:9000") -var doc = cli.process("String to analyze") -~~~ - -## NLPIndex - -NLPIndex extends the StringIndex to use a NLPProcessor to tokenize, lemmatize and -tag the terms of a document. - -~~~nitish -var index = new NLPIndex(proc) - -var d1 = index.index_string("Doc 1", "/uri/1", "this is a sample") -var d2 = index.index_string("Doc 2", "/uri/2", "this and this is another example") -assert index.documents.length == 2 - -matches = index.match_string("this sample") -assert matches.first.document == d1 -~~~ - -## TODO - -* Use JWrapper -* Use options to choose CoreNLP analyzers -* Analyze sentences dependencies -* Analyze sentiment diff --git a/lib/popcorn/README.md b/lib/popcorn/README.md deleted file mode 100644 index bbc9c95b0b..0000000000 --- a/lib/popcorn/README.md +++ /dev/null @@ -1,855 +0,0 @@ -# Popcorn - -**Why endure plain corn when you can pop it?!** - -Popcorn is a minimal yet powerful nit web application framework that provides cool -features for lazy developpers. - -Popcorn is built over nitcorn to provide a clean and user friendly interface -without all the boiler plate code. - -## What does it taste like? - -Set up is quick and easy as 10 lines of code. -Create a file `app.nit` and add the following code: - -~~~ -import popcorn - -class HelloHandler - super Handler - - redef fun get(req, res) do res.html "

Hello World!

" -end - -var app = new App -app.use("/", new HelloHandler) -app.listen("localhost", 3000) -~~~ - -The Popcorn app listens on port 3000 for connections. -The app responds with "Hello World!" for requests to the root URL (`/`) or **route**. -For every other path, it will respond with a **404 Not Found**. - -The `req` (request) and `res` (response) parameters are the same that nitcorn provides -so you can do anything else you would do in your route without Popcorn involved. - -Run the app with the following command: - -~~~bash -$ nitc app.nit && ./app -~~~ - -Then, load [http://localhost:3000](http://localhost:3000) in a browser to see the output. - -Here the output using the `curl` command: - -~~~bash -$ curl localhost:3000 -

Hello World!

- -$ curl localhost:3000/wrong_uri - - - - -Not Found - - -

404 Not Found

- - -~~~ - -This is why we love popcorn! - -## Basic routing - -**Routing** refers to determining how an application responds to a client request -to a particular endpoint, which is a URI (or path) and a specific HTTP request -method GET, POST, PUT or DELETE (other methods are not suported yet). - -Each route can have one or more handler methods, which are executed when the route is matched. - -Route handlers definition takes the following form: - -~~~nitish -import popcorn - -class MyHandler - super Handler - - redef fun METHOD(req, res) do end -end -~~~ - -Where: -* `MyHandler` is the name of the handler you will add to the app. -* `METHOD` can be replaced by `get`, `post`, `put` or `delete`. - -The following example responds to GET and POST requests: - -~~~ -import popcorn - -class MyHandler - super Handler - - redef fun get(req, res) do res.send "Got a GET request" - redef fun post(req, res) do res.send "Got a POST request" -end -~~~ - -To make your handler responds to a specific route, you have to add it to the app. - -Respond to POST request on the root route (`/`), the application's home page: - -~~~ -var app = new App -app.use("/", new MyHandler) -~~~ - -Respond to a request to the `/user` route: - -~~~ -app.use("/user", new MyHandler) -~~~ - -For more details about routing, see the routing section. - -## Serving static files with Popcorn - -To serve static files such as images, CSS files, and JavaScript files, use the -Popcorn built-in handler `StaticHandler`. - -Pass the name of the directory that contains the static assets to the StaticHandler -init method to start serving the files directly. -For example, use the following code to serve images, CSS files, and JavaScript files -in a directory named `public`: - -~~~ -app.use("/", new StaticHandler("public/")) -~~~ - -Now, you can load the files that are in the `public` directory: - -~~~raw -http://localhost:3000/images/trollface.jpg -http://localhost:3000/css/style.css -http://localhost:3000/js/app.js -http://localhost:3000/hello.html -~~~ - -Popcorn looks up the files relative to the static directory, so the name of the -static directory is not part of the URL. -To use multiple static assets directories, add the `StaticHandler` multiple times: - -~~~ -app.use("/", new StaticHandler("public/")) -app.use("/", new StaticHandler("files/")) -~~~ - -Popcorn looks up the files in the order in which you set the static directories -with the `use` method. - -To create a virtual path prefix (where the path does not actually exist in the file system) -for files that are served by the `StaticHandler`, specify a mount path for the -static directory, as shown below: - -~~~ -app.use("/static/", new StaticHandler("public/")) -~~~ - -Now, you can load the files that are in the public directory from the `/static` -path prefix. - -~~~raw -http://localhost:3000/static/images/trollface.jpg -http://localhost:3000/static/css/style.css -http://localhost:3000/static/js/app.js -http://localhost:3000/static/hello.html -~~~ - -However, the path that you provide to the `StaticHandler` is relative to the -directory from where you launch your app. -If you run the app from another directory, it’s safer to use the absolute path of -the directory that you want to serve. - -In some cases, you can want to redirect request to static files to a default file -instead of returning a 404 error. -This can be achieved by specifying a default file in the StaticHandler: - -~~~ -app.use("/static/", new StaticHandler("public/", "default.html")) -~~~ - -This way all non-matched queries to the StaticHandler will be answered with the -`default.html` file. - -## Advanced Routing - -**Routing** refers to the definition of application end points (URIs) and how -they respond to client requests. For an introduction to routing, see the Basic routing -section. - -The following code is an example of a very basic route. - -~~~ -import popcorn - -class HelloHandler - super Handler - - redef fun get(req, res) do res.send "Hello World!" -end - -var app = new App -app.use("/", new HelloHandler) -~~~ - -### Route methods - -A **route method** is derived from one of the HTTP methods, and is attached to an -instance of the Handler class. - -The following code is an example of routes that are defined for the GET and the POST -methods to the root of the app. - -~~~ -import popcorn - -class GetPostHandler - super Handler - - redef fun get(req, res) do res.send "GET request to the homepage" - redef fun post(req, res) do res.send "POST request to the homepage" -end - -var app = new App -app.use("/", new GetPostHandler) -~~~ - -Popcorn supports the following routing methods that correspond to HTTP methods: -get, post, put, and delete. - -The request query string is accessed through the `req` parameter: - -~~~ -import popcorn -import template - -class QueryStringHandler - super Handler - - redef fun get(req, res) do - var tpl = new Template - tpl.addn "URI: {req.uri}" - tpl.addn "Query string: {req.query_string}" - for name, arg in req.get_args do - tpl.addn "{name}: {arg}" - end - res.send tpl - end -end - -var app = new App -app.use("/", new QueryStringHandler) -app.listen("localhost", 3000) -~~~ - -Post parameters can also be accessed through the `req` parameter: - -~~~ -import popcorn -import template - -class PostHandler - super Handler - - redef fun post(req, res) do - var tpl = new Template - tpl.addn "URI: {req.uri}" - tpl.addn "Body: {req.body}" - for name, arg in req.post_args do - tpl.addn "{name}: {arg}" - end - res.send tpl - end -end - -var app = new App -app.use("/", new PostHandler) -app.listen("localhost", 3000) -~~~ - -There is a special routing method, `all(res, req)`, which is not derived from any -HTTP method. This method is used to respond at a path for all request methods. - -In the following example, the handler will be executed for requests to "/user" -whether you are using GET, POST, PUT, DELETE, or any other HTTP request method. - -~~~ -import popcorn - -class AllHandler - super Handler - - redef fun all(req, res) do res.send "Every request to the homepage" -end -~~~ - -Using the `all` method you can also implement other HTTP request methods. - -~~~ -import popcorn - -class MergeHandler - super Handler - - redef fun all(req, res) do - if req.method == "MERGE" then - # handle that method - else super # keep handle GET, POST, PUT and DELETE methods - end -end -~~~ - -### Route paths - -**Route paths**, in combination with a request handlers, define the endpoints at -which requests can be made. -Route paths can be strings, parameterized strings or glob patterns. -Query strings such as `?q=foo`are not part of the route path. - -Popcorn uses the `Handler::match(uri)` method to match the route paths. - -Here are some examples of route paths based on strings. - -This route path will match requests to the root route, `/`. - -~~~ -import popcorn - -class MyHandler - super Handler - - redef fun get(req, res) do res.send "Got a GET request" -end - -var app = new App -app.use("/", new MyHandler) -~~~ - -This route path will match requests to `/about`. - -~~~ -app.use("/about", new MyHandler) -~~~ - -This route path will match requests to `/random.text`. - -~~~ -app.use("/random.text", new MyHandler) -~~~ - -During the query/response process, routes are matched by order of declaration -through the `App::use` method. - -The app declared in this example will try to match the routes in this order: - -1. `/` -2. `/about` -3. `/random.text` - -### Route parameters - -**Route parameters** are variable parts of a route path. They can be used to path -arguments within the URI. -Parameters in a route are prefixed with a colon `:` like in `:userId`, `:year`. - -The following example declares a handler `UserHome` that responds with the `user` -name. - -~~~ -import popcorn - -class UserHome - super Handler - - redef fun get(req, res) do - var user = req.param("user") - if user != null then - res.send "Hello {user}" - else - res.send("Nothing received", 400) - end - end -end - -var app = new App -app.use("/:user", new UserHome) -app.listen("localhost", 3000) -~~~ - -The `UserHome` handler listen to every path matching `/:user`. This can be `/Morriar`, -`/10`, ... but not `/Morriar/profile` since route follow the strict matching rule. - -### Glob routes - -**Glob routes** are routes that match only on a prefix, thus accepting a wider range -of URI. -Glob routes end with the symbol `*`. - -Here we define a `UserItem` handler that will respond to any URI matching the prefix -`/user/:user/item/:item`. -Note that glob route are compatible with route parameters. - -~~~ -import popcorn - -class UserItem - super Handler - - redef fun get(req, res) do - var user = req.param("user") - var item = req.param("item") - if user == null or item == null then - res.send("Nothing received", 400) - else - res.send "Here the item {item} of the use {user}." - end - end -end - -var app = new App -app.use("/user/:user/item/:item/*", new UserItem) -app.listen("localhost", 3000) -~~~ - -## Response methods - -The methods on the response object (`res`), can is used to manipulate the -request-response cycle. -If none of these methods are called from a route handler, the client request will -receive a `404 Not found` error. - -* `res.html()` Send a HTML response. -* `res.json()` Send a JSON response. -* `res.redirect()` Redirect a request. -* `res.send()` Send a response of various types. -* `res.error()` Set the response status code and send its message as the response body. - -## Response cycle - -When the popcorn `App` receives a request, the response cycle is the following: - -1. `pre-middlewares` lookup matching middlewares registered with `use_before(pre_middleware)`: - 1. execute matching middleware by registration order - 2. if a middleware send a response then let the `pre-middlewares` loop continue - with the next middleware -2. `response-handlers` lookup matching handlers registered with `use(handler)`: - 1. execute matching middleware by registration order - 2. if a middleware send a response then stop the `response-handlers` loop - 3. if no hander matches or sends a response, generate a 404 response -3. `post-middlewares` lookup matching handlers registered with `use_after(post_handler)`: - 1. execute matching middleware by registration order - 2. if a middleware send a response then let the `post-middlewares` loop continue - with the next middleware - -## Middlewares - -### Overview - -**Middleware** handlers are handlers that typically do not send `HttpResponse` responses. -Middleware handlers can perform the following tasks: - -* Execute any code. -* Make changes to the request and the response objects. -* End its action and pass to the next handler in the stack. - -If a middleware handler makes a call to `res.send()`, it provoques the end the -request-response cycle and the response is sent to the client. - -### Ultra simple logger example - -Here is an example of a simple “Hello World” Popcorn application. -We add a middleware handler to the application called MyLogger that prints a simple -log message in the app stdout. - -~~~ -import popcorn - -class MyLogger - super Handler - - redef fun all(req, res) do print "Request Logged!" -end - -class HelloHandler - super Handler - - redef fun get(req, res) do res.send "Hello World!" -end - - -var app = new App -app.use_before("/*", new MyLogger) -app.use("/", new HelloHandler) -app.listen("localhost", 3000) -~~~ - -By using the `MyLogger` handler to the route `/*` we ensure that every requests -(even 404 ones) pass through the middleware handler. -This handler just prints “Request Logged!” when a request is received. - -Be default, the order of middleware execution is that are loaded first are also executed first. -To ensure our middleware `MyLogger` will be executed before all the other, we add it -with the `use_before` method. - -### Ultra cool, more advanced logger example - -Next, we’ll create a middleware handler called “LogHandler” that prints the requested -uri, the response status and the time it took to Popcorn to process the request. - -This example gives a simplified version of the `RequestClock` and `ConsoleLog` middlewares. - -~~~ -import popcorn -import realtime - -redef class HttpRequest - # Time that request was received by the Popcorn app. - var timer: nullable Clock = null -end - -class RequestTimeHandler - super Handler - - redef fun all(req, res) do req.timer = new Clock -end - -class LogHandler - super Handler - - redef fun all(req, res) do - var timer = req.timer - if timer != null then - print "{req.method} {req.uri} {res.color_status} ({timer.total}s)" - else - print "{req.method} {req.uri} {res.color_status}" - end - end -end - -class HelloHandler - super Handler - - redef fun get(req, res) do res.send "Hello World!" -end - -var app = new App -app.use_before("/*", new RequestTimeHandler) -app.use("/", new HelloHandler) -app.use_after("/*", new LogHandler) -app.listen("localhost", 3000) -~~~ - -First, we attach a new attribute `timer` to every `HttpRequest`. -Doing so we can access our data from all handlers that import our module, directly -from the `req` parameter. - -We use the new middleware called `RequestTimeHandler` to initialize the request timer. -Because of the `use_before` method, the `RequestTimeHandler` middleware will be executed -before all the others. - -We then let the `HelloHandler` produce the response. - -Finally, our `LogHandler` will display a bunch of data and use the request `timer` -to display the time it took to process the request. -Because of the `use_after` method, the `LogHandler` middleware will be executed after -all the others. - -The app now uses the `RequestTimeHandler` middleware for every requests received -by the Popcorn app. -The page is processed the `HelloHandler` to display the index page. -And, before every response is sent, the `LogHandler` is activated to display the -log line. - -Because you have access to the request object, the response object, and all the -Popcorn API, the possibilities with middleware functions are endless. - -### Built-in middlewares - -Starting with version 0.1, Popcorn provide a set of built-in middleware that can -be used to develop your app faster. - -* `RequestClock`: initializes requests clock. -* `ConsoleLog`: displays resquest and response status in console (can be used with `RequestClock`). -* `SessionInit`: initializes requests session (see the `Sessions` section). -* `StaticServer`: serves static files (see the `Serving static files with Popcorn` section). -* `Router`: a mountable mini-app (see the `Mountable routers` section). - -## Mountable routers - -Use the `Router` class to create modular, mountable route handlers. -A Router instance is a complete middleware and routing system; for this reason, -it is often referred to as a “mini-app”. - -The following example creates a router as a module, loads a middleware handler in it, -defines some routes, and mounts the router module on a path in the main app. - -~~~ -import popcorn - -class AppHome - super Handler - - redef fun get(req, res) do res.send "Site Home" -end - -class UserLogger - super Handler - - redef fun all(req, res) do print "User logged" -end - -class UserHome - super Handler - - redef fun get(req, res) do res.send "User Home" -end - -class UserProfile - super Handler - - redef fun get(req, res) do res.send "User Profile" -end - -var user_router = new Router -user_router.use("/*", new UserLogger) -user_router.use("/", new UserHome) -user_router.use("/profile", new UserProfile) - -var app = new App -app.use("/", new AppHome) -app.use("/user", user_router) -app.listen("localhost", 3000) -~~~ - -The app will now be able to handle requests to /user and /user/profile, as well -as call the `Time` middleware handler that is specific to the route. - -## Error handling - -**Error handling** is based on middleware handlers. - -Define error-handling middlewares in the same way as other middleware handlers: - -~~~ -import popcorn - -class SimpleErrorHandler - super Handler - - redef fun all(req, res) do - if res.status_code != 200 then - print "An error occurred! {res.status_code})" - end - end -end - -class HelloHandler - super Handler - - redef fun get(req, res) do res.send "Hello World!" -end - -var app = new App -app.use("/", new HelloHandler) -app.use("/*", new SimpleErrorHandler) -app.listen("localhost", 3000) -~~~ - -In this example, every non-200 response is caught by the `SimpleErrorHandler` -that print an error in stdout. - -By defining multiple middleware error handlers, you can take multiple action depending -on the kind of error or the kind of interface you provide (HTML, XML, JSON...). - -Here an example of the 404 custom error page in HTML: - -~~~ -import popcorn -import template - -class HtmlErrorTemplate - super Template - - var status: Int - var message: nullable String - - redef fun rendering do add """ - - - - - {{{message or else status}}} - - -

{{{status}}} {{{message or else ""}}}

- - """ -end - -class HtmlErrorHandler - super Handler - - redef fun all(req, res) do - if res.status_code != 200 then - res.send(new HtmlErrorTemplate(res.status_code, "An error occurred!")) - end - end -end - -var app = new App -app.use("/*", new HtmlErrorHandler) -app.listen("localhost", 3000) -~~~ - -## Sessions - -**Sessions** can be used thanks to the built-in `SessionInit` middleware. - -Here a simple example of login button that define a value in the `req` session. - -~~~ -import popcorn - -redef class Session - var is_logged = false -end - -class AppLogin - super Handler - - redef fun get(req, res) do - res.html """ -

Is logged: {{{req.session.as(not null).is_logged}}}

-
- -
""" - end - - redef fun post(req, res) do - req.session.as(not null).is_logged = true - res.redirect("/") - end -end - -var app = new App -app.use_before("/*", new SessionInit) -app.use("/", new AppLogin) -app.listen("localhost", 3000) -~~~ - -Notice the use of the `SessionInit` on the `/*` route. You must use the -`SessionInit` first to initialize the request session. -Without that, your request session will be set to `null`. -If you don't use sessions in your app, you do not need to include that middleware. - -## Database integration - -### Mongo DB - -If you want to persist your data, Popcorn works well with MongoDB. - -In this example, we will show how to store and list user with a Mongo database. - -First let's define a handler that access the database to list all the user. -The mongo database reference is passed to the UserList handler through the `db` attribute. - -Then we define a handler that displays the user creation form on GET requests. -POST requests are used to save the user data. - -~~~ -import popcorn -import mongodb -import template - -class UserList - super Handler - - var db: MongoDb - - redef fun get(req, res) do - var users = db.collection("users").find_all(new JsonObject) - - var tpl = new Template - tpl.add "

Users

" - tpl.add "" - for user in users do - tpl.add """ - - - """ - end - tpl.add "
{{{user["login"] or else "null"}}}{{{user["password"] or else "null"}}}
" - res.html tpl - end -end - -class UserForm - super Handler - - var db: MongoDb - - redef fun get(req, res) do - var tpl = new Template - tpl.add """

Add a new user

-
- - - -
""" - res.html tpl - end - - redef fun post(req, res) do - var json = new JsonObject - json["login"] = req.post_args["login"] - json["password"] = req.post_args["password"] - db.collection("users").insert(json) - res.redirect "/" - end -end - -var mongo = new MongoClient("mongodb://localhost:27017/") -var db = mongo.database("mongo_example") - -var app = new App -app.use("/", new UserList(db)) -app.use("/new", new UserForm(db)) -app.listen("localhost", 3000) -~~~ - -## Angular.JS integration - -Loving [AngularJS](https://angularjs.org/)? Popcorn is made for Angular and for you! - -Using the StaticHandler with a glob route, you can easily redirect all HTTP requests -to your angular controller: - -~~~ -import popcorn - -var app = new App -app.use("/*", new StaticHandler("my-ng-app/", "index.html")) -app.listen("localhost", 3000) -~~~ - -Because the StaticHandler will not find the angular routes as static files, -you must specify the path to the default angular controller. -In this example, the StaticHandler will redirect any unknown requests to the `index.html` -angular controller. - -See the examples for a more detailed use case working with a JSON API. diff --git a/lib/posix/README.md b/lib/posix/README.md deleted file mode 100644 index 3b73f9c7bc..0000000000 --- a/lib/posix/README.md +++ /dev/null @@ -1,5 +0,0 @@ -Services conforming to POSIX - -The core module `posix` includes POSIX services available on all POSIX compliant systems. -For services provided by some implementations of POSIX but absent from any POSIX version, -import `posix::ext`. diff --git a/lib/pthreads/README.md b/lib/pthreads/README.md deleted file mode 100644 index 44f3754de0..0000000000 --- a/lib/pthreads/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# POSIX Threads support - -The threads can be manipulated and synchronized using the classes `Thread`, -`Mutex` and `Barrier`. - -This group also provides two optional modules with thread-safe collections: - -* `redef_collections` redefines existing collection to make them thread-safe. - This incures a small overhead in all usage of the redefined collections. -* `concurrent_collections` intro new thread-safe collections. - -Theses services are implemented using the POSIX threads. - -You can also use the `is threaded` annotation on methods, which makes them run on their own thread. -Methods with self calls are not supported. - -A method or function annotated with `is threaded` has its return value changed during compilation. -You will get a subclass of `Thread`, even if there wasn't a return value before. You can know if the threaded method is done with the `is_done` boolean from `Thread`. -A call to the `join` method will block the execution until the threaded method is done, or immediatly return if it's already done. -`join` will return an object typed with the orginial return type, or `null` if there wasn't. - -## Known limitations: - -* Most services from the Nit library are not thread-safe. You must manage - your own mutex to avoid conflicts on shared data. -* FFI's global references are not thread-safe. - -## For more information: - -* See: `man pthreads` -* See: `examples/concurrent_array_and_barrier.nit` -* See: ̀ examples/threaded_example.nit` diff --git a/lib/sdl2/README.md b/lib/sdl2/README.md deleted file mode 100644 index 53bf50646e..0000000000 --- a/lib/sdl2/README.md +++ /dev/null @@ -1,13 +0,0 @@ -This is a low-level wrapper of the SDL 2.0 library (as `sdl2`) and SDL_image 2.0 (as `sdl2::image`). - -The main entry point of this project, `sdl2`, exposes some features of the base -library: video, events, syswm, etc. The alternative entry point `sdl2::image` offers -mainly `SDLSurface::load` to load images from PNG, JPG or TIF files. - -You can also import `sdl2::all` to get `sdl2` and all its sister libraries, which is only -`sdl2::image` at this point. - -# Examples - -See the `minimal` example within this project at `examples/minimal` for a simple example -of how to use this project. diff --git a/lib/serialization/README.md b/lib/serialization/README.md deleted file mode 100644 index 3f6ac6c063..0000000000 --- a/lib/serialization/README.md +++ /dev/null @@ -1,309 +0,0 @@ -# Abstract serialization services - -The serialization services are based on the `serialize` and the `noserialize` annotations, -the `Serializable` interface and the implementations of `Serializer` and `Deserializer`. - -## The `serialize` annotation - -A class annotated with `serialize` identifies it as a subclass of Serializable and -triggers the generation of customized serialization and deserialization services. - -~~~ -import serialization - -# Simple serializable class identifying a human -class Person - serialize - - # First and last name - var name: String - - # Year of birth (`null` if unknown) - var birth: nullable Int - - redef fun ==(o) do return o isa SELF and name == o.name and birth == o.birth - redef fun hash do return name.hash -end -~~~ - -The `Person` class also defines `==` and `hash`, this is optional but we will use it to make an important point. -By definition of a serializable class, an instance can be serialized to a stream, then deserialized. -The deserialized instance will not be the same instance, but they should be equal. -So, in this case, we can compare both instances with `==` to test their equality. - -Some conditions applies to the classes that can be annotated as `serialize`. -All attributes of the class must be serializable, runtime errors will be -raised when trying to serialize non-serializable attributes. - -In the class `Person`, all attributes are typed with classes the standards library. -These common types are defined defined as serializable by this project. -The attributes could also be typed with user-defined `serialize` -classes or any other subclass of `Serializable`. - -~~~ -# This `serialize` class is composed of two `serialize` attributes -class Partnership - serialize - - var partner_a: Person - var partner_b: Person - - redef fun ==(o) do return o isa SELF and partner_a == o.partner_a and partner_b == o.partner_b - redef fun hash do return partner_a.hash + 1024*partner_b.hash -end -~~~ - -### Scope of the `serialize` annotation - -`serialize` can annotate class definitions, modules and attributes: - -* The annotation on a class applies only to the class definition, - only attributes declared locally will be serialized. - However, each definition of a class (a refinement or specialization) can be annotated with `serialize`. - -* A module declaration annotated with `serialize` states that all its class definitions - and locally declared attributes are serializable. - - ~~~ - module shared_between_clients is serialize - ~~~ - -* Attribute annotated with `serialize` states that it is to be serialized, when the rest of the class does not. - The class will become subclass to `Serializable` but its attributes are not to be serialized by default. - Only the attributes with the `serialize` annotation will be serialized. - - ~~~ - # Only serialize the `name` - class UserCredentials - var name: String is serialize - var avatar_path: String = "/somepath/"+name is lazy - end - ~~~ - -## The `noserialize` annotation - -The `noserialize` annotation mark an exception in a `serialize` module or class definition. - -* By default a module is `noserialize`. There is no need to declare it as such. - -* A class definition annotated with `noserialize` within a `serialize` module will not be made serializable. - -* A `noserialize` attribute within a class or module annotated with `serialize` will not serialize this attribute. - The class will still be made subclass of `Serializable` and it won't affect the other attributes. - The `noserialize` attribute will not be set at deserialization. - Usually, it will also be annotated with `lazy` to get its value by another mean after the object has been deserialized. - - ~~~ - # Once again, only serialize the `name` - class UserCredentials - serialize - - var name: String - var avatar_path: String = "/somepath/"+name is noserialize, lazy - end - ~~~ - -## The `serialize_as` annotation - -By default, an attribute is identified in the serialization format by its Nit name. -The `serialize_as` attribute changes this behavior and sets the name of an attribute in the serialization format. - -This annotation can be useful to change the name of an attribute to what is expected by a remote service. -Or to use identifiers in the serialization format that are reserved keywords in Nit (like `class` and `type`). - -~~~ -class UserCredentials - serialize - - # Rename to "username" in JSON for compatibility with remote service - var name: String is serialize_as "username" - - # Rename to a shorter "ap" for a smaller JSON file - var avatar_path: String = "/somepath/"+name is lazy, serialize_as "ap" -end -~~~ - -## Custom serializable classes - -The annotation `serialize` should be enough for most cases, -but in some cases you need more control over the serialization process. - -For more control, create a subclass to `Serializable` and redefine `core_serialize_to`. -This method should use `Serializer::serialize_attribute` to serialize its components. -`serialize_attribute` works as a dictionary and organize attributes with a key. - -You will also need to redefine `Deserializer::deserialize_class` to support this specific class. -The method should only act on known class names, and call super otherwise. - -### Example: the User class - -The following example cannot use the `serialize` annotations -because some of the arguments to the `User` class need special treatment: - -* The `name` attribute is perfectly normal, it can be serialized and deserialized - directly. - -* The `password` attribute must be encrypted before being serialized, - and unencrypted on deserialization. - -* The `avatar` attributes is kept as ASCII art in memory. - It could be serialized as such but it is cleaner to only - serialize the path to its source on the file system. - The data is reloaded on deserialization. - -For this customization, the following code snippet implements -two serialization services: `User::core_serialize_to` and -`Deserializer::deserialize_class`. - -~~~ -module user_credentials - -# User credentials for a website -class User - super Serializable - - # User name - var name: String - - # Clear text password - var password: String - - # User's avatar image as data blob - var avatar: Image - - redef fun core_serialize_to(serializer: Serializer) - do - # This is the normal serialization process - serializer.serialize_attribute("name", name) - - # Serialized an encrypted version of the password - # - # Obviously, `rot(13)` is not a good encrption - serializer.serialize_attribute("pass", password.rot(13)) - - # Do not serialize the image, only its path - serializer.serialize_attribute("avatar_path", avatar.path) - end -end - -redef class Deserializer - redef fun deserialize_class(name) - do - if name == "User" then - # Deserialize normally - var user = deserialize_attribute("name") - - # Decrypt password - var pass = deserialize_attribute("pass").rot(-13) - - # Deserialize the path and load the avatar from the file system - var avatar_path = deserialize_attribute("avatar_path") - var avatar = new Image(avatar_path) - - return new User(user, pass, avatar) - end - - return super - end -end - -# An image loaded in memory as ASCII art -# -# Not really useful for this example, provided for consistency only. -class Image - # Path on the filesystem for `self` - var path: String - - # ASCII art composing this image - var ascii_art: String = path.read_all is lazy -end - -~~~ - -See the documentation of the module `serialization::serialization` for more -information on the services to redefine. - -## Serialization services - -The `serialize` annotation and the `Serializable` class are used on -classes specific to the business domain. -To write (and read) instances of these classes to a persistent format -you must use implementations of `Serializer` and `Deserializer`. - -The main implementations of these services are `JsonSerializer` and `JsonDeserializer`, -from the `json_serialization` module. - -~~~ -import json -import user_credentials - -# Data to be serialized and deserialized -var couple = new Partnership( - new Person("Alice", 1985, new Image("alice.png")), - new Person("Bob", null, new Image("bob.png"))) - -var path = "serialized_data.json" -var writer = new FileWriter(path) -var serializer = new JsonSerializer(writer) -serializer.serialize couple -writer.close - -var reader = new FileReader(path) -var deserializer = new JsonDeserializer(reader.to_s) -var deserialized_couple = deserializer.deserialize -reader.close - -assert couple == deserialize_couple -~~~ - -## Limitations and TODO - -The serialization has some limitations: - -* A limitation of the JSON parser prevents deserializing from files - with more than one object. - This could be improved in the future, but for now you should - serialize a single object to each files and use different instances of - serializer and deserializer each time. - -* The serialization uses only the short name of a class, not its qualified name. - This will cause problem when different classes using the same name. - This could be solved partially in the compiler and the library. - A special attention must be given to the consistency of the name across - the different programs sharing the serialized data. - -* The serialization support in the compiler need some help to - deal with generic types. A solution is to use `nitserial`, - the next section explores this subject. - -## Dealing with generic types - -One limitation of the serialization support in the compiler is with generic types. -For example, the `Array` class is generic and serializable. -However, the runtime types of Array instances are parameterized and are unknown to the compiler. -So the compiler won't support serializing instances of `Array[MySerializable]`. - -The tool `nitserial` solves this problem at the level of user modules. -It does so by parsing a Nit module, group or project to find all known -parameterized types of generic classes. -It will then generating a Nit module to handle deserialization of these types. - -Usage steps to serialize parameterized types: - -* Write your program, let's call it `my_prog.nit`, - it must use some parameterized serializable types. - Let's say that you use `Array[MySerializable]`. - -* Run nitserial using `nitserial my_prog.nit` to - generate the file `my_prog_serial.nit`. - -* Compile your program by mixing in the generated module with: - `nitc my_prog.nit -m my_prog_serial.nit` - -This was a simple example, in practical cases you may need -to use more than one generated file. -For example, on a client/server system, an instance can be created -server-side, serialized and the used client-side. -In this case, two files will be generated by nitserial, -one for the server and one for the client. -Both the files should be compiled with both the client and the server. diff --git a/lib/vsm/README.md b/lib/vsm/README.md deleted file mode 100644 index ea501328fe..0000000000 --- a/lib/vsm/README.md +++ /dev/null @@ -1,103 +0,0 @@ -# Vector Space Model - -Vector Space Model (VSM) is an algebraic model for representing text documents -(and any objects, in general) as vectors of identifiers, such as, for example, -index terms. - -It is used in information filtering, information retrieval, indexing and -relevancy rankings. - -The `vsm` package provides the following features: -* Vector comparison with cosine similarity. -* Vector indexing and matching with tf * idf. -* File indexing and matching to free text queries. - -## Vectors - -With VSM, documents are represented by a n-dimensions vector. -Each dimension represent an attribute of the document or object. - -For text document, the count of each term found in the document if often used to -build vectors. - -### Creating a vector - -~~~ -var vector = new Vector -vector["term1"] = 2.0 -vector["term2"] = 1.0 -assert vector["term1"] == 2.0 -assert vector["term2"] == 1.0 -assert vector.norm.is_approx(2.236, 0.001) -~~~ - -### Comparing vectors - -~~~ -var v1 = new Vector -v1["term1"] = 1.0 -v1["term2"] = 2.0 - -var v2 = new Vector -v2["term2"] = 1.0 -v2["term3"] = 3.0 - -var query = new Vector -query["term2"] = 1.0 - -var s1 = query.cosine_similarity(v1) -var s2 = query.cosine_similarity(v2) -assert s1 > s2 -~~~ - -## VSMIndex - -VSMIndex is a Document index based on VSM. - -Using VSMIndex you can index documents associated with their vector. -Documents can then be matched to query vectors. - -This represents a minimalistic search engine. - -~~~ -var index = new VSMIndex - -var d1 = new Document("Doc 1", "/uri/1", v1) -index.index_document(d1) - -var d2 = new Document("Doc 2", "/uri/2", v2) -index.index_document(d2) - -assert index.documents.length == 2 - -query = new Vector -query["term1"] = 1.0 - -var matches = index.match_vector(query) -assert matches.first.document == d1 -~~~ - -## StringIndex - -The StringIndex provides usefull services to index and match strings. - -~~~ -index = new StringIndex - -d1 = index.index_string("Doc 1", "/uri/1", "this is a sample") -d2 = index.index_string("Doc 2", "/uri/2", "this and this is another example") -assert index.documents.length == 2 - -matches = index.match_string("this sample") -assert matches.first.document == d1 -~~~ - -## FileIndex - -The FileIndex is a StringIndex able to index and retrieve files. - -~~~nit -index = new FileIndex - -index.index_files(["/path/to/doc/1", "/path/to/doc/2"]) -~~~ From 49af7d53e451f331ca0872cfcc78accf6bd3d4a6 Mon Sep 17 00:00:00 2001 From: Alexandre Terrasa Date: Wed, 22 Aug 2018 21:48:48 -0400 Subject: [PATCH 2/2] GENERATE READMES Signed-off-by: Alexandre Terrasa --- lib/a_star/README.docdown.md | 21 + lib/a_star/README.md | 73 ++++ lib/actors/README.docdown.md | 13 + lib/actors/README.md | 122 ++++++ lib/ai/README.docdown.md | 27 ++ lib/ai/README.md | 464 +++++++++++++++++++++ lib/android/README.docdown.md | 39 ++ lib/android/README.md | 149 +++++++ lib/app/README.docdown.md | 61 +++ lib/app/README.md | 259 ++++++++++++ lib/array_debug/README.docdown.md | 9 + lib/array_debug/README.md | 11 + lib/base64/README.docdown.md | 17 + lib/base64/README.md | 33 ++ lib/bcm2835/README.docdown.md | 15 + lib/bcm2835/README.md | 43 ++ lib/binary/README.docdown.md | 11 + lib/binary/README.md | 34 ++ lib/bitmap/README.docdown.md | 19 + lib/bitmap/README.md | 50 +++ lib/bucketed_game/README.docdown.md | 13 + lib/bucketed_game/README.md | 27 ++ lib/c/README.doREADMEdown.md | 11 + lib/c/README.md | 20 + lib/cartesian/README.docdown.md | 23 + lib/cartesian/README.md | 80 ++++ lib/cocoa/README.docdown.md | 17 + lib/cocoa/README.md | 49 +++ lib/combinations/README.docdown.md | 19 + lib/combinations/README.md | 116 ++++++ lib/config/README.docdown.md | 27 ++ lib/config/README.md | 217 ++++++++++ lib/console/README.docdown.md | 35 ++ lib/console/README.md | 122 ++++++ lib/core/README.docdown.md | 40 ++ lib/core/README.md | 100 +++++ lib/counter/README.docdown.md | 19 + lib/counter/README.md | 63 +++ lib/cpp/README.docdown.md | 9 + lib/cpp/README.md | 9 + lib/crapto/README.docdown.md | 27 ++ lib/crapto/README.md | 60 +++ lib/crypto/README.docdown.md | 11 + lib/crypto/README.md | 13 + lib/csv/README.docdown.md | 35 ++ lib/csv/README.md | 72 ++++ lib/curl/README.docdown.md | 17 + lib/curl/README.md | 106 +++++ lib/curses/README.docdown.md | 9 + lib/curses/README.md | 9 + lib/date/README.docdown.md | 11 + lib/date/README.md | 36 ++ lib/deriving/README.docdown.md | 27 ++ lib/deriving/README.md | 90 ++++ lib/dom/README.docdown.md | 23 + lib/dom/README.md | 78 ++++ lib/dot/README.docdown.md | 49 +++ lib/dot/README.md | 251 +++++++++++ lib/dummy_array/README.docdown.md | 9 + lib/dummy_array/README.md | 10 + lib/egl/README.docdown.md | 11 + lib/egl/README.md | 25 ++ lib/emscripten/README.docdown.md | 11 + lib/emscripten/README.md | 14 + lib/event_queue/README.docdown.md | 23 + lib/event_queue/README.md | 178 ++++++++ lib/fca/README.docdown.md | 35 ++ lib/fca/README.md | 109 +++++ lib/filter_stream/README.docdown.md | 9 + lib/filter_stream/README.md | 12 + lib/for_abuse/README.docdown.md | 23 + lib/for_abuse/README.md | 47 +++ lib/gamnit/README.docdown.md | 55 +++ lib/gamnit/README.md | 147 +++++++ lib/gen_nit/README.docdown.md | 9 + lib/gen_nit/README.md | 9 + lib/geometry/README.docdown.md | 19 + lib/geometry/README.md | 28 ++ lib/gettext/README.docdown.md | 17 + lib/gettext/README.md | 52 +++ lib/github/README.docdown.md | 67 +++ lib/github/README.md | 219 ++++++++++ lib/glesv2/README.docdown.md | 23 + lib/glesv2/README.md | 259 ++++++++++++ lib/gmp/README.docdown.md | 19 + lib/gmp/README.md | 23 + lib/graph/README.docdown.md | 19 + lib/graph/README.md | 150 +++++++ lib/gtk/README.docdown.md | 13 + lib/gtk/README.md | 16 + lib/hash_debug/README.docdown.md | 11 + lib/hash_debug/README.md | 26 ++ lib/html/README.docdown.md | 19 + lib/html/README.md | 115 +++++ lib/ini/README.docdown.md | 19 + lib/ini/README.md | 53 +++ lib/ios/README.docdown.md | 37 ++ lib/ios/README.md | 100 +++++ lib/java/README.docdown.md | 25 ++ lib/java/README.md | 50 +++ lib/json/README.docdown.md | 27 ++ lib/json/README.md | 114 +++++ lib/jvm/README.docdown.md | 23 + lib/jvm/README.md | 51 +++ lib/libevent/README.docdown.md | 33 ++ lib/libevent/README.md | 56 +++ lib/linux/README.docdown.md | 11 + lib/linux/README.md | 14 + lib/logic/README.docdown.md | 15 + lib/logic/README.md | 44 ++ lib/markdown/README.docdown.md | 49 +++ lib/markdown/README.md | 73 ++++ lib/markdown2/README.docdown.md | 67 +++ lib/markdown2/README.md | 131 ++++++ lib/matrix/README.docdown.md | 11 + lib/matrix/README.md | 11 + lib/md5/README.docdown.md | 19 + lib/md5/README.md | 28 ++ lib/meta/README.docdown.md | 19 + lib/meta/README.md | 82 ++++ lib/mnit/README.docdown.md | 23 + lib/mnit/README.md | 33 ++ lib/mongodb/README.docdown.md | 21 + lib/mongodb/README.md | 81 ++++ lib/more_collections/README.docdown.md | 9 + lib/more_collections/README.md | 15 + lib/mpd/README.docdown.md | 9 + lib/mpd/README.md | 11 + lib/mpi/README.docdown.md | 35 ++ lib/mpi/README.md | 163 ++++++++ lib/msgpack/README.docdown.md | 45 ++ lib/msgpack/README.md | 212 ++++++++++ lib/neo4j/README.docdown.md | 13 + lib/neo4j/README.md | 60 +++ lib/nitcc_runtime/README.docdown.md | 9 + lib/nitcc_runtime/README.md | 25 ++ lib/nitcorn/README.docdown.md | 42 ++ lib/nitcorn/README.md | 457 ++++++++++++++++++++ lib/niti_runtime/README.docdown.md | 7 + lib/niti_runtime/README.md | 7 + lib/nlp/README.docdown.md | 17 + lib/nlp/README.md | 19 + lib/noise/README.docdown.md | 29 ++ lib/noise/README.md | 181 ++++++++ lib/opts/README.docdown.md | 23 + lib/opts/README.md | 37 ++ lib/ordered_tree/README.docdown.md | 19 + lib/ordered_tree/README.md | 101 +++++ lib/parser_base/README.docdown.md | 9 + lib/parser_base/README.md | 10 + lib/perfect_hashing/README.docdown.md | 9 + lib/perfect_hashing/README.md | 9 + lib/performance_analysis/README.docdown.md | 11 + lib/performance_analysis/README.md | 35 ++ lib/pipeline/README.docdown.md | 27 ++ lib/pipeline/README.md | 75 ++++ lib/popcorn/README.docdown.md | 21 + lib/popcorn/README.md | 69 +++ lib/poset/README.docdown.md | 25 ++ lib/poset/README.md | 106 +++++ lib/posix/README.docdown.md | 11 + lib/posix/README.md | 11 + lib/postgresql/README.docdown.md | 19 + lib/postgresql/README.md | 57 +++ lib/privileges/README.docdown.md | 15 + lib/privileges/README.md | 48 +++ lib/progression/README.docdown.md | 9 + lib/progression/README.md | 10 + lib/prompt/README.docdown.md | 17 + lib/prompt/README.md | 22 + lib/pthreads/README.docdown.md | 31 ++ lib/pthreads/README.md | 160 +++++++ lib/readline/README.docdown.md | 9 + lib/readline/README.md | 10 + lib/realtime/README.docdown.md | 19 + lib/realtime/README.md | 47 +++ lib/ropes_debug/README.docdown.md | 9 + lib/ropes_debug/README.md | 9 + lib/rubix/README.docdown.md | 19 + lib/rubix/README.md | 87 ++++ lib/sax/README.docdown.md | 21 + lib/sax/README.md | 229 ++++++++++ lib/saxophonit/README.docdown.md | 19 + lib/saxophonit/README.md | 25 ++ lib/scene2d/README.docdown.md | 33 ++ lib/scene2d/README.md | 47 +++ lib/sdl2/README.docdown.md | 27 ++ lib/sdl2/README.md | 140 +++++++ lib/sendmail/README.docdown.md | 11 + lib/sendmail/README.md | 19 + lib/serialization/README.docdown.md | 23 + lib/serialization/README.md | 195 +++++++++ lib/sexp/README.docdown.md | 11 + lib/sexp/README.md | 17 + lib/sha1/README.docdown.md | 21 + lib/sha1/README.md | 39 ++ lib/signals/README.docdown.md | 11 + lib/signals/README.md | 51 +++ lib/socket/README.docdown.md | 11 + lib/socket/README.md | 11 + lib/sqlite3/README.docdown.md | 13 + lib/sqlite3/README.md | 13 + lib/standard/README.docdown.md | 5 + lib/standard/README.md | 5 + lib/symbol/README.docdown.md | 9 + lib/symbol/README.md | 9 + lib/template/README.docdown.md | 27 ++ lib/template/README.md | 110 +++++ lib/text_stat/README.docdown.md | 7 + lib/text_stat/README.md | 10 + lib/trees/README.docdown.md | 27 ++ lib/trees/README.md | 95 +++++ lib/vsm/README.docdown.md | 17 + lib/vsm/README.md | 74 ++++ lib/websocket/README.docdown.md | 29 ++ lib/websocket/README.md | 67 +++ lib/x11/README.docdown.md | 5 + lib/x11/README.md | 5 + lib/xdg_basedir/README.docdown.md | 35 ++ lib/xdg_basedir/README.md | 47 +++ uml-a_star.svg | 142 +++++++ uml-ai.svg | 51 +++ uml-android.svg | 188 +++++++++ uml-app.svg | 168 ++++++++ uml-bucketed_game.svg | 135 ++++++ uml-c.svg | 185 ++++++++ uml-cocoa.svg | 62 +++ uml-core.svg | 144 +++++++ uml-crapto.svg | 52 +++ uml-crypto.svg | 76 ++++ uml-csv.svg | 70 ++++ uml-curl.svg | 80 ++++ uml-dom.svg | 90 ++++ uml-dot.svg | 98 +++++ uml-gamnit.svg | 190 +++++++++ uml-geometry.svg | 141 +++++++ uml-github.svg | 243 +++++++++++ uml-gmp.svg | 50 +++ uml-graph.svg | 44 ++ uml-gtk.svg | 52 +++ uml-html.svg | 59 +++ uml-ios.svg | 48 +++ uml-java.svg | 106 +++++ uml-json.svg | 154 +++++++ uml-libevent.svg | 178 ++++++++ uml-linux.svg | 108 +++++ uml-logic.svg | 50 +++ uml-markdown.svg | 197 +++++++++ uml-matrix.svg | 40 ++ uml-mnit.svg | 173 ++++++++ uml-mongodb.svg | 82 ++++ uml-msgpack.svg | 166 ++++++++ uml-neo4j.svg | 40 ++ uml-nlp.svg | 50 +++ uml-opts.svg | 184 ++++++++ uml-posix.svg | 40 ++ uml-postgresql.svg | 44 ++ uml-pthreads.svg | 118 ++++++ uml-sax.svg | 80 ++++ uml-saxophonit.svg | 61 +++ uml-scene2d.svg | 92 ++++ uml-sdl2.svg | 181 ++++++++ uml-serialization.svg | 170 ++++++++ uml-sexp.svg | 87 ++++ uml-socket.svg | 82 ++++ uml-sqlite3.svg | 64 +++ uml-template.svg | 38 ++ uml-trees.svg | 98 +++++ uml-vsm.svg | 48 +++ uml-xdg_basedir.svg | 38 ++ 270 files changed, 15838 insertions(+) create mode 100644 lib/a_star/README.docdown.md create mode 100644 lib/a_star/README.md create mode 100644 lib/actors/README.docdown.md create mode 100644 lib/actors/README.md create mode 100644 lib/ai/README.docdown.md create mode 100644 lib/ai/README.md create mode 100644 lib/android/README.docdown.md create mode 100644 lib/android/README.md create mode 100644 lib/app/README.docdown.md create mode 100644 lib/app/README.md create mode 100644 lib/array_debug/README.docdown.md create mode 100644 lib/array_debug/README.md create mode 100644 lib/base64/README.docdown.md create mode 100644 lib/base64/README.md create mode 100644 lib/bcm2835/README.docdown.md create mode 100644 lib/bcm2835/README.md create mode 100644 lib/binary/README.docdown.md create mode 100644 lib/binary/README.md create mode 100644 lib/bitmap/README.docdown.md create mode 100644 lib/bitmap/README.md create mode 100644 lib/bucketed_game/README.docdown.md create mode 100644 lib/bucketed_game/README.md create mode 100644 lib/c/README.doREADMEdown.md create mode 100644 lib/c/README.md create mode 100644 lib/cartesian/README.docdown.md create mode 100644 lib/cartesian/README.md create mode 100644 lib/cocoa/README.docdown.md create mode 100644 lib/cocoa/README.md create mode 100644 lib/combinations/README.docdown.md create mode 100644 lib/combinations/README.md create mode 100644 lib/config/README.docdown.md create mode 100644 lib/config/README.md create mode 100644 lib/console/README.docdown.md create mode 100644 lib/console/README.md create mode 100644 lib/core/README.docdown.md create mode 100644 lib/core/README.md create mode 100644 lib/counter/README.docdown.md create mode 100644 lib/counter/README.md create mode 100644 lib/cpp/README.docdown.md create mode 100644 lib/cpp/README.md create mode 100644 lib/crapto/README.docdown.md create mode 100644 lib/crapto/README.md create mode 100644 lib/crypto/README.docdown.md create mode 100644 lib/crypto/README.md create mode 100644 lib/csv/README.docdown.md create mode 100644 lib/csv/README.md create mode 100644 lib/curl/README.docdown.md create mode 100644 lib/curl/README.md create mode 100644 lib/curses/README.docdown.md create mode 100644 lib/curses/README.md create mode 100644 lib/date/README.docdown.md create mode 100644 lib/date/README.md create mode 100644 lib/deriving/README.docdown.md create mode 100644 lib/deriving/README.md create mode 100644 lib/dom/README.docdown.md create mode 100644 lib/dom/README.md create mode 100644 lib/dot/README.docdown.md create mode 100644 lib/dot/README.md create mode 100644 lib/dummy_array/README.docdown.md create mode 100644 lib/dummy_array/README.md create mode 100644 lib/egl/README.docdown.md create mode 100644 lib/egl/README.md create mode 100644 lib/emscripten/README.docdown.md create mode 100644 lib/emscripten/README.md create mode 100644 lib/event_queue/README.docdown.md create mode 100644 lib/event_queue/README.md create mode 100644 lib/fca/README.docdown.md create mode 100644 lib/fca/README.md create mode 100644 lib/filter_stream/README.docdown.md create mode 100644 lib/filter_stream/README.md create mode 100644 lib/for_abuse/README.docdown.md create mode 100644 lib/for_abuse/README.md create mode 100644 lib/gamnit/README.docdown.md create mode 100644 lib/gamnit/README.md create mode 100644 lib/gen_nit/README.docdown.md create mode 100644 lib/gen_nit/README.md create mode 100644 lib/geometry/README.docdown.md create mode 100644 lib/geometry/README.md create mode 100644 lib/gettext/README.docdown.md create mode 100644 lib/gettext/README.md create mode 100644 lib/github/README.docdown.md create mode 100644 lib/github/README.md create mode 100644 lib/glesv2/README.docdown.md create mode 100644 lib/glesv2/README.md create mode 100644 lib/gmp/README.docdown.md create mode 100644 lib/gmp/README.md create mode 100644 lib/graph/README.docdown.md create mode 100644 lib/graph/README.md create mode 100644 lib/gtk/README.docdown.md create mode 100644 lib/gtk/README.md create mode 100644 lib/hash_debug/README.docdown.md create mode 100644 lib/hash_debug/README.md create mode 100644 lib/html/README.docdown.md create mode 100644 lib/html/README.md create mode 100644 lib/ini/README.docdown.md create mode 100644 lib/ini/README.md create mode 100644 lib/ios/README.docdown.md create mode 100644 lib/ios/README.md create mode 100644 lib/java/README.docdown.md create mode 100644 lib/java/README.md create mode 100644 lib/json/README.docdown.md create mode 100644 lib/json/README.md create mode 100644 lib/jvm/README.docdown.md create mode 100644 lib/jvm/README.md create mode 100644 lib/libevent/README.docdown.md create mode 100644 lib/libevent/README.md create mode 100644 lib/linux/README.docdown.md create mode 100644 lib/linux/README.md create mode 100644 lib/logic/README.docdown.md create mode 100644 lib/logic/README.md create mode 100644 lib/markdown/README.docdown.md create mode 100644 lib/markdown/README.md create mode 100644 lib/markdown2/README.docdown.md create mode 100644 lib/markdown2/README.md create mode 100644 lib/matrix/README.docdown.md create mode 100644 lib/matrix/README.md create mode 100644 lib/md5/README.docdown.md create mode 100644 lib/md5/README.md create mode 100644 lib/meta/README.docdown.md create mode 100644 lib/meta/README.md create mode 100644 lib/mnit/README.docdown.md create mode 100644 lib/mnit/README.md create mode 100644 lib/mongodb/README.docdown.md create mode 100644 lib/mongodb/README.md create mode 100644 lib/more_collections/README.docdown.md create mode 100644 lib/more_collections/README.md create mode 100644 lib/mpd/README.docdown.md create mode 100644 lib/mpd/README.md create mode 100644 lib/mpi/README.docdown.md create mode 100644 lib/mpi/README.md create mode 100644 lib/msgpack/README.docdown.md create mode 100644 lib/msgpack/README.md create mode 100644 lib/neo4j/README.docdown.md create mode 100644 lib/neo4j/README.md create mode 100644 lib/nitcc_runtime/README.docdown.md create mode 100644 lib/nitcc_runtime/README.md create mode 100644 lib/nitcorn/README.docdown.md create mode 100644 lib/nitcorn/README.md create mode 100644 lib/niti_runtime/README.docdown.md create mode 100644 lib/niti_runtime/README.md create mode 100644 lib/nlp/README.docdown.md create mode 100644 lib/nlp/README.md create mode 100644 lib/noise/README.docdown.md create mode 100644 lib/noise/README.md create mode 100644 lib/opts/README.docdown.md create mode 100644 lib/opts/README.md create mode 100644 lib/ordered_tree/README.docdown.md create mode 100644 lib/ordered_tree/README.md create mode 100644 lib/parser_base/README.docdown.md create mode 100644 lib/parser_base/README.md create mode 100644 lib/perfect_hashing/README.docdown.md create mode 100644 lib/perfect_hashing/README.md create mode 100644 lib/performance_analysis/README.docdown.md create mode 100644 lib/performance_analysis/README.md create mode 100644 lib/pipeline/README.docdown.md create mode 100644 lib/pipeline/README.md create mode 100644 lib/popcorn/README.docdown.md create mode 100644 lib/popcorn/README.md create mode 100644 lib/poset/README.docdown.md create mode 100644 lib/poset/README.md create mode 100644 lib/posix/README.docdown.md create mode 100644 lib/posix/README.md create mode 100644 lib/postgresql/README.docdown.md create mode 100644 lib/postgresql/README.md create mode 100644 lib/privileges/README.docdown.md create mode 100644 lib/privileges/README.md create mode 100644 lib/progression/README.docdown.md create mode 100644 lib/progression/README.md create mode 100644 lib/prompt/README.docdown.md create mode 100644 lib/prompt/README.md create mode 100644 lib/pthreads/README.docdown.md create mode 100644 lib/pthreads/README.md create mode 100644 lib/readline/README.docdown.md create mode 100644 lib/readline/README.md create mode 100644 lib/realtime/README.docdown.md create mode 100644 lib/realtime/README.md create mode 100644 lib/ropes_debug/README.docdown.md create mode 100644 lib/ropes_debug/README.md create mode 100644 lib/rubix/README.docdown.md create mode 100644 lib/rubix/README.md create mode 100644 lib/sax/README.docdown.md create mode 100644 lib/sax/README.md create mode 100644 lib/saxophonit/README.docdown.md create mode 100644 lib/saxophonit/README.md create mode 100644 lib/scene2d/README.docdown.md create mode 100644 lib/scene2d/README.md create mode 100644 lib/sdl2/README.docdown.md create mode 100644 lib/sdl2/README.md create mode 100644 lib/sendmail/README.docdown.md create mode 100644 lib/sendmail/README.md create mode 100644 lib/serialization/README.docdown.md create mode 100644 lib/serialization/README.md create mode 100644 lib/sexp/README.docdown.md create mode 100644 lib/sexp/README.md create mode 100644 lib/sha1/README.docdown.md create mode 100644 lib/sha1/README.md create mode 100644 lib/signals/README.docdown.md create mode 100644 lib/signals/README.md create mode 100644 lib/socket/README.docdown.md create mode 100644 lib/socket/README.md create mode 100644 lib/sqlite3/README.docdown.md create mode 100644 lib/sqlite3/README.md create mode 100644 lib/standard/README.docdown.md create mode 100644 lib/standard/README.md create mode 100644 lib/symbol/README.docdown.md create mode 100644 lib/symbol/README.md create mode 100644 lib/template/README.docdown.md create mode 100644 lib/template/README.md create mode 100644 lib/text_stat/README.docdown.md create mode 100644 lib/text_stat/README.md create mode 100644 lib/trees/README.docdown.md create mode 100644 lib/trees/README.md create mode 100644 lib/vsm/README.docdown.md create mode 100644 lib/vsm/README.md create mode 100644 lib/websocket/README.docdown.md create mode 100644 lib/websocket/README.md create mode 100644 lib/x11/README.docdown.md create mode 100644 lib/x11/README.md create mode 100644 lib/xdg_basedir/README.docdown.md create mode 100644 lib/xdg_basedir/README.md create mode 100644 uml-a_star.svg create mode 100644 uml-ai.svg create mode 100644 uml-android.svg create mode 100644 uml-app.svg create mode 100644 uml-bucketed_game.svg create mode 100644 uml-c.svg create mode 100644 uml-cocoa.svg create mode 100644 uml-core.svg create mode 100644 uml-crapto.svg create mode 100644 uml-crypto.svg create mode 100644 uml-csv.svg create mode 100644 uml-curl.svg create mode 100644 uml-dom.svg create mode 100644 uml-dot.svg create mode 100644 uml-gamnit.svg create mode 100644 uml-geometry.svg create mode 100644 uml-github.svg create mode 100644 uml-gmp.svg create mode 100644 uml-graph.svg create mode 100644 uml-gtk.svg create mode 100644 uml-html.svg create mode 100644 uml-ios.svg create mode 100644 uml-java.svg create mode 100644 uml-json.svg create mode 100644 uml-libevent.svg create mode 100644 uml-linux.svg create mode 100644 uml-logic.svg create mode 100644 uml-markdown.svg create mode 100644 uml-matrix.svg create mode 100644 uml-mnit.svg create mode 100644 uml-mongodb.svg create mode 100644 uml-msgpack.svg create mode 100644 uml-neo4j.svg create mode 100644 uml-nlp.svg create mode 100644 uml-opts.svg create mode 100644 uml-posix.svg create mode 100644 uml-postgresql.svg create mode 100644 uml-pthreads.svg create mode 100644 uml-sax.svg create mode 100644 uml-saxophonit.svg create mode 100644 uml-scene2d.svg create mode 100644 uml-sdl2.svg create mode 100644 uml-serialization.svg create mode 100644 uml-sexp.svg create mode 100644 uml-socket.svg create mode 100644 uml-sqlite3.svg create mode 100644 uml-template.svg create mode 100644 uml-trees.svg create mode 100644 uml-vsm.svg create mode 100644 uml-xdg_basedir.svg diff --git a/lib/a_star/README.docdown.md b/lib/a_star/README.docdown.md new file mode 100644 index 0000000000..4816d1bf33 --- /dev/null +++ b/lib/a_star/README.docdown.md @@ -0,0 +1,21 @@ +# `a_star` - [[ini-desc: a_star]] + +[[toc: a_star]] + +[[doc: a_star::a_star]] + +## Features + +[[uml: a_star | format: svg, mentities: a_star::Node;a_star::Link;a_star::Graph;a_star::AStarPath;a_star::PathContext;a_star::ConstantPathContext;a_star::WeightedPathContext;a_star::WeightedLink;a_star::TargetCondition]] + +[[features: a_star | mentities: a_star::Node;a_star::Link;a_star::Graph;a_star::AStarPath;a_star::PathContext;a_star::ConstantPathContext;a_star::WeightedPathContext;a_star::WeightedLink;a_star::TargetCondition;a_star::NamedNode;a_star::PositionedNamedNode;a_star::PositionedLink;a_star::PositionPathContext]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: a_star]] + +## Authors + +This project is maintained by [[ini-maintainer: a_star]]. diff --git a/lib/a_star/README.md b/lib/a_star/README.md new file mode 100644 index 0000000000..33306196ba --- /dev/null +++ b/lib/a_star/README.md @@ -0,0 +1,73 @@ +# `a_star` - A* pathfinding in graphs + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +A single graph may have different properties according to the `PathContext` used + +Usage: + +~~~ +# Weighted graph (letters are nodes, digits are weights): +# +# a -2- b +# / / +# 3 1 +# / / +# c -3- d -8- e +# +var graph = new Graph[Node,WeightedLink] + +var na = new Node(graph) +var nb = new Node(graph) +var nc = new Node(graph) +var nd = new Node(graph) +var ne = new Node(graph) + +var lab = new WeightedLink(graph, na, nb, 2) +var lac = new WeightedLink(graph, na, nc, 3) +var lbd = new WeightedLink(graph, nb, nd, 1) +var lcd = new WeightedLink(graph, nc, nd, 3) +var lde = new WeightedLink(graph, nd, ne, 8) + +var context = new WeightedPathContext(graph) + +var path = na.path_to(ne, 100, context) +assert path != null else print "No possible path" + +assert path.step == nb +assert path.step == nd +assert path.step == ne +assert path.at_end_of_path +~~~ + +## Features + +![Diagram for `a_star`](uml-a_star.svg) + +* `AStarPath` - Result from path finding and a walkable path +* `ConstantPathContext` - Simple context with constant cost on each links +* `Graph` - General graph +* `Link` - Link between two nodes and associated to a graph +* `NamedNode` - Simple node with a name +* `Node` - General graph node +* `PathContext` - Context related to an evocation of pathfinding +* `PositionPathContext` - Context for a graph with positions +* `PositionedLink` - Link for nodes with a position +* `PositionedNamedNode` - Node with a name and position +* `TargetCondition` - Advanced path conditions with customizable accept states +* `WeightedLink` - A `Link` with a `weight` +* `WeightedPathContext` - A `PathContext` for graphs with `WeightedLink` + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/actors/README.docdown.md b/lib/actors/README.docdown.md new file mode 100644 index 0000000000..12037225bb --- /dev/null +++ b/lib/actors/README.docdown.md @@ -0,0 +1,13 @@ +# `actors` - [[ini-desc: actors]] + +Example from `actors::agent_simulation`: + +[[code: actors::agent_simulation]] + +## Features + +[[features: actors | mentities: actors::Actor;actors::Mailbox;actors::Message;actors::Proxy;actors::ShutDownMessage;actors::Future;actors::SynchronizedCounter;actors::ActorClockAgent;actors::ActorAgent;actors::MessageClockAgent;actors::ClockAgentMessagenb_steps;actors::ClockAgentMessageagents;actors::ClockAgentMessagenb_finished;actors::ClockAgentMessagedo_step;actors::ClockAgentMessagefinished_step;actors::MessageAgent;actors::AgentMessagedo_step;actors::AgentMessageend_step;actors::AgentMessageothers;actors::AgentMessagecount;actors::AgentMessagegreet;actors::AgentMessagegreet_back;actors::ProxyClockAgent;actors::ProxyAgent;actors::ActorCreature;actors::MessageCreature;actors::CreatureMessageplace;actors::CreatureMessagecolor;actors::CreatureMessageid;actors::CreatureMessagecount;actors::CreatureMessagesamecount;actors::CreatureMessagerun;actors::CreatureMessageto_string;actors::ProxyCreature;actors::ActorFannkuchRedux;actors::MessageFannkuchRedux;actors::FannkuchReduxMessagep;actors::FannkuchReduxMessagepp;actors::FannkuchReduxMessagecount;actors::FannkuchReduxMessageprint_p;actors::FannkuchReduxMessagefirst_permutation;actors::FannkuchReduxMessagenext_permutation;actors::FannkuchReduxMessagecount_flips;actors::FannkuchReduxMessagerun_task;actors::FannkuchReduxMessagerun;actors::ProxyFannkuchRedux;actors::ActorWorker;actors::MessageWorker;actors::WorkerMessageget_byte;actors::WorkerMessageput_line;actors::WorkerMessagework;actors::ProxyWorker;actors::ActorA;actors::MessageA;actors::AMessagefoo;actors::AMessagebar;actors::ProxyA;actors::ActorThreadRing;actors::MessageThreadRing;actors::ThreadRingMessageid;actors::ThreadRingMessagenext;actors::ThreadRingMessagesend_token;actors::ProxyThreadRing]] + +## Authors + +This project is maintained by [[ini-maintainer: actors]]. diff --git a/lib/actors/README.md b/lib/actors/README.md new file mode 100644 index 0000000000..631f4a46c7 --- /dev/null +++ b/lib/actors/README.md @@ -0,0 +1,122 @@ +# `actors` - Nit Actor Model + +Example from `actors::agent_simulation`: + +~~~ +# a "Framework" to make Multi-Agent Simulations in Nit +module agent_simulation is example, no_warning("missing-doc") + +import actors + +# Master of the simulation, it initiates the steps and waits for them to terminate +class ClockAgent + actor + + # Number of steps to do in the simulation + var nb_steps: Int + + # List of Agents in the simulation + var agents: Array[Agent] + + # Number of agents that finished their step + var nb_finished = 0 + + fun do_step do + for a in agents do a.async.do_step + nb_steps -= 1 + end + + fun finished_step do + nb_finished += 1 + if nb_finished == agents.length then + nb_finished = 0 + if nb_steps != 0 then async.do_step + end + end +end + +class Agent + actor + + # Doing a step in the simulation + fun do_step do + end + + fun end_step do clock_agent.async.finished_step + +end + +redef class Sys + var clock_agent: ClockAgent is noautoinit,writable +end +~~~ + +## Features + +* `AMessagebar` +* `AMessagefoo` +* `Actor` - Abstraction of an actor +* `ActorA` - ###################### Actor classes ######################### +* `ActorAgent` +* `ActorClockAgent` - ###################### Actor classes ######################### +* `ActorCreature` - ###################### Actor classes ######################### +* `ActorFannkuchRedux` - ###################### Actor classes ######################### +* `ActorThreadRing` - ###################### Actor classes ######################### +* `ActorWorker` - ###################### Actor classes ######################### +* `AgentMessagecount` +* `AgentMessagedo_step` +* `AgentMessageend_step` +* `AgentMessagegreet` +* `AgentMessagegreet_back` +* `AgentMessageothers` - ###################### Redef classes ######################### +* `ClockAgentMessageagents` +* `ClockAgentMessagedo_step` +* `ClockAgentMessagefinished_step` +* `ClockAgentMessagenb_finished` +* `ClockAgentMessagenb_steps` +* `CreatureMessagecolor` +* `CreatureMessagecount` +* `CreatureMessageid` +* `CreatureMessageplace` +* `CreatureMessagerun` +* `CreatureMessagesamecount` +* `CreatureMessageto_string` +* `FannkuchReduxMessagecount` +* `FannkuchReduxMessagecount_flips` +* `FannkuchReduxMessagefirst_permutation` +* `FannkuchReduxMessagenext_permutation` +* `FannkuchReduxMessagep` +* `FannkuchReduxMessagepp` +* `FannkuchReduxMessageprint_p` +* `FannkuchReduxMessagerun` +* `FannkuchReduxMessagerun_task` +* `Future` - The promise of a value which will be set asynchronously +* `Mailbox` - A Blocking queue implemented from a `ConcurrentList` +* `Message` - A Message received by a Mailbox +* `MessageA` - ###################### Messages classes ###################### +* `MessageAgent` +* `MessageClockAgent` - ###################### Messages classes ###################### +* `MessageCreature` - ###################### Messages classes ###################### +* `MessageFannkuchRedux` - ###################### Messages classes ###################### +* `MessageThreadRing` - ###################### Messages classes ###################### +* `MessageWorker` - ###################### Messages classes ###################### +* `Proxy` - Abstraction of proxies for threaded actors +* `ProxyA` +* `ProxyAgent` +* `ProxyClockAgent` +* `ProxyCreature` +* `ProxyFannkuchRedux` +* `ProxyThreadRing` +* `ProxyWorker` +* `ShutDownMessage` - A Message to Rule them all... properly shutdown an Actor +* `SynchronizedCounter` - A counter on which threads can wait until its value is 0 +* `ThreadRingMessageid` +* `ThreadRingMessagenext` +* `ThreadRingMessagesend_token` +* `WorkerMessageget_byte` +* `WorkerMessageput_line` +* `WorkerMessagework` + +## Authors + +This project is maintained by **Romain Chanoir **. diff --git a/lib/ai/README.docdown.md b/lib/ai/README.docdown.md new file mode 100644 index 0000000000..311ca415c9 --- /dev/null +++ b/lib/ai/README.docdown.md @@ -0,0 +1,27 @@ +# `ai` - [[ini-desc: ai]] + +[[toc: ai]] + +## Features + +[[uml: ai | format: svg, mentities: ai::ai;ai::backtrack;ai::search]] + +### `backtrack` - Basic framework for active backtrack solver + +[[doc: ai::backtrack | no-synopsis]] + +Example from `ai::queens`: + +[[code: ai::queens]] + +### `search` - Basic framework for search problems and solver. + +[[doc: ai::search | no-synopsis]] + +Example from `ai::puzzle`: + +[[code: ai::puzzle]] + +## Authors + +This project is maintained by [[ini-maintainer: ai]]. diff --git a/lib/ai/README.md b/lib/ai/README.md new file mode 100644 index 0000000000..752b4ff0d8 --- /dev/null +++ b/lib/ai/README.md @@ -0,0 +1,464 @@ +# `ai` - Simple library for basic artificial intelligence algorithms + +* [Features](#Features) +* [`backtrack` - Basic framework for active backtrack solver](#`backtrack`---Basic-framework-for-active-backtrack-solver) +* [`search` - Basic framework for search problems and solver.](#`search`---Basic-framework-for-search-problems-and-solver.) +* [Authors](#Authors) + +## Features + +![Diagram for `ai`](uml-ai.svg) + +### `backtrack` - Basic framework for active backtrack solver + +This module provides a simple abstract class `BacktrackProblem[S,A]` to be specialized for a specific problem. + +The concrete class `BacktrackSolver` is used to configure, query, and run a solver for a given problem. + +For an example, see the `queens.nit` program in the `examples` subdirectory. + +Example from `ai::queens`: + +~~~ +# Example of the famous eight-queens problem solved with the `ai::backtrack` module. +# +# The game is to places n queens on a n*n chessboard. +# The constraint is that two queens cannot be on the same row, column or diagonal. +# +# Eg. a solution to the 8-queens problem is +# ~~~raw +# +--------+ +# |Q.......| +# |....Q...| +# |.......Q| +# |.....Q..| +# |..Q.....| +# |......Q.| +# |.Q......| +# |...Q....| +# +--------+ +# +# This program takes an integer n as argument then display all solutions for the +# n-queens proglem (ie. on a n*n board). +module queens is example + +import ai::backtrack + +# The (eight-)queens problem, modeled naively as a `BacktrackProblem`. +# +# The state (`S`) is a board, modeled as an array of occupied rows. +# The integer in each row indicates the column occupied by the queen. +# Since there can be only one queen by row, a single `Int` is +# enough for each row, and the whole board `rows` is just an `Array[Int]`. +# Only the occupied rows are stored, thus the length of `rows` indicates +# the number of occupied rows, the remaining virtual rows are considered free. +# +# An action (`A`) is the column where to put a queen in the first free row, +# so modeled as an Int. +# Actions are applied until all rows are occupied by a queen. +class QueenProblem + super BacktrackProblem[Array[Int], Int] + + # The initial state has no queens; so, no occupied rows. + redef fun initial_state do return new Array[Int] + + # The board size. + # Hint: use 8 to be traditional. + var size: Int + + # What are the available columns for a queen in the first free row? + # Just look at occupied rows above and cancel the possible columns one by one. + redef fun actions(rows, node) + do + # No more than 8 rows + if rows.length >= size then return null + + # Available columns. At first, all are available. + var columns = new Array[Bool].filled_with(true, size) + + # Look at each occupied row and cancel columns + var i = rows.length # delta for each diagonal + for r in rows do + columns[r] = false # no queen under `r` + var d = r - i + if d >= 0 then columns[d] = false # no queen on the first diagonal + d = r + i + if d < size then columns[d] = false # no queen on the second diagonal + i -= 1 + end + + # Collect the remaining columns, those that were not cancelled. + var res = new Array[Int] + for c in [0..size[ do if columns[c] then res.add(c) + + return res + end + + # The first free row become occupied with a queen placed where indicated. + redef fun apply_action(rows, column) + do + rows.add column + end + + # Just `free` the last occupied row. + redef fun backtrack(rows, column) + do + rows.pop + end + + # Are all rows are occupied? + redef fun is_goal(rows) do return rows.length >= size + + # Draw a nice board + fun print_state(rows: Array[Int]) + do + printn "+" + for i in [0..size[ do printn "-" + print "+" + for r in rows do + printn "|" + for i in [0..r[ do printn "." + printn "Q" + for i in [r+1..size[ do printn "." + print "|" + end + for r in [rows.length..size[ do + printn "|" + for i in [0..size[ do printn "." + print "|" + end + printn "+" + for i in [0..size[ do printn "-" + print "+" + end +end + +# just cont solutions (no not print them) +var quiet = false + +# The board size +var size = 8 + +# Basic argument parsing +if args.length > 0 and args.first == "-q" then + args.shift + quiet = true +end +if args.length > 0 then + size = args.first.to_i + if size <= 0 then + print "usage: queens [-q] [size]\n -q for quiet" + exit 1 + end +end + +print "The {size}-queens problem" +var pb = new QueenProblem(size) +var s = pb.solve +var sols = 0 +while s.is_running do + if s.run != null then + if not quiet then pb.print_state(s.state) + sols += 1 + end +end +print "Found {sols} solutions" +~~~ + +### `search` - Basic framework for search problems and solver. + +The module provides a simple abstract class `SearchProblem[S,A]` to be specialized for a specific problem. + +The concrete class `SearchSolver` is used to configure, query, and run a solver for a given problem. + +For an example, see the `puzzle.nit` program in the `examples` subdirectory. + +Example from `ai::puzzle`: + +~~~ +# The N-puzzle problem, modeled naively as a `SearchProblem`. +# +# A square grid, made of tiles represented with a letter, is scrambled. +# A missing tile, the hole, represented with a dot, is used to move them. +# +# The goal is to found a plan, made of the four basic movements up, down, +# left, and right, that move each letter to its correct position: the solved +# grid list letters alphabetically from left to right then top to bottom. +# The hole must be in the last position (bottom-right). +# +# The argument of the program is a initial position, the program then find +# the best plan to solve the puzzle. +# +# ## Example: +# +# The argument "abcd.fgeh" is the grid +# +# ~~~raw +# abc +# d.f +# geh +# ~~~ +# +# The goal is: +# +# ~~~raw +# abc +# def +# gh. +# ~~~ +# +# The shortest plan, in two steps, is to move *up* the tile under the hole (e), +# then to move *left* the tile after the hole (h). +module puzzle is example + +import ai::search + +# The state (`S`) is a square grid, modeled as a one-dimensional array of Tile. +# read from left to right then top to bottom. +# +# An action (`A`) is the relative position of the tile to swap with the hole. +# Therefore, `-1` for left, `1` for right, `-width` for up and `width` for down. +class PuzzleProblem + super SearchProblem[ArrayCmp[Tile], Int] + + # The initial grid. use letters for tiles, and . for the hole. + var initial_grid: String + + # The width of the grid. + # Eg. 3 for a 8-puzzle grid + var width: Int is noinit + + # Construct a state form `initial_grid` + redef fun initial_state do + var g = initial_grid + var len = g.length + var width = len.sqrt.to_i + self.width = width + if width * width != len then + print "Error: {g} has {len} tiles. A square number, like {width*width} is needed" + exit 1 + end + var res = new ArrayCmp[Tile] + for i in [0..g.length[ do + var c = g.chars[i] + if c == ' ' or c == '.' then + var hole = new Tile('.', -1) + self.hole = hole + res.add hole + else if c >= '1' and c <= '9' then + var t = new Tile(c, '1'.distance(c)) + res.add t + else if c >= 'a' and c <= 'z' then + var t = new Tile(c, 'a'.distance(c)) + res.add t + else if c >= 'A' and c <= 'Z' then + var t = new Tile(c, 'A'.distance(c)) + res.add t + else + print "Error: illegal tile {c} in {g}" + exit 1 + end + end + return res + end + + # Get the four available movements, or 3 on a edge, or 2 in a corner. + redef fun actions(state) + do + var h = get_hole(state) + var x = h % width + var y = h / width + var res = new Array[Int] + if x >= 1 then res.add(-1) + if x < width-1 then res.add(1) + if y >= 1 then res.add(-width) + if y < width-1 then res.add(width) + return res + end + + # Return the state where the tile at hole+action has moved + redef fun apply_action(state, action) + do + # Copy the state + var res = new ArrayCmp[Tile].with_capacity(state.length) + res.add_all(state) + + # Get the hole and the tile next to it + var h = get_hole(res) + var t = h + action + + # Move (by swapping the tile and the hole) + res[h] = res[t] + res[t] = hole + + return res + end + + # The special empty tile for fast retrieval. + var hole: Tile is noinit + + # What is the position of the hole? + fun get_hole(state: Array[Tile]): Int + do + return state.index_of(hole) + end + + # Each tile is at its correct position + redef fun is_goal(state) + do + for i in [0..state.length[ do + var t = state[i] + if t != hole and t.goal_idx != i then return false + end + return true + end + + # The sum of the Manhattan distances of each tile to its goal + # Not the best heuristic but the simplest to implement among the good ones. + redef fun heuristic(state) + do + var p = 0 + var i = -1 + for t in state do + i += 1 + + # The hole does not count + if t == hole then continue + + var dx = (i % width - t.goal_idx % width).abs + var dy = (i / width - t.goal_idx / width).abs + + # Add Manhattan distance + p += dx + dy + end + return p.to_f + end + + # Print the grid + fun print_state(state: Array[Tile]) + do + for i in [0..state.length[ do + var t = state[i] + if t == hole then + printn "." + else + printn t.symbol + end + if (i+1) % width == 0 then print "" + end + end + + # Print the plan with words. + fun print_plan(plan: Sequence[Int]) + do + var s = new Array[String] + for i in plan do + if i == -1 then + s.add "right(>)" + else if i == 1 then + s.add "left(<)" + else if i == -width then + s.add "down(v)" + else if i == width then + s.add "up(^)" + else + abort + end + end + print "Solution in {plan.length} moves: {s.join(" ")}" + end + + redef fun make_memory do + var res = super + res.add new RBTreeMap[ArrayCmp[Tile], SearchNode[ArrayCmp[Tile], Int]] + res.add new BinTreeMap[ArrayCmp[Tile], SearchNode[ArrayCmp[Tile], Int]] + return res + end +end + +# A movable tile +# A simple class to encapsulate the symbol and the goal position. +class Tile + super Comparable + redef type OTHER: Tile is fixed + + # The symbol written on the tile + var symbol: Char + + # The expected position in the grid + var goal_idx: Int + + redef fun to_s do return symbol.to_s + redef fun ==(o) do return o isa Tile and goal_idx == o.goal_idx + redef fun <(o) do return goal_idx < o.goal_idx + redef fun <=>(o) do return goal_idx <=> o.goal_idx +end + +var configs = false + +if not args.is_empty then + if args.first == "--configs" then + configs = true + args.shift + end +end + +if args.is_empty then + print """ +Usage: puzzle [--configs] initial... + +--configs: search and time solutions with various configurations of solvers. +initial: an initial configuration (letters for the tiles, and dot for the hole). eg: + + 8-puzzle: + + goal (0): abcdefgh. + easy (4): abce.fdgh + medium (10): eabf.cdgh + hard (20): feacbh.dg + harder (31): hfgbedc.a + + 15-puzzle: + goal (0): abcdefghijklmno. + easy (30): bacdefghijlkmno. + medium (40): fg.jacoheldnibmk + hard (55): kleg.mondcafjhbi + harder (61): lomgkcend.afjhbi + + 24-puzzle: + goal (0): abcdefghijklmnopqrstuvwx. + easy (55): giabcjekmdhrtflqsownpuv.x + medium (75): giabcjekmdrtwulhs.vnqofpx + hard (79): giabcjekmdrtw.uhsvnlqofpx + harder (80): giabcjekmdrt.wuhsvnlqofpx +""" + exit 0 +end + + +for arg in args do + var pb = new PuzzleProblem(arg) + print "Initial: {arg}" + pb.print_state(pb.initial_state) + + if configs then + pb.run_configs(1000000) + continue + end + + var s = pb.astar + s.memorize = true + var r = s.run + if r == null then + print "No solution." + break + end + + print "Solved, after looking at {r.steps} positions" + pb.print_plan(r.plan) +end +~~~ + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/android/README.docdown.md b/lib/android/README.docdown.md new file mode 100644 index 0000000000..a7b9441c7b --- /dev/null +++ b/lib/android/README.docdown.md @@ -0,0 +1,39 @@ +# `android` - [[ini-desc: android]] + +[[toc: android]] + +[[doc: android::android]] + +Example from `android::ui_test`: + +[[code: android::ui_test]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: android]] + +### Run `nit_activity` + +Compile `nit_activity` with the following command: + +[[main-compile: android::nit_activity]] + +## Features + +[[uml: android | format: svg, mentities: android>;android>bundle>;android>intent>;android>notification>;android>service>;android>shared_preferences>;android>ui>]] + +[[features: android | mentities: android::assets;android::assets_and_resources;android::audio;android::aware;android::cardboard;android::data_store;android::landscape;android::native_app_glue;android::nit_activity;android::sensors;android::vibration;android::wifi;android::activities;android::dalvik;android::game;android::gamepad;android::http_request;android::input_events;android::key_event;android::load_image;android::log;android::platform;android::portrait;android::toast]] + +Then run it with: + +[[main-run: android::nit_activity]] + +## Authors + +This project is maintained by [[ini-maintainer: android]]. diff --git a/lib/android/README.md b/lib/android/README.md new file mode 100644 index 0000000000..69c4fec561 --- /dev/null +++ b/lib/android/README.md @@ -0,0 +1,149 @@ +# `android` - Android platform support and APIs + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `nit_activity`](#Run-`nit_activity`) +* [Features](#Features) +* [Authors](#Authors) + +This module provides basic logging facilities, advanced logging can be +achieved by importing `android::log`. + +Example from `android::ui_test`: + +~~~ +# Test for app.nit's UI services +module ui_test is + example + app_name "app.nit UI test" + app_version(0, 1, git_revision) + app_namespace "org.nitlanguage.ui_test" + android_manifest_activity """android:theme="@android:style/Theme.Light"""" + android_api_target 15 +end + +import android::ui +import android::toast +import android::notification + +redef class App + redef fun on_create + do + self.window = new Window + super + end +end + +redef class Window + + private var layout = new VerticalLayout(parent=self) + + private var but_notif = new Button(parent=layout, text="Show Notification") + private var but_toast = new Button(parent=layout, text="Show Toast") + + private var notif: nullable Notification = null + + init + do + but_notif.observers.add self + but_toast.observers.add self + end + + # Action when pressing `but_notif` + fun act_notif + do + var notif = self.notif + if notif == null then + notif = new Notification("From app.nit", "Some content...") + notif.ticker = "Ticker text..." + notif.show + self.notif = notif + else + notif.cancel + self.notif = null + end + end + + # Action when pressing `but_toast` + fun act_toast + do + app.toast("Sample toast from app.nit at {get_time}", false) + end + + redef fun on_event(event) + do + print "on_event {event}" + if event isa ButtonPressEvent then + var sender = event.sender + if sender == but_notif then + act_notif + else if sender == but_toast then + act_toast + end + end + end +end +~~~ + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `app` - _app.nit_, a framework for portable applications +* `c` - Structures and services for compatibility with the C language +* `core` - Nit common library of core classes and methods +* `gamnit` - Portable game and multimedia framework for Nit +* `java` - Supporting services for the FFI with Java and to access Java libraries +* `json` - read and write JSON formatted text +* `mnit` - `mnit` + +### Run `nit_activity` + +Compile `nit_activity` with the following command: + +~~~bash +nitc ./nit_activity.nit +~~~ + +## Features + +![Diagram for `android`](uml-android.svg) + +* `activities` - Android Activities wrapper +* `assets` - Implementation of `app::assets` +* `assets_and_resources` - Android Assets and Resources Management +* `audio` - Android audio services, wraps a part of android audio API +* `aware` - Android compatibility module +* `cardboard` - Services from the Google Cardboard SDK for virtual reality on Android +* `dalvik` - Java related services specific to Android and its Dalvik VM +* `data_store` - Implements `app::data_store` using `shared_preferences` +* `game` - Android services and implementation of app.nit for gamnit and mnit +* `gamepad` - Support for gamepad events (over Bluetooth or USB) +* `http_request` - Android implementation of `app:http_request` +* `input_events` - Pointer and hardware key events +* `key_event` +* `landscape` - Lock the application in the landscape orientation +* `load_image` - Low-level services to load pixel data from the assets +* `log` - Advanced Android logging services +* `native_app_glue` - Wrapper of the Android native_app_glue framework to implement app.nit +* `nit_activity` - Core implementation of `app.nit` on Android using a custom Java entry point +* `platform` - Triggers compilation for the android platform +* `portrait` - Config to set the portrait orientation +* `sensors` - Access Android sensors +* `toast` - Services to display a _toast_, a small popup on Android +* `vibration` - Vibration services for Android +* `wifi` - Simple wrapper of the Android WiFi services + +Then run it with: + +~~~bash +./nit_activity +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/app/README.docdown.md b/lib/app/README.docdown.md new file mode 100644 index 0000000000..e3e9d2b320 --- /dev/null +++ b/lib/app/README.docdown.md @@ -0,0 +1,61 @@ +# `app` - [[ini-desc: app]] + +[[toc: app]] + +[[doc: app::app]] + +Example from `app::http_request_example`: + +[[code: app::http_request_example]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: app]] + +### Run `app_base` + +Compile `app_base` with the following command: + +[[main-compile: app::app_base]] + +## Features + +[[uml: app | format: svg, mentities: app::app;app::app_base;app::assets;app::audio;app::data_store;app::http_request;app::ui]] + +### `audio` - Services to load and play `Sound` and `Music` from the assets folder + +[[doc: app::audio | no-synopsis]] + +### `data_store` - Key/value storage services + +[[doc: app::data_store | no-synopsis]] + +Example from `app::ui_example`: + +[[code: app::ui_example]] + +### `http_request` - HTTP request services: `AsyncHttpRequest` and `Text::http_get` + +[[doc: app::http_request | no-synopsis]] + +### `ui` - Portable UI controls for mobiles apps + +[[doc: app::ui | no-synopsis]] + +## Other features + +[[features: app | mentities: app::app_base;app::assets]] + +Then run it with: + +[[main-run: app::app_base]] + +## Authors + +This project is maintained by [[ini-maintainer: app]]. diff --git a/lib/app/README.md b/lib/app/README.md new file mode 100644 index 0000000000..401d0d908c --- /dev/null +++ b/lib/app/README.md @@ -0,0 +1,259 @@ +# `app` - _app.nit_, a framework for portable applications + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `app_base`](#Run-`app_base`) +* [Features](#Features) +* [`audio` - Services to load and play `Sound` and `Music` from the assets folder](#`audio`---Services-to-load-and-play-`Sound`-and-`Music`-from-the-assets-folder) +* [`data_store` - Key/value storage services](#`data_store`---Key/value-storage-services) +* [`http_request` - HTTP request services: `AsyncHttpRequest` and `Text::http_get`](#`http_request`---HTTP-request-services:-`AsyncHttpRequest`-and-`Text::http_get`) +* [`ui` - Portable UI controls for mobiles apps](#`ui`---Portable-UI-controls-for-mobiles-apps) +* [Other features](#Other-features) +* [Authors](#Authors) + +The features offered by this modules are common to all platforms, but +may not be available on all devices. + +Example from `app::http_request_example`: + +~~~ +# Example for the `app::http_request` main service `AsyncHttpRequest` +module http_request_example is + example + app_name "app.nit HTTP" + app_namespace "org.nitlanguage.http_example" + android_api_target 15 +end + +import app::ui +import app::http_request +import android::aware # for android_api_target + +# Simple asynchronous HTTP request to http://example.com/ displaying feedback to the window +class MyHttpRequest + super AsyncHttpRequest + + # Back reference to the window to show feedback to the user + var win: HttpRequestClientWindow + + # --- + # Config the request + + redef fun uri do return "http://example.com/" + redef fun deserialize_json do return false + + # --- + # Customize callbacks + + redef fun before + do + win.label_response.text = "Sending request..." + + # Disable button to prevent double requests + win.button_request.enabled = false + end + + redef fun on_load(data, status) + do win.label_response.text = "Received response code {status} with {data.as(Text).byte_length} bytes" + + redef fun on_fail(error) + do win.label_response.text = "Connection error: {error}" + + redef fun after do win.button_request.enabled = true +end + +# Simple window with a label and a button +class HttpRequestClientWindow + super Window + + # Root layout + var layout = new ListLayout(parent=self) + + # Button to send request + var button_request = new Button(parent=layout, text="Press to send HTTP request") + + # Label displaying feedback to user + var label_response = new Label(parent=layout, text="No response yet.") + + init do button_request.observers.add self + + redef fun on_event(event) + do + if event isa ButtonPressEvent and event.sender == button_request then + # Prepare and send request + var request = new MyHttpRequest(self) + request.start + end + end +end + +redef fun root_window do return new HttpRequestClientWindow +~~~ + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `android` - Android platform support and APIs +* `core` - Nit common library of core classes and methods +* `json` - read and write JSON formatted text +* `pthreads` - POSIX Threads support +* `serialization` - Abstract serialization services + +### Run `app_base` + +Compile `app_base` with the following command: + +~~~bash +nitc ./app_base.nit +~~~ + +## Features + +![Diagram for `app`](uml-app.svg) + +### `audio` - Services to load and play `Sound` and `Music` from the assets folder + +Get a handle to a sound using `new Sound` or `new Music` at any time. +Call `load` at or after `App::on_create` or leave it to be loaded +on demand by the first call to `play`. + +### `data_store` - Key/value storage services + +The main services is `App::data_store`, a `DataStore` holding any +serializable Nit object. + +Example from `app::ui_example`: + +~~~ +# User interface example using `app::ui` +module ui_example is + example + app_name "app.nit UI" + app_namespace "org.nitlanguage.ui_example" + android_api_min 21 + android_api_target 21 + android_manifest_activity "android:theme=\"@android:style/Theme.Material\"" +end + +import app::ui +import app::data_store +import android::aware # for android_api_target + +# Window showing off some the available controls +class UiExampleWindow + super Window + + # Root layout + var layout = new ListLayout(parent=self) + + # Some label + var some_label = new Label(parent=layout, text="Sample Window using a ListLayout.") + + # A checkbox + var checkbox = new CheckBox(parent=layout, text="A CheckBox") + + # Horizontal organization + var h_layout = new HorizontalLayout(parent=layout) + + # Description for the `user_input` + var user_input_label = new Label(parent=h_layout, text="Input some text:", align=0.5) + + # Field for the user to enter data + var user_input = new TextInput(parent=h_layout, text="Default text") + + # Button to open a new window with a ListLayout + var button_window = new Button(parent=layout, text="Open a new window") + + # URL to open + var example_url = "http://nitlanguage.org/" + + # Button to open the browser + var button_browser = new Button(parent=layout, text="Open {example_url}") + + redef fun on_event(event) + do + if event isa ButtonPressEvent then + if event.sender == button_browser then + example_url.open_in_browser + else if event.sender == button_window then + app.push_window new SecondWindow + end + else if event isa ToggleEvent then + if event.sender == checkbox then checkbox.text = if checkbox.is_checked then "Checked" else "Unchecked" + end + end +end + +# Another window with a small `VerticalLayout` +class SecondWindow + super Window + + # Root layout + var layout = new VerticalLayout(parent=self) + + # Some label + var a_label = new Label(parent=layout, text="This window uses a VerticalLayout.") + + # Another label + var another_label = new Label(parent=layout, text="Close it by tapping the back button.") +end + +redef fun root_window do return new UiExampleWindow +~~~ + +### `http_request` - HTTP request services: `AsyncHttpRequest` and `Text::http_get` + +~~~nitish +import app::http_request + +class MyHttpRequest + super AsyncHttpRequest + + redef fun uri do return "http://example.com/" + + redef fun on_load(data, status) do print "Received: {data or else "null"}" + + redef fun on_fail(error) do print "Connection error: {error}" +end + +var req = new MyHttpRequest +req.start +~~~ + +### `ui` - Portable UI controls for mobiles apps + +~~~ +import app::ui + +class MyWindow + super Window + + var layout = new ListLayout(parent=self) + var lbl = new Label(parent=layout, text="Hello world", align=0.5) + var but = new Button(parent=layout, text="Press here") + + redef fun on_event(event) do lbl.text = "Pressed!" +end + +redef fun root_window do return new MyWindow +~~~ + +## Other features + +* `app_base` - Base of the _app.nit_ framework, defines `App` +* `assets` - Portable services to load resources from the assets folder + +Then run it with: + +~~~bash +./app_base +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/array_debug/README.docdown.md b/lib/array_debug/README.docdown.md new file mode 100644 index 0000000000..5295d4340c --- /dev/null +++ b/lib/array_debug/README.docdown.md @@ -0,0 +1,9 @@ +# `array_debug` - [[ini-desc: array_debug]] + +## Features + +[[features: array_debug | mentities: array_debug::array_debug::Sys::avg_arr_len;array_debug::array_debug::Sys::avg_s_len;array_debug::array_debug::Sys::print_stats]] + +## Authors + +This project is maintained by [[ini-maintainer: array_debug]]. diff --git a/lib/array_debug/README.md b/lib/array_debug/README.md new file mode 100644 index 0000000000..110a67574b --- /dev/null +++ b/lib/array_debug/README.md @@ -0,0 +1,11 @@ +# `array_debug` - Exposes functions to help profile or debug Arrays + +## Features + +* `Sys::avg_arr_len` - Compute the average array length. +* `Sys::avg_s_len` - Compute the average string length. +* `Sys::print_stats` - Display statistics in standard output. + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/base64/README.docdown.md b/lib/base64/README.docdown.md new file mode 100644 index 0000000000..a2043b9ff2 --- /dev/null +++ b/lib/base64/README.docdown.md @@ -0,0 +1,17 @@ +# `base64` - [[ini-desc: base64]] + +[[toc: base64]] + +## Features + +[[features: base64 | mentities: base64::base64::Int::to_base64_char;base64::base64::CString::is_base64;base64::base64::CString::check_base64;base64::base64::Bytes::encode_base64;base64::base64::Bytes::decode_base64;base64::base64::Bytes::check_base64;base64::base64::Text::encode_base64;base64::base64::Text::decode_base64;base64::base64::Text::check_base64;base64::base64::Char::is_base64_char;base64::base64::Int::is_base64_char;base64::base64::Bytes::is_base64;base64::base64::Text::is_base64]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: base64]] + +## Authors + +This project is maintained by [[ini-maintainer: base64]]. diff --git a/lib/base64/README.md b/lib/base64/README.md new file mode 100644 index 0000000000..7aba81b1b3 --- /dev/null +++ b/lib/base64/README.md @@ -0,0 +1,33 @@ +# `base64` - Offers the base 64 encoding and decoding algorithms + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +## Features + +* `Text::check_base64` - Is `self` a well-formed Base64 entity ? +* `CString::check_base64` - Is `self` a well-formed Base64 entity ? +* `Bytes::check_base64` - Is `self` a well-formed Base64 entity ? +* `Bytes::decode_base64` - Decodes the receiver string to base64 using a custom padding character. +* `Text::decode_base64` - Decodes the receiver string to base64 using a custom padding character. +* `Text::encode_base64` - Encodes the receiver string to base64 using a custom padding character. +* `Bytes::encode_base64` - Encodes the receiver string to base64 using a custom padding character. +* `CString::is_base64` - Is `self` a well-formed Base64 entity ? +* `Text::is_base64` - Is `self` a well-formed Base64 entity ? +* `Bytes::is_base64` - Is `self` a well-formed Base64 entity ? +* `Int::is_base64_char` - Is `self` a valid Base64 character ? +* `Char::is_base64_char` - Is `self` a valid Base64 character ? +* `Int::to_base64_char` - Returns the `base64` equivalent of `self` + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/bcm2835/README.docdown.md b/lib/bcm2835/README.docdown.md new file mode 100644 index 0000000000..4b13f09779 --- /dev/null +++ b/lib/bcm2835/README.docdown.md @@ -0,0 +1,15 @@ +# `bcm2835` - [[ini-desc: bcm2835]] + +[[doc: bcm2835::bcm2835]] + +Example from `bcm2835::blink`: + +[[code: bcm2835::blink]] + +## Features + +[[features: bcm2835 | mentities: bcm2835::Pin;bcm2835::RPiPin;bcm2835::FunctionSelect;bcm2835::PUDControl;bcm2835::RotaryEncoder;bcm2835::HD44780;bcm2835::Switch;bcm2835::StepperMotor;bcm2835::Buzzer]] + +## Authors + +This project is maintained by [[ini-maintainer: bcm2835]]. diff --git a/lib/bcm2835/README.md b/lib/bcm2835/README.md new file mode 100644 index 0000000000..bf83c2be74 --- /dev/null +++ b/lib/bcm2835/README.md @@ -0,0 +1,43 @@ +# `bcm2835` - Services to control the bcm2835 chipset used in the Raspberry Pi + +Uses the C library by Mike McCauley available at http://www.airspayce.com/mikem/bcm2835/ + +This module targets the model B revision 1, it could be tweaked for other versions. + +Example from `bcm2835::blink`: + +~~~ +module blink is example + +import bcm2835 + +assert bcm2835_init else print "Failed to init" + +var out = new RPiPin.p1_11 +out.fsel = new FunctionSelect.outp + +for i in [0..1000[ do + out.write(true) + 500.bcm2835_delay + out.write(false) + 500.bcm2835_delay +end + +bcm2835_close +~~~ + +## Features + +* `Buzzer` +* `FunctionSelect` +* `HD44780` - Hitachi HD44780 or similar 2-4 lines LCD displays +* `PUDControl` +* `Pin` - A physical binary pin +* `RPiPin` +* `RotaryEncoder` +* `StepperMotor` +* `Switch` - Component for any kind of buttons or switches + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/binary/README.docdown.md b/lib/binary/README.docdown.md new file mode 100644 index 0000000000..3fe63d5e1a --- /dev/null +++ b/lib/binary/README.docdown.md @@ -0,0 +1,11 @@ +# `binary` - [[ini-desc: binary]] + +[[doc: binary::binary]] + +## Features + +[[features: binary | mentities: binary::BinaryStream]] + +## Authors + +This project is maintained by [[ini-maintainer: binary]]. diff --git a/lib/binary/README.md b/lib/binary/README.md new file mode 100644 index 0000000000..52eed4f5da --- /dev/null +++ b/lib/binary/README.md @@ -0,0 +1,34 @@ +# `binary` - Read and write binary data with any `Reader` and `Writer` + +~~~ +var w = new FileWriter.open("/tmp/data.bin") +w.write "hello" +w.write_int64 123456789 +w.write_byte 3 +w.write_float 1.25 +w.write_double 1.234567 +w.write_bits(true, false, true) +assert w.last_error == null +w.close + +var r = new FileReader.open("/tmp/data.bin") +assert r.read(5) == "hello" +assert r.read_int64 == 123456789 +assert r.read_byte == 3 +assert r.read_float == 1.25 +assert r.read_double == 1.234567 + +var bits = r.read_bits +assert bits[0] and not bits[1] and bits[2] + +assert r.last_error == null +r.close +~~~ + +## Features + +* `BinaryStream` - A stream of binary data + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/bitmap/README.docdown.md b/lib/bitmap/README.docdown.md new file mode 100644 index 0000000000..c96e355c3d --- /dev/null +++ b/lib/bitmap/README.docdown.md @@ -0,0 +1,19 @@ +# `bitmap` - [[ini-desc: bitmap]] + +[[toc: bitmap]] + +[[doc: bitmap::bitmap]] + +## Features + +[[features: bitmap | mentities: bitmap::Bitmap]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: bitmap]] + +## Authors + +This project is maintained by [[ini-maintainer: bitmap]]. diff --git a/lib/bitmap/README.md b/lib/bitmap/README.md new file mode 100644 index 0000000000..6c84b7a4d8 --- /dev/null +++ b/lib/bitmap/README.md @@ -0,0 +1,50 @@ +# `bitmap` - 24-bit bitmap image representation + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +~~~nitish +var bm1 = new Bitmap.load(path_to_a_bmp_file) +var bm2 = new Bitmap.with_size(400, 300) +~~~ + +The width and height attributes contain the image's width and height, +respectively. + +Individual pixels can be manipulated by calling the set_pixel function: + +~~~nitish + set_pixel(x, y, color) +~~~ + +The no-argument grayscale function converts the bitmap to grayscale and is an +implementation of this Rossetacode task: +http://rosettacode.org/wiki/Grayscale_image + +Finally, the bitmap can be saved to a file by calling save: + +~~~nitish + save(path_to_a_file) +~~~ + +For information on the bitmap format, see +http://en.wikipedia.org/wiki/BMP_file_format + +A module containing classes for manipulating bitmap images + +## Features + +* `Bitmap` - A class that represents a Bitmap image + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/bucketed_game/README.docdown.md b/lib/bucketed_game/README.docdown.md new file mode 100644 index 0000000000..c987258f9f --- /dev/null +++ b/lib/bucketed_game/README.docdown.md @@ -0,0 +1,13 @@ +# `bucketed_game` - [[ini-desc: bucketed_game]] + +[[doc: bucketed_game::bucketed_game]] + +## Features + +[[uml: bucketed_game | format: svg, mentities: bucketed_game::Turnable;bucketed_game::Bucketable;bucketed_game::Buckets;bucketed_game::GameEvent;bucketed_game::FirstTurnEvent;bucketed_game::ThinGame;bucketed_game::ThinGameTurn;bucketed_game::GameTurn;bucketed_game::Game]] + +[[features: bucketed_game | mentities: bucketed_game::Turnable;bucketed_game::Bucketable;bucketed_game::Buckets;bucketed_game::GameEvent;bucketed_game::FirstTurnEvent;bucketed_game::ThinGame;bucketed_game::ThinGameTurn;bucketed_game::GameTurn;bucketed_game::Game]] + +## Authors + +This project is maintained by [[ini-maintainer: bucketed_game]]. diff --git a/lib/bucketed_game/README.md b/lib/bucketed_game/README.md new file mode 100644 index 0000000000..0bdfc124ed --- /dev/null +++ b/lib/bucketed_game/README.md @@ -0,0 +1,27 @@ +# `bucketed_game` - Game framework with an emphasis on efficient event coordination + +Provides basic game logic entities to manage a game where the logic is executed by turns: +`Game`, `GameTurn`, `GameEvent`, `Turnable`. +Also offers a bucket system to plan future events at a known number of turns in the future: +`Bucketable` and the services `act_next` and `act_in`. + +Efficiently support large number of entities with rare or sparse actions, +such as a forest with many individual trees growing slowly. + +## Features + +![Diagram for `bucketed_game`](uml-bucketed_game.svg) + +* `Bucketable` - Something acting on the game from time to time +* `Buckets` - Optimized organization of `Bucketable` instances +* `FirstTurnEvent` - Event raised at the first turn +* `Game` - Full game logic +* `GameEvent` - Game related event +* `GameTurn` - Game turn on the full logic +* `ThinGame` - Game logic on the client +* `ThinGameTurn` - Game turn on the client +* `Turnable` - Something acting on the game + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/c/README.doREADMEdown.md b/lib/c/README.doREADMEdown.md new file mode 100644 index 0000000000..54d3fde309 --- /dev/null +++ b/lib/c/README.doREADMEdown.md @@ -0,0 +1,11 @@ +# `c` - [[ini-desc: c]] + +## Features + +[[uml: c | format: svg, mentities: c::CArray;c::NativeCArray;c::CIntArray;c::NativeCIntArray;c::CUInt16Array;c::NativeCUInt16Array;c::CByteArray;c::NativeCByteArray;c::CCStringArray;c::NativeCStringArray]] + +[[features: c | mentities: c::CArray;c::NativeCArray;c::CIntArray;c::NativeCIntArray;c::CUInt16Array;c::NativeCUInt16Array;c::CByteArray;c::NativeCByteArray;c::CCStringArray;c::NativeCStringArray]] + +## Authors + +This project is maintained by [[ini-maintainer: c]]. diff --git a/lib/c/README.md b/lib/c/README.md new file mode 100644 index 0000000000..39517cbb12 --- /dev/null +++ b/lib/c/README.md @@ -0,0 +1,20 @@ +# `c` - Structures and services for compatibility with the C language + +## Features + +![Diagram for `c`](uml-c.svg) + +* `CArray` - A thin wrapper around a `NativeCArray` adding length information +* `CByteArray` - Wrapper around an array of `unsigned char` in C (`unsigned char*`) with length and destroy state +* `CCStringArray` - Wrapper around an array of `CString` in C (`char**`) with length and destroy state. +* `CIntArray` - Wrapper around an array of `int` in C (`int*`) with length and destroy state +* `CUInt16Array` - Wrapper of a C array of type `uint16_t*` with length and destroy state +* `NativeCArray` - A native C array, as in a pointer to the first element of the array +* `NativeCByteArray` - An array of `unsigned char` in C (`unsigned char*`) +* `NativeCIntArray` - An array of `int` in C (`int*`) +* `NativeCStringArray` - An array of `CString` in C (`char**`) +* `NativeCUInt16Array` - An array of `uint16_t` in C + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/cartesian/README.docdown.md b/lib/cartesian/README.docdown.md new file mode 100644 index 0000000000..3b9a0db63e --- /dev/null +++ b/lib/cartesian/README.docdown.md @@ -0,0 +1,23 @@ +# `cartesian` - [[ini-desc: cartesian]] + +[[toc: cartesian]] + +[[doc: cartesian::cartesian]] + +## Features + +### `Cartesian` - A view of a Cartesian-product collection over two collections. + +[[doc: cartesian::Cartesian | no-synopsis]] + +Properties: + +[[features: cartesian::Cartesian | min-visibility: public, no-redef]] + +## Other features + +[[features: cartesian | mentities: cartesian::Pair;cartesian::CartesianIterator]] + +## Authors + +This project is maintained by [[ini-maintainer: cartesian]]. diff --git a/lib/cartesian/README.md b/lib/cartesian/README.md new file mode 100644 index 0000000000..64998b1063 --- /dev/null +++ b/lib/cartesian/README.md @@ -0,0 +1,80 @@ +# `cartesian` - Memory-efficient Cartesian products on heterogeneous collections + +* [Features](#Features) +* [`Cartesian` - A view of a Cartesian-product collection over two collections.](#`Cartesian`---A-view-of-a-Cartesian-product-collection-over-two-collections.) +* [Other features](#Other-features) +* [Authors](#Authors) + +This module is a proof-of-concept to propose memory-efficient views on collections. + +This is a specific alternative to `combinations`, that focuses only highly efficient +Cartesian products between collections of different types. + +Collection[Int] X Collection[String] -> Collection[(Int,String)] + +However, in Nit, there in no native *tuple* type. +So we need a first building block, a pair. + +## Features + +### `Cartesian` - A view of a Cartesian-product collection over two collections. + +A Cartesian product over two collections is just a collection of pairs. +Therefore, this view *contains* all the pairs of elements constructed by associating each +element of the first collection to each element of the second collection. + +However the view is memory-efficient and the pairs are created only when needed. + +A simple Cartesian product + +~~~~ +var c1 = [1,2] +var c2 = ["a","b","c"] +var c12 = new Cartesian[Int,String](c1, c2) +assert c12.length == 6 +assert c12.join(";") == "(1,a);(1,b);(1,c);(2,a);(2,b);(2,c)" # All the 6 pairs +~~~~ + +Note: because it is a view, changes on the base collections are reflected on the view. + +E.g. c12 is a view on c1 and c2, so if c1 changes, then c12 "changes". + +~~~~ +assert c2.pop == "c" +assert c12.length == 4 +assert c12.join(";") == "(1,a);(1,b);(2,a);(2,b)" # All the 4 remaining pairs +~~~~ + +Cartesian objects are collections, so can be used to build another Cartesian object. + +~~~~ +var c3 = [1000..2000[ +var c123 = new Cartesian[Pair[Int,String],Int](c12, c3) +assert c123.length == 4000 +~~~~ + +All methods of Collection are inherited, it is so great! + +E.g. search elements? + +~~~~ +var p12 = new Pair[Int,String](2,"b") +assert c12.has(p12) == true +var p123 = new Pair[Pair[Int, String], Int](p12, 1500) +var p123bis = new Pair[Pair[Int, String], Int](p12, 0) +assert c123.has(p123) == true +assert c123.has(p123bis) == false +~~~~ + +Properties: + +* `Cartesian::swap` - Returns a new Cartesian where the first collection is the second. + +## Other features + +* `CartesianIterator` - An iterator over a `Cartesian`-product collection. +* `Pair` - A simple read-only pair of two elements `e` and `f`. + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/cocoa/README.docdown.md b/lib/cocoa/README.docdown.md new file mode 100644 index 0000000000..70ae9c82fe --- /dev/null +++ b/lib/cocoa/README.docdown.md @@ -0,0 +1,17 @@ +# `cocoa` - [[ini-desc: cocoa]] + +[[doc: cocoa::cocoa]] + +Example from `cocoa::cocoa_extern_types`: + +[[code: cocoa::cocoa_extern_types]] + +## Features + +[[uml: cocoa | format: svg, mentities: cocoa::app_kit;cocoa::cocoa;cocoa::foundation]] + +[[features: cocoa | mentities: cocoa::app_kit;cocoa::foundation]] + +## Authors + +This project is maintained by [[ini-maintainer: cocoa]]. diff --git a/lib/cocoa/README.md b/lib/cocoa/README.md new file mode 100644 index 0000000000..bd12c7d096 --- /dev/null +++ b/lib/cocoa/README.md @@ -0,0 +1,49 @@ +# `cocoa` - Cocoa API, the development layer of OS X + +This module is only compatible with OS X. + +This wrapper of the Cocoa API regroups the Foundation Kit and the +Application Kit. + +Example from `cocoa::cocoa_extern_types`: + +~~~ +# Test extern classes from the Cocoa framework and extern factories +module cocoa_extern_types is example + +import cocoa + +in "ObjC Header" `{ + // for `NSString::hello` + #import +`} + +redef extern class NSString + + # Additionnal factory + new hello in "ObjC" `{ return @"Factory Hello"; `} +end + +# Print a custom string to the log +fun nslog(text: NSString) in "ObjC" `{ + NSLog(text); +`} + +nslog "Hello using to_nsstring".to_nsstring +nslog new NSString.hello + +var msg_box = new NSAlert +msg_box.message_text = "From Nit".to_nsstring +if "NIT_TESTING".environ != "true" then msg_box.run_modal +~~~ + +## Features + +![Diagram for `cocoa`](uml-cocoa.svg) + +* `app_kit` - The Application Kit provides services to create GUI +* `foundation` - The Foundation Kit provides basic Objective-C classes and structures + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/combinations/README.docdown.md b/lib/combinations/README.docdown.md new file mode 100644 index 0000000000..fe5dfb9e79 --- /dev/null +++ b/lib/combinations/README.docdown.md @@ -0,0 +1,19 @@ +# `combinations` - [[ini-desc: combinations]] + +[[toc: combinations]] + +[[doc: combinations::combinations]] + +## Features + +### `CartesianCollection` - A view of a Cartesian-product collection over homogeneous collections. + +[[doc: combinations::CartesianCollection | no-synopsis]] + +### `CombinationCollection` - A view of some combinations over a base collections. + +[[doc: combinations::CombinationCollection | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: combinations]]. diff --git a/lib/combinations/README.md b/lib/combinations/README.md new file mode 100644 index 0000000000..54334e8dfa --- /dev/null +++ b/lib/combinations/README.md @@ -0,0 +1,116 @@ +# `combinations` - Memory-efficient Cartesian products, combinations and permutation on collections + +* [Features](#Features) +* [`CartesianCollection` - A view of a Cartesian-product collection over homogeneous collections.](#`CartesianCollection`---A-view-of-a-Cartesian-product-collection-over-homogeneous-collections.) +* [`CombinationCollection` - A view of some combinations over a base collections.](#`CombinationCollection`---A-view-of-some-combinations-over-a-base-collections.) +* [Authors](#Authors) + +This module offers memory-efficient views on combinatoric collections. +Methods of the views create objects only when needed. +Moreover, produced objects during iterations are free to be collected and +their memory reused. + +This enable these views and method to works with very combinatoric large collections. + +When small combinatoric views need to be kept in memory (for fast access by example). +The `Collection::to_a` method and other related factories can be used to transform +the combinatoric views into extensive collections, + +## Features + +### `CartesianCollection` - A view of a Cartesian-product collection over homogeneous collections. + +Therefore, this view *generates* all the sequences of elements constructed by associating +en element for each one of the original collections. + +It is equivalent to doing nesting `for` for each collection. + +~~~~ +var xs = [1, 2, 3] +var ys = [8, 9] +var xys = new CartesianCollection[Int]([xs, ys]) +assert xys.length == 6 +assert xys.to_a == [[1,8], [1,9], [2,8], [2,9], [3,8], [3,9]] +~~~~ + +The pattern of the generate sequences produces a lexicographical order. + +Because it is a generator, it is memory-efficient and the sequences are created only when needed. + +Note: because it is a view, changes on the base collections are reflected on the view. + +~~~~ +assert xs.pop == 3 +assert ys.pop == 9 +assert xys.to_a == [[1,8], [2,8]] +~~~~ + +### `CombinationCollection` - A view of some combinations over a base collections. + +This view *generates* some combinations and permutations on a collection. + +By default, the generated sequences are combinations: + +* each sequence has a length of `repeat` +* elements are in sorted order (see `are_sorted` for details) +* no repeated element (see `are_unique` for details) + +~~~~ +var xs = [1, 2, 3] +var cxs = new CombinationCollection[Int](xs, 2) +assert cxs.length == 3 +assert cxs.to_a == [[1,2], [1,3], [2,3]] +~~~~ + +Other kind of combinations can be generated by tweaking the attributes `are_sorted` and `are_unique`. + +* for permutation: + +~~~~ +cxs.are_sorted = false +cxs.are_unique = true +assert cxs.length == 6 +assert cxs.to_a == [[1,2], [1,3], [2,1], [2,3], [3,1], [3,2]] +~~~~ + +* for combinations with replacement: + +~~~~ +cxs.are_sorted = true +cxs.are_unique = false +assert cxs.length == 6 +assert cxs.to_a == [[1,1], [1,2], [1,3], [2,2], [2,3], [3,3]] +~~~~ + +* for product: + +~~~~ +cxs.are_sorted = false +cxs.are_unique = false +assert cxs.length == 9 +assert cxs.to_a == [[1,1], [1,2], [1,3], [2,1], [2,2], [2,3], [3,1], [3,2], [3,3]] +~~~~ + +However, in the last case, a faster alternative is to use `CartesianCollection`: + +~~~~ +var cp = new CartesianCollection[Int]([xs] * 2) +assert cp.to_a == cxs.to_a +~~~~ + +As seen in the examples, the patterns of the generated sequences produce a lexicographical order. + +Because it is a generator, it is memory-efficient and the sequences are created only when needed. + +Note: because it is a view, changes on the base collection are reflected on the view. + +~~~~ +assert xs.pop == 3 +cxs.are_sorted = true +cxs.are_unique = true +assert cxs.to_a == [[1,2]] +~~~~ + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/config/README.docdown.md b/lib/config/README.docdown.md new file mode 100644 index 0000000000..3f350272e2 --- /dev/null +++ b/lib/config/README.docdown.md @@ -0,0 +1,27 @@ +# `config` - [[ini-desc: config]] + +[[toc: config]] + +[[doc: config::config]] + +## Features + +### `Config` - Basic configuration class + +[[doc: config::Config | no-synopsis]] + +Properties: + +[[features: config::Config | min-visibility: public, no-redef]] + +### `IniConfig` - Configuration class based on a INI file. + +[[doc: config::IniConfig | no-synopsis]] + +Properties: + +[[features: config::IniConfig | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: config]]. diff --git a/lib/config/README.md b/lib/config/README.md new file mode 100644 index 0000000000..5173bc6f83 --- /dev/null +++ b/lib/config/README.md @@ -0,0 +1,217 @@ +# `config` - Configuration options for nit tools and apps + +* [Features](#Features) +* [`Config` - Basic configuration class](#`Config`---Basic-configuration-class) +* [`IniConfig` - Configuration class based on a INI file.](#`IniConfig`---Configuration-class-based-on-a-INI-file.) +* [Authors](#Authors) + +This module provides basic services for options handling in your Nit programs. + +## Basic configuration holder + +The `Config` class can be used as a simple option holder and processor: + +~~~ +import config + +# Create a new config option +var opt_my = new OptionString("My option", "--my") + +# Create the config and add the option +var config = new Config +config.add_option(opt_my) + +# Parse the program arguments, usually `args` +config.parse_options(["--my", "myOption", "arg1", "arg2"]) + +# Access the options and args +assert opt_my.value == "myOption" +assert config.args == ["arg1", "arg2"] +~~~ + +## Custom configuration class + +Instead of using basic `Config` instances, it is better to define new sublcasses +to store options and define custom services. + +~~~ +import config + +class MyConfig + super Config + + var opt_my = new OptionString("My option", "--my") + + init do + super + tool_description = "Usage: MyExample [OPTION]... [ARGS]..." + add_option(opt_my) + end + + fun my: String do return opt_my.value or else "Default value" +end + +var config = new MyConfig +config.parse_options(["--my", "myOption", "arg1", "arg2"]) + +assert config.my == "myOption" +assert config.args == ["arg1", "arg2"] +~~~ + +We define the `my` method to provide an elegant shortcut to `opt_my.value` +and define the default value if the option was not set by the user. + +The `tool_description` attribute is used to set the `usage` header printed when +the user request the `help` message. + +~~~ +config.parse_options(["-h"]) +if config.help then + config.usage + exit 0 +end +~~~ + +This will display the tool usage like this: + +~~~raw +Usage: MyExample [OPTION]... [ARGS]... + -h, --help Show this help message + --my My option +~~~ + +## Configuration with `ini` file + +The `IniConfig` class extends `Config` to add an easy way to link your +configuration to an ini file. + +~~~ +class MyIniConfig + super IniConfig + + var opt_my = new OptionString("My option", "--my") + + init do + super + tool_description = "Usage: MyExample [OPTION]... [ARGS]..." + opts.add_option(opt_my) + end + + fun my: String do return opt_my.value or else ini["my"] or else "Default" +end +~~~ + +This time, we define the `my` method to return the option value or the ini +if no option was passed. Finally, if no ini value can be found, we return the +default value. + +By default, `IniConfig` looks at a `config.ini` file in the execution directory. +This can be overrided in multiple ways. + +First by the app user by setting the `--config` option: + +~~~ +var config = new MyIniConfig +config.parse_options(["--config", "my_config.ini"]) + +assert config.config_file == "my_config.ini" +~~~ + +Default config file can also be changed by the library client through the +`default_config_file` attribute: + +~~~ +config = new MyIniConfig +config.default_config_file = "my_config.ini" +config.parse_options(["arg"]) + +assert config.config_file == "my_config.ini" +~~~ + +Or by the library developper in the custom config class: + +~~~ +class MyCustomIniConfig + super IniConfig + + redef var default_config_file = "my_config.ini" +end + +var config = new MyCustomIniConfig +config.parse_options(["arg"]) + +assert config.config_file == "my_config.ini" +~~~ + +## Features + +### `Config` - Basic configuration class + +~~~ +import config + +class MyConfig + super Config + + var opt_my = new OptionString("My option", "--my") + + init do + super + tool_description = "Usage: MyExample [OPTION]... [ARGS]..." + opts.add_option(opt_my) + end + + fun my: String do return opt_my.value or else "Default value" +end + +var config = new MyConfig +config.parse_options(["--my", "hello", "arg1", "arg2"]) +assert config.my == "hello" +assert config.args == ["arg1", "arg2"] +~~~ + +Properties: + +* `Config::add_option` - Add an option to `self` +* `Config::args` - Return the remaining args once options are parsed by `from_args` +* `Config::help` - Was the `--help` option requested? +* `Config::parse_options` - Initialize `self` options from `args` +* `Config::stub_man_options` - Generate a manpage stub from `self` +* `Config::usage` - Display `tool_description` and options usage in console + +### `IniConfig` - Configuration class based on a INI file. + +~~~ +class MyIniConfig + super IniConfig + + var opt_my = new OptionString("My option", "--my") + + init do + super + tool_description = "Usage: MyExample [OPTION]... [ARGS]..." + opts.add_option(opt_my) + end + + fun my: String do return opt_my.value or else ini["my"] or else "Default" +end + +var config = new MyIniConfig +config.default_config_file = "my_config.ini" +config.parse_options(args) + +if config.help then + config.usage + exit 0 +end + +assert config.my == "Default" +~~~ + +Properties: + +* `IniConfig::config_file` - Return the config file path from options or the default + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/console/README.docdown.md b/lib/console/README.docdown.md new file mode 100644 index 0000000000..de7ade78b2 --- /dev/null +++ b/lib/console/README.docdown.md @@ -0,0 +1,35 @@ +# `console` - [[ini-desc: console]] + +[[toc: console]] + +[[doc: console::console]] + +## Features + +### `TermClearDisplay` - ANSI/VT100 code to clear the entire display and move the cursor to the top left of screen (ED 2). + +[[doc: console::TermClearDisplay | no-synopsis]] + +### `TermCharFormat` - ANSI/VT100 code to change character look (SGR). + +[[doc: console::TermCharFormat | no-synopsis]] + +Properties: + +[[features: console::TermCharFormat | min-visibility: public, no-redef]] + +### `TermProgress` - A dynamic progress bar displayable in console. + +[[doc: console::TermProgress | no-synopsis]] + +Properties: + +[[features: console::TermProgress | min-visibility: public, no-redef]] + +## Other features + +[[features: console | mentities: console::TermEscape;console::TermDirectionalMove;console::TermMoveUp;console::TermMoveDown;console::TermMoveFoward;console::TermMoveBackward;console::TermMove;console::TermEraseDisplayDown;console::TermEraseDisplayUp;console::TermEraseLineFoward;console::TermEraseLineBackward;console::TermClearLine;console::TermSaveCursor;console::TermRestoreCursor]] + +## Authors + +This project is maintained by [[ini-maintainer: console]]. diff --git a/lib/console/README.md b/lib/console/README.md new file mode 100644 index 0000000000..93fb14b3ac --- /dev/null +++ b/lib/console/README.md @@ -0,0 +1,122 @@ +# `console` - Defines some ANSI Terminal Control Escape Sequences + +* [Features](#Features) +* [`TermClearDisplay` - ANSI/VT100 code to clear the entire display and move the cursor to the top left of screen (ED 2).](#`TermClearDisplay`---ANSI/VT100-code-to-clear-the-entire-display-and-move-the-cursor-to-the-top-left-of-screen-(ED-2).) +* [`TermCharFormat` - ANSI/VT100 code to change character look (SGR).](#`TermCharFormat`---ANSI/VT100-code-to-change-character-look-(SGR).) +* [`TermProgress` - A dynamic progress bar displayable in console.](#`TermProgress`---A-dynamic-progress-bar-displayable-in-console.) +* [Other features](#Other-features) +* [Authors](#Authors) + +The color methods (e.g. `Text::green`) format the text to appear colored +in a ANSI/VT100 terminal. By default, this coloring is skipped if stdout +is not a TTY, but it can be forced by setting `force_console_colors = true`. + +## Features + +### `TermClearDisplay` - ANSI/VT100 code to clear the entire display and move the cursor to the top left of screen (ED 2). + +Note: Some terminals always move the cursor when the screen is cleared. So we +force this behaviour to ensure interoperability of the code. + +### `TermCharFormat` - ANSI/VT100 code to change character look (SGR). + +By default, resets everything to the terminal’s defaults. + +Note: + +The escape sequence inserted at the end of the string by terminal-related +methods of `String` resets all character attributes to the terminal’s +defaults. So, when combining format `a` and `b`, something like +`("foo".a + " bar").b` will not work as expected, but `"foo".a.b + " bar".b` +will. You may also use `TermCharFormat` (this class). + +Usage example: + + print "{(new TermCharFormat).yellow_fg.bold}a{(new TermCharFormat).yellow_fg}b{new TermCharFormat}" + +Properties: + +* `TermCharFormat::black_bg` - Apply a black background and return `self`. +* `TermCharFormat::black_fg` - Apply a black foreground and return `self`. +* `TermCharFormat::blink` - Apply blinking or bold weight and return `self`. +* `TermCharFormat::blue_bg` - Apply a blue background and return `self`. +* `TermCharFormat::blue_fg` - Apply a blue foreground and return `self`. +* `TermCharFormat::bold` - Apply bold weight and return `self`. +* `TermCharFormat::cyan_bg` - Apply a cyan background and return `self`. +* `TermCharFormat::cyan_fg` - Apply a cyan foreground and return `self`. +* `TermCharFormat::default` - Apply normal (default) format and return `self`. +* `TermCharFormat::default_bg` - Apply the default background and return `self`. +* `TermCharFormat::default_fg` - Apply the default foreground and return `self`. +* `TermCharFormat::from` - Copies the attributes from the specified format. +* `TermCharFormat::green_bg` - Apply a green background and return `self`. +* `TermCharFormat::green_fg` - Apply a green foreground and return `self`. +* `TermCharFormat::inverse` - Apply reverse video and return `self`. +* `TermCharFormat::magenta_bg` - Apply a magenta background and return `self`. +* `TermCharFormat::magenta_fg` - Apply a magenta foreground and return `self`. +* `TermCharFormat::normal_weight` - Apply normal weight and return `self`. +* `TermCharFormat::not_underlined` - Add the attribute that disable underlining and return `self`. +* `TermCharFormat::positive` - Add the attribute that disable reverse video and return `self`. +* `TermCharFormat::red_bg` - Apply a red background and return `self`. +* `TermCharFormat::red_fg` - Apply a red foreground and return `self`. +* `TermCharFormat::steady` - Add the attribute that disable blinking and return `self`. +* `TermCharFormat::underline` - Apply underlining and return `self`. +* `TermCharFormat::white_bg` - Apply a white background and return `self`. +* `TermCharFormat::white_fg` - Apply a white foreground and return `self`. +* `TermCharFormat::yellow_bg` - Apply a yellow background and return `self`. +* `TermCharFormat::yellow_fg` - Apply a yellow foreground and return `self`. + +### `TermProgress` - A dynamic progress bar displayable in console. + +Example: + +~~~nitish +var max = 10 +var current = 0 +var pb = new TermProgress(max, current) + +pb.display +for i in [current + 1 .. max] do + nanosleep(1, 0) + pb.update(i) +end + +print "\ndone" +~~~ + +Progress bar can accept metadata to display a small amount of data. + +Example with metadata: + +~~~nitish +var pb = new TermProgress(10, 0) +for i in [0..10] do + pb.update(i, "Step {i}") +end +~~~ + +Properties: + +* `TermProgress::current_percentage` - Get the current percent value. +* `TermProgress::display` - Display the progress bar. +* `TermProgress::update` - Update and display the progress bar. + +## Other features + +* `TermClearLine` - ANSI/VT100 code to clear everything in the current line (EL 2). +* `TermDirectionalMove` - Abstract class of the ANSI/VT100 escape sequences for directional moves. +* `TermEraseDisplayDown` - ANSI/VT100 code to clear from the cursor to the end of the screen (ED 0). +* `TermEraseDisplayUp` - ANSI/VT100 code to clear from the cursor to the beginning of the screen (ED 1). +* `TermEraseLineBackward` - ANSI/VT100 code to erase anything before the cursor in the line (EL 1). +* `TermEraseLineFoward` - ANSI/VT100 code to erase anything after the cursor in the line (EL 0). +* `TermEscape` - A ANSI/VT100 escape sequence. +* `TermMove` - ANSI/VT100 code to move the cursor at the specified position (CUP). +* `TermMoveBackward` - ANSI/VT100 code to move the cursor backward by `magnitude` columns (CUB). +* `TermMoveDown` - ANSI/VT100 code to move the cursor down by `magnitude` rows (CUD). +* `TermMoveFoward` - ANSI/VT100 code to move the cursor forward by `magnitude` columns (CUF). +* `TermMoveUp` - ANSI/VT100 code to move the cursor up by `magnitude` rows (CUU). +* `TermRestoreCursor` - ANSI/VT100 code to restore the current cursor position (RCP). +* `TermSaveCursor` - ANSI/VT100 code to save the current cursor position (SCP). + +## Authors + +This project is maintained by **Jean-Christophe Beaupré **. diff --git a/lib/core/README.docdown.md b/lib/core/README.docdown.md new file mode 100644 index 0000000000..04c1471d27 --- /dev/null +++ b/lib/core/README.docdown.md @@ -0,0 +1,40 @@ +# `core` - [[ini-desc: core]] + +[[toc: core]] + +## Features + +[[uml: core | format: svg, mentities: core>;core>codecs>;core>collection>;core>text>]] + +### `fixed_ints` - Basic integers of fixed-precision + +[[doc: core::fixed_ints | no-synopsis]] + +### `kernel` - Most basic classes and methods. + +[[doc: core::kernel | no-synopsis]] + +### `queue` - Queuing data structures and wrappers + +[[doc: core::queue | no-synopsis]] + +### `re` - Regular expression support for all services based on `Pattern` + +[[doc: core::re | no-synopsis]] + +## Other features + +[[features: core | mentities: core::bitset;core::bytes;core::environ;core::error;core::exec;core::file;core::gc;core::math;core::numeric;core::protocol;core::stream;core::time]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: core]] + +## Authors + +This project is maintained by [[ini-maintainer: core]]. + +Thanks to the contribution of: +[[ini-contributors: core]] diff --git a/lib/core/README.md b/lib/core/README.md new file mode 100644 index 0000000000..58092a2285 --- /dev/null +++ b/lib/core/README.md @@ -0,0 +1,100 @@ +# `core` - Nit common library of core classes and methods + +* [Features](#Features) +* [`fixed_ints` - Basic integers of fixed-precision](#`fixed_ints`---Basic-integers-of-fixed-precision) +* [`kernel` - Most basic classes and methods.](#`kernel`---Most-basic-classes-and-methods.) +* [`queue` - Queuing data structures and wrappers](#`queue`---Queuing-data-structures-and-wrappers) +* [`re` - Regular expression support for all services based on `Pattern`](#`re`---Regular-expression-support-for-all-services-based-on-`Pattern`) +* [Other features](#Other-features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +## Features + +![Diagram for `core`](uml-core.svg) + +### `fixed_ints` - Basic integers of fixed-precision + +All classes defined here have C-equivalents and the semantics of their +operations are the same as C's + +* Int8 => int8_t +* Int16 => int16_t +* UInt16 => uint16_t +* Int32 => int32_t +* UInt32 => uint32_t + +NOTE: No UInt8 is provided as Byte is the same +SEE: kernel::Byte + +HOW TO USE: +All classes can be instanciated via a literal rule. +Namely, a suffix to append after the literal integer. + +* Int8 => i8 +* Byte => u8 +* Int16 => i16 +* UInt16 => u16 +* Int32 => i32 +* UInt32 => u32 + +### `kernel` - Most basic classes and methods. + +This module is the root of the module hierarchy. +It provides a very minimal set of classes and services used as a +foundation to define other classes and methods. + +### `queue` - Queuing data structures and wrappers + +Topics: + +* `Queue` +* `Sequence::as_lifo` +* `Sequence::as_fifo` +* `SimpleCollection::as_random` +* `MinHeap` + +### `re` - Regular expression support for all services based on `Pattern` + +Implemented using libc regular expressions. + +The main entities are `Text::to_re` and `Regex`. + +## Other features + +* `bitset` - Services to handle BitSet +* `bytes` - Services for byte streams and arrays +* `environ` - Access to the environment variables of the process +* `error` - Standard error-management infrastructure. +* `exec` - Invocation and management of operating system sub-processes. +* `file` - File manipulations (create, read, write, etc.) +* `gc` - Access to the Nit internal garbage collection mechanism +* `math` - Mathematical operations +* `numeric` - Advanced services for `Numeric` types +* `protocol` +* `stream` - Input and output streams of characters +* `time` - Management of time and dates + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Jean Privat **. + +Thanks to the contribution of: + +* **Jean-Christophe Beaupré ** +* **Romain Chanoir ** +* **Christophe Gigax ** +* **Frédéric Vachon ** +* **Jean-Sebastien Gelinas ** +* **Alexandre Blondin Massé ** +* **Johan Kayser ** +* **Johann Dubois ** +* **Julien Pagès ** diff --git a/lib/counter/README.docdown.md b/lib/counter/README.docdown.md new file mode 100644 index 0000000000..176c89538e --- /dev/null +++ b/lib/counter/README.docdown.md @@ -0,0 +1,19 @@ +# `counter` - [[ini-desc: counter]] + +[[toc: counter]] + +[[doc: counter::Counter]] + +## Features + +### `Counter` - A counter counts occurrences of things + +[[doc: counter::Counter | no-synopsis]] + +Properties: + +[[features: counter::Counter | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: counter]]. diff --git a/lib/counter/README.md b/lib/counter/README.md new file mode 100644 index 0000000000..3ec904b7f2 --- /dev/null +++ b/lib/counter/README.md @@ -0,0 +1,63 @@ +# `counter` - Simple numerical statistical analysis and presentation + +* [Features](#Features) +* [`Counter` - A counter counts occurrences of things](#`Counter`---A-counter-counts-occurrences-of-things) +* [Authors](#Authors) + +~~~ +var c = new Counter[String].from(["a", "a", "b", "b", "b", "c"]) +assert c["a"] == 2 +assert c["b"] == 3 +assert c["c"] == 1 +assert c["d"] == 0 +~~~ + +The counter class can also be used to gather statistical informations. + +~~~~ +assert c.length == 3 # because 3 distinct values +assert c.max == "b" # because "b" has the most count (3) +assert c.avg == 2.0 # because it is the mean of the counts +~~~~ + +## Features + +### `Counter` - A counter counts occurrences of things + +~~~ +var c = new Counter[String].from(["a", "a", "b", "b", "b", "c"]) +assert c["a"] == 2 +assert c["b"] == 3 +assert c["c"] == 1 +assert c["d"] == 0 +~~~ + +The counter class can also be used to gather statistical informations. + +~~~~ +assert c.length == 3 # because 3 distinct values +assert c.max == "b" # because "b" has the most count (3) +assert c.avg == 2.0 # because it is the mean of the counts +~~~~ + +Properties: + +* `Counter::avg` - Values average (aka. arithmetic mean) +* `Counter::dec` - Decrement the value of `e` by 1 +* `Counter::dec_all` - Decrement the value for each element of `es` +* `Counter::entropy` - The information entropy (Shannon entropy) of the elements in the counter (in bits). +* `Counter::from` - A new Counter initialized with `inc_all`. +* `Counter::inc` - Count one more occurrence of `e` +* `Counter::inc_all` - Count one more for each element of `es` +* `Counter::max` - Return the element with the highest value (aka. the mode) +* `Counter::min` - Return the couple with the lowest value +* `Counter::pack` - Packs elements into separate arrays based on their occurences +* `Counter::print_content` - Prints the content of the counter along with statistics +* `Counter::print_elements` - Display up to `count` most used elements and `count` least used elements +* `Counter::print_summary` - Display statistical information +* `Counter::sort` - Return an array of elements sorted by occurrences +* `Counter::std_dev` - The standard derivation of the counter values + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/cpp/README.docdown.md b/lib/cpp/README.docdown.md new file mode 100644 index 0000000000..ac3302de4a --- /dev/null +++ b/lib/cpp/README.docdown.md @@ -0,0 +1,9 @@ +# `cpp` - [[ini-desc: cpp]] + +## Features + +[[features: cpp | mentities: cpp::CppString]] + +## Authors + +This project is maintained by [[ini-maintainer: cpp]]. diff --git a/lib/cpp/README.md b/lib/cpp/README.md new file mode 100644 index 0000000000..8f81f45cd9 --- /dev/null +++ b/lib/cpp/README.md @@ -0,0 +1,9 @@ +# `cpp` - Services for compatibility with C++ code and libraries + +## Features + +* `CppString` - A pointer to a C++ std::string instance + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/crapto/README.docdown.md b/lib/crapto/README.docdown.md new file mode 100644 index 0000000000..3ba1d5c76b --- /dev/null +++ b/lib/crapto/README.docdown.md @@ -0,0 +1,27 @@ +# `crapto` - [[ini-desc: crapto]] + +[[toc: crapto]] + +## Features + +[[uml: crapto | format: svg, mentities: crapto::crapto;crapto::english_utils;crapto::xor]] + +### `Text::english_scoring` - Score `self` according to english's letter frequency. + +[[doc: crapto::english_utils::Text::english_scoring | no-synopsis]] + +### `RepeatingKeyXorCipher::find_key` - Attempts to find the key by using frequency analysis on the resulting plaintexts. + +[[doc: crapto::xor::RepeatingKeyXorCipher::find_key | no-synopsis]] + +Example from `crapto::repeating_key_xor_solve`: + +[[code: crapto::repeating_key_xor_solve]] + +## Other features + +[[features: crapto | mentities: crapto::xor::SingleByteXorCipher::find_key]] + +## Authors + +This project is maintained by [[ini-maintainer: crapto]]. diff --git a/lib/crapto/README.md b/lib/crapto/README.md new file mode 100644 index 0000000000..910df2a440 --- /dev/null +++ b/lib/crapto/README.md @@ -0,0 +1,60 @@ +# `crapto` - Cryptographic attacks and utilities + +* [Features](#Features) +* [`Text::english_scoring` - Score `self` according to english's letter frequency.](#`Text::english_scoring`---Score-`self`-according-to-english's-letter-frequency.) +* [`RepeatingKeyXorCipher::find_key` - Attempts to find the key by using frequency analysis on the resulting plaintexts.](#`RepeatingKeyXorCipher::find_key`---Attempts-to-find-the-key-by-using-frequency-analysis-on-the-resulting-plaintexts.) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `crapto`](uml-crapto.svg) + +### `Text::english_scoring` - Score `self` according to english's letter frequency. + + assert "aaaa".english_scoring > "bbbb".english_scoring + +### `RepeatingKeyXorCipher::find_key` - Attempts to find the key by using frequency analysis on the resulting plaintexts. + +`min_keylength` and `max_keylength` are limits as to what key lengths are tested. +`considered_keylength_count` is the number of best key lengths that are kept to be +analysed by the SingleByteXor frequency analysis. + +Example from `crapto::repeating_key_xor_solve`: + +~~~ +module repeating_key_xor_solve is example + +import base64 +import crapto + +# Check usage +if args.length != 1 then + print "Usage: repeating_key_xor_solve " + exit 1 +end + +# Read the cipher from the file +var cipher_bytes = args[0].to_path.read_all_bytes.decode_base64 + +# Create a RepeatingKeyXorCipher object to manipulate your ciphertext +var xorcipher = new RepeatingKeyXorCipher +xorcipher.ciphertext = cipher_bytes + +# Try to find the best candidate key +xorcipher.find_key + +# Decrypt the cipher according to the found key +xorcipher.decrypt + +# Check the resulting plaintext out... +print xorcipher.plaintext +~~~ + +## Other features + +* `SingleByteXorCipher::find_key` - Tries to find key using frequency analysis on all possible plaintexts. + +## Authors + +This project is maintained by **Philippe Pépos Petitclerc **. diff --git a/lib/crypto/README.docdown.md b/lib/crypto/README.docdown.md new file mode 100644 index 0000000000..1c272c9805 --- /dev/null +++ b/lib/crypto/README.docdown.md @@ -0,0 +1,11 @@ +# `crypto` - [[ini-desc: crypto]] + +## Features + +[[uml: crypto | format: svg, mentities: crypto::basic_ciphers;crypto::bytes;crypto::crypto;crypto::xor_ciphers]] + +[[features: crypto | mentities: crypto::basic_ciphers;crypto::bytes;crypto::xor_ciphers]] + +## Authors + +This project is maintained by [[ini-maintainer: crypto]]. diff --git a/lib/crypto/README.md b/lib/crypto/README.md new file mode 100644 index 0000000000..f9386dedf6 --- /dev/null +++ b/lib/crypto/README.md @@ -0,0 +1,13 @@ +# `crypto` - Mix of all things cryptography-related + +## Features + +![Diagram for `crypto`](uml-crypto.svg) + +* `basic_ciphers` - Basic cryptographic ciphers and utilities. +* `bytes` - Mix of utilities and services related to bytes +* `xor_ciphers` - XOR oriented cryptographic ciphers and utilities. + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/csv/README.docdown.md b/lib/csv/README.docdown.md new file mode 100644 index 0000000000..2c64df2fd0 --- /dev/null +++ b/lib/csv/README.docdown.md @@ -0,0 +1,35 @@ +# `csv` - [[ini-desc: csv]] + +[[toc: csv]] + +## Features + +[[uml: csv | format: svg, mentities: csv::CsvStream;csv::CsvDocument;csv::CsvWriter;csv::CsvReader]] + +### `CsvStream` - Shared properties by all CSV-related classes + +[[doc: csv::CsvStream | no-synopsis]] + +### `CsvWriter` - Appends CSV records to a file. + +[[doc: csv::CsvWriter | no-synopsis]] + +Properties: + +[[features: csv::CsvWriter | min-visibility: public, no-redef]] + +### `CsvReader` - Reads records from a CSV file. + +[[doc: csv::CsvReader | no-synopsis]] + +Properties: + +[[features: csv::CsvReader | min-visibility: public, no-redef]] + +## Other features + +[[features: csv | mentities: csv::CsvDocument]] + +## Authors + +This project is maintained by [[ini-maintainer: csv]]. diff --git a/lib/csv/README.md b/lib/csv/README.md new file mode 100644 index 0000000000..42097de45e --- /dev/null +++ b/lib/csv/README.md @@ -0,0 +1,72 @@ +# `csv` - CSV document handling + +* [Features](#Features) +* [`CsvStream` - Shared properties by all CSV-related classes](#`CsvStream`---Shared-properties-by-all-CSV-related-classes) +* [`CsvWriter` - Appends CSV records to a file.](#`CsvWriter`---Appends-CSV-records-to-a-file.) +* [`CsvReader` - Reads records from a CSV file.](#`CsvReader`---Reads-records-from-a-CSV-file.) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `csv`](uml-csv.svg) + +### `CsvStream` - Shared properties by all CSV-related classes + +This class is basically only here for implementation purposes and should not be used +by clients for typing. + +### `CsvWriter` - Appends CSV records to a file. + +By default, uses the format recommended by RFC 4180 (see `rfc4180`). + +Note: If a record contains only an empty cell, its representation is +undistinguishable from an empty line. This is because the empty values are +always written unescaped in order to avoid them to be interpreted as escaped +delimiters by some parsers. + +~~~nit +var out = new StringWriter +var writer = new CsvWriter(out) +writer.write_elements(1, 2.0, "foo\nbar") +writer.write_line([""]) +assert out.to_s == """1,2.0,"foo\nbar"\n\n""" +~~~ + +Properties: + +* `CsvWriter::write_elements` - Append the elements in `els` as a record. +* `CsvWriter::write_line` - Append the specified record. +* `CsvWriter::write_lines` - Write several lines to a stream + +### `CsvReader` - Reads records from a CSV file. + +By default, the format recognizes EOLs as `\n` + +~~~nit +var example = """ +foo,bar +"Hello, word!",1234.5 + 42 +"Something +""else""\", baz +""" +var reader = new CsvReader.from_string(example) +var table = reader.read_all + +assert table.header == ["foo","bar"] +assert table.records == [["Hello, word!","1234.5 + 42"], + ["Something\n\"else\""," baz"]] +~~~ + +Properties: + +* `CsvReader::from_string` - Creates a new CSVReader from a `string` data +* `CsvReader::read_all` - Reads the content of the Stream and interprets it as a CSV Document + +## Other features + +* `CsvDocument` - A CSV document representation. + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/curl/README.docdown.md b/lib/curl/README.docdown.md new file mode 100644 index 0000000000..bb97ad8b77 --- /dev/null +++ b/lib/curl/README.docdown.md @@ -0,0 +1,17 @@ +# `curl` - [[ini-desc: curl]] + +[[doc: curl::curl]] + +Example from `curl::curl_http`: + +[[code: curl::curl_http]] + +## Features + +[[uml: curl | format: svg, mentities: curl::curl;curl::native_curl]] + +[[features: curl | mentities: curl::native_curl]] + +## Authors + +This project is maintained by [[ini-maintainer: curl]]. diff --git a/lib/curl/README.md b/lib/curl/README.md new file mode 100644 index 0000000000..992ac18a9a --- /dev/null +++ b/lib/curl/README.md @@ -0,0 +1,106 @@ +# `curl` - Data transfer powered by the native curl library + +Download or upload over HTTP with `CurlHTTPRequest` and send emails with `CurlMail`. + +Example from `curl::curl_http`: + +~~~ +# Example use of the Curl module +module curl_http is example + +import curl + +# Custom delegate to receive callbacks from a Curl transfer +class MyHttpFetcher + super CurlCallbacks + + # Body of the downloaded file + var fetched_body = "" + + redef fun header_callback(line) do + # We keep this callback silent for testing purposes + #if not line.has_prefix("Date:") then print "Header_callback: {line}" + end + + redef fun body_callback(line) do self.fetched_body += line + + redef fun stream_callback(buffer) do print "Stream_callback: {buffer}" +end + +private fun print_usage do print "Usage: curl_http [POST|GET|GET_FILE] url" + +if args.length < 2 then + print_usage + exit 1 +end + +var url = args[1] +var request = new CurlHTTPRequest(url) +request.verbose = false # Set to `true` to debug + +if args[0] == "GET" then + # HTTP Get Request + var response = request.execute + + if response isa CurlResponseSuccess then + print "Status code: {response.status_code}" + print "Body: {response.body_str}" + else if response isa CurlResponseFailed then + print "Error code: {response.error_code}" + print "Error msg: {response.error_msg}" + end + +else if args[0] == "POST" then + # HTTP Post Request + var my_http_fetcher = new MyHttpFetcher + request.delegate = my_http_fetcher + + var post_data = new HeaderMap + post_data["Bugs Bunny"] = "Daffy Duck" + post_data["Batman"] = "Robin likes special characters @#ùà!è§'(\"é&://,;<>∞~*" + post_data["Batman"] = "Yes you can set multiple identical keys, but APACHE will consider only one, the last one" + request.data = post_data + var response = request.execute + + print "Our body from the callback: {my_http_fetcher.fetched_body}" + + if response isa CurlResponseSuccess then + print "*** Answer ***" + print "Status code: {response.status_code}" + print "Body should be empty, because we decided to manage callbacks: {response.body_str.length}" + else if response isa CurlResponseFailed then + print "Error code: {response.error_code}" + print "Error msg: {response.error_msg}" + end + +else if args[0] == "GET_FILE" then + # HTTP Get to file Request + var headers = new HeaderMap + headers["Accept"] = "Moo" + request.headers = headers + var response = request.download_to_file(null) + + if response isa CurlFileResponseSuccess then + print "*** Answer ***" + print "Status code: {response.status_code}" + print "Size downloaded: {response.size_download}" + else if response isa CurlResponseFailed then + print "Error code: {response.error_code}" + print "Error msg: {response.error_msg}" + end + +else + print_usage + exit 1 +end +~~~ + +## Features + +![Diagram for `curl`](uml-curl.svg) + +* `native_curl` - Binding of C libCurl which allow us to interact with network. + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/curses/README.docdown.md b/lib/curses/README.docdown.md new file mode 100644 index 0000000000..09824c3b5a --- /dev/null +++ b/lib/curses/README.docdown.md @@ -0,0 +1,9 @@ +# `curses` - [[ini-desc: curses]] + +## Features + +[[features: curses | mentities: curses::Window]] + +## Authors + +This project is maintained by [[ini-maintainer: curses]]. diff --git a/lib/curses/README.md b/lib/curses/README.md new file mode 100644 index 0000000000..b5a291104b --- /dev/null +++ b/lib/curses/README.md @@ -0,0 +1,9 @@ +# `curses` - Curses for Nit + +## Features + +* `Window` - A curse windows + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/date/README.docdown.md b/lib/date/README.docdown.md new file mode 100644 index 0000000000..eb50126d1a --- /dev/null +++ b/lib/date/README.docdown.md @@ -0,0 +1,11 @@ +# `date` - [[ini-desc: date]] + +[[doc: date::date]] + +## Features + +[[features: date | mentities: date::Time;date::Date;date::DateTime]] + +## Authors + +This project is maintained by [[ini-maintainer: date]]. diff --git a/lib/date/README.md b/lib/date/README.md new file mode 100644 index 0000000000..ba319135ba --- /dev/null +++ b/lib/date/README.md @@ -0,0 +1,36 @@ +# `date` - Services to manipulate `Date`, `Time` and `DateTime` + +The services are split in 2 classes: + +* `Date` handles the year, month and day parts of the date. +* `Time` handles the time in hours, minutes and seconds. + +These are united in `DateTime` for a precise time in a precise day. + +~~~ +var now = new Time.now +var midnight = new Time(0, 0, 0) +assert now > midnight + +var nine_thirty = new Time(9, 30, 0) +var eleven_twenty = new Time(11, 20, 0) +assert eleven_twenty > nine_thirty + +var pi_day = new Date(2015, 03, 14) +var may_the_fourth = new Date(2015, 5, 4) +assert pi_day < may_the_fourth + +var now_t = new DateTime.now +var epoch = new DateTime(1970, 1, 1, 0, 0, 0) +assert now_t > epoch +~~~ + +## Features + +* `Date` - A date, composed by a `year`, a `month` and a `day` +* `DateTime` - A `Time` in a `Date` +* `Time` - A time of the day, composed of an `hour`, a `minute` and a `second` count + +## Authors + +This project is maintained by **Mehdi Ait Younes **. diff --git a/lib/deriving/README.docdown.md b/lib/deriving/README.docdown.md new file mode 100644 index 0000000000..616d121e10 --- /dev/null +++ b/lib/deriving/README.docdown.md @@ -0,0 +1,27 @@ +# `deriving` - [[ini-desc: deriving]] + +[[toc: deriving]] + +[[doc: deriving::deriving]] + +## Features + +### `Derivable` - Interface of objects that expose some kind of internal representation in a very unreliable way. + +[[doc: deriving::Derivable | no-synopsis]] + +Properties: + +[[features: deriving::Derivable | min-visibility: public, no-redef]] + +### `DeriveToS` - Implementation of `to_s` for `Derivable` objects. + +[[doc: deriving::DeriveToS | no-synopsis]] + +### `DeriveEqual` - Implementation of `==` and `hash` for `Derivable` objects. + +[[doc: deriving::DeriveEqual | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: deriving]]. diff --git a/lib/deriving/README.md b/lib/deriving/README.md new file mode 100644 index 0000000000..8c29b1b6ab --- /dev/null +++ b/lib/deriving/README.md @@ -0,0 +1,90 @@ +# `deriving` - Automatic derivable implementations of standard basic methods + +* [Features](#Features) +* [`Derivable` - Interface of objects that expose some kind of internal representation in a very unreliable way.](#`Derivable`---Interface-of-objects-that-expose-some-kind-of-internal-representation-in-a-very-unreliable-way.) +* [`DeriveToS` - Implementation of `to_s` for `Derivable` objects.](#`DeriveToS`---Implementation-of-`to_s`-for-`Derivable`-objects.) +* [`DeriveEqual` - Implementation of `==` and `hash` for `Derivable` objects.](#`DeriveEqual`---Implementation-of-`==`-and-`hash`-for-`Derivable`-objects.) +* [Authors](#Authors) + +This module introduce `Derivable` as the main interface to implement (or auto-implement) and +provides additional mixin-interfaces with specific default behavior of standard basic methods based +on the services of this interface. + +The name *deriving* is inspired from the deriving mechanism of Haskell. + +This module also introduce a new annotation `auto_derive`. See `Derivable` for details. + +## Features + +### `Derivable` - Interface of objects that expose some kind of internal representation in a very unreliable way. + +The point of this interface is to allow objects to give a basic representation of +themselves within a simple key-value dictionary. +The specific semantic of each key and value is let unspecified. + +Moreover the class annotation `auto_derive` will automatically implements the +interface with the attributes locally defined in the class. + +~~~ +class A + auto_derive + var an_int: Int + var a_string: String +end + +var a = new A(5, "five") +var map = a.derive_to_map +assert map.length == 2 +assert map["an_int"] == 5 +assert map["a_string"] == "five" +~~~ + +Properties: + +* `Derivable::derive_to_map` - Returns a map that loosely represents the object `self`. + +### `DeriveToS` - Implementation of `to_s` for `Derivable` objects. + +The implementation uses `to_s` for each value of `attributes_to_map`. + +~~~ +class A + auto_derive + super DeriveToS + var an_int: Int + var a_string: String +end + +var a = new A(5, "five") +assert a.to_s == "an_int:5; a_string:five" +~~~ + +Warning: the method may go in an infinite recursion if there is a circuit in +the implementation of `to_s`. + +### `DeriveEqual` - Implementation of `==` and `hash` for `Derivable` objects. + +The implementations just call `==` and `hash` on `derive_to_map`. + +~~~ +class A + auto_derive + super DeriveEqual + var an_int: Int + var a_string: String +end + +var a = new A(5, "five") +var b = new A(5, "five") +var c = new A(6, "six") +assert a == b +assert a.hash == b.hash +assert a != c +~~~ + +Warning: the method may go in an infinite recursion if there is a circuit in +the implementation of `==` or `hash`. + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/dom/README.docdown.md b/lib/dom/README.docdown.md new file mode 100644 index 0000000000..930fa79bf9 --- /dev/null +++ b/lib/dom/README.docdown.md @@ -0,0 +1,23 @@ +# `dom` - [[ini-desc: dom]] + +[[toc: dom]] + +Example from `dom::checker`: + +[[code: dom::checker]] + +## Features + +[[uml: dom | format: svg, mentities: dom::dom;dom::parser;dom::xml_entities]] + +### `xml_entities` - Basic blocks for DOM-XML representation + +[[doc: dom::xml_entities | no-synopsis]] + +## Other features + +[[features: dom | mentities: dom::parser]] + +## Authors + +This project is maintained by [[ini-maintainer: dom]]. diff --git a/lib/dom/README.md b/lib/dom/README.md new file mode 100644 index 0000000000..9f6556532c --- /dev/null +++ b/lib/dom/README.md @@ -0,0 +1,78 @@ +# `dom` - Easy XML DOM parser + +* [Features](#Features) +* [`xml_entities` - Basic blocks for DOM-XML representation](#`xml_entities`---Basic-blocks-for-DOM-XML-representation) +* [Other features](#Other-features) +* [Authors](#Authors) + +Example from `dom::checker`: + +~~~ +# Simple XML validity checker using the `dom` module +module checker is example + +import dom + +# Check arguments +if args.length != 1 then + print_error "Usage: checker xml_file" + exit 2 +end + +var path = args.first +if not path.file_exists then + print_error "Path '{path}' does not exist" + exit 3 +end + +# Read file +var content = path.to_path.read_all + +# Parse XML +var xml = content.to_xml + +# Check for errors +if xml isa XMLError then + print_error "XML file at '{path}' is invalid:" + print_error xml.message + var loc = xml.location + if loc != null then print_error loc + exit 1 +else + print "XML file at '{path}' is valid" +end +~~~ + +## Features + +![Diagram for `dom`](uml-dom.svg) + +### `xml_entities` - Basic blocks for DOM-XML representation + +DOM entities are defined in this module, specifically: + +* `XMLEntity`: Abstract kind of XML-related node +* `XMLDocument`: A well-formed XML document, root of the tree +* `PCDATA`: Raw XML-escaped character data +* `CDATA`: Raw data, may contain invalid XML escape characters +* `XMLTag`: Abstract XML tag element +* `XMLAttrTag`: Abstract XML element, they may contain attributes +* `XMLOnelinerTag`: Any tag contained on one-line only +* `XMLStartTag`: A tag starting a new hierarchy level in the tree +* `XMLPrologTag`: A tag containing meta-information on the document, must start with **. diff --git a/lib/dot/README.docdown.md b/lib/dot/README.docdown.md new file mode 100644 index 0000000000..e0d6d0dfcc --- /dev/null +++ b/lib/dot/README.docdown.md @@ -0,0 +1,49 @@ +# `dot` - [[ini-desc: dot]] + +[[toc: dot]] + +[[doc: dot::dot]] + +## Features + +[[uml: dot | format: svg, mentities: dot::DotElement;dot::AttributeMap;dot::DotGraph;dot::DotNode;dot::DotEdge;dot::DotCluster]] + +### `DotGraph` - A Graph representation suited for dot format. + +[[doc: dot::DotGraph | no-synopsis]] + +Properties: + +[[features: dot::DotGraph | min-visibility: public, no-redef]] + +### `DotNode` - A dot node + +[[doc: dot::DotNode | no-synopsis]] + +Example from `dot::clusters`: + +[[code: dot::clusters]] + +### `DotEdge` - A dot edge that links two nodes + +[[doc: dot::DotEdge | no-synopsis]] + +Example from `dot::hello`: + +[[code: dot::hello]] + +### `DotCluster` - A dot cluster allows nested nodes + +[[doc: dot::DotCluster | no-synopsis]] + +Example from `dot::undirected_clusters`: + +[[code: dot::undirected_clusters]] + +## Other features + +[[features: dot | mentities: dot::DotElement;dot::AttributeMap]] + +## Authors + +This project is maintained by [[ini-maintainer: dot]]. diff --git a/lib/dot/README.md b/lib/dot/README.md new file mode 100644 index 0000000000..26f5874d96 --- /dev/null +++ b/lib/dot/README.md @@ -0,0 +1,251 @@ +# `dot` - Dot rendering library + +* [Features](#Features) +* [`DotGraph` - A Graph representation suited for dot format.](#`DotGraph`---A-Graph-representation-suited-for-dot-format.) +* [`DotNode` - A dot node](#`DotNode`---A-dot-node) +* [`DotEdge` - A dot edge that links two nodes](#`DotEdge`---A-dot-edge-that-links-two-nodes) +* [`DotCluster` - A dot cluster allows nested nodes](#`DotCluster`---A-dot-cluster-allows-nested-nodes) +* [Other features](#Other-features) +* [Authors](#Authors) + +Example: + +~~~ +import dot + +var graph = new DotGraph("G", "digraph") + +var hello = graph.add_node("hello") +var world = graph.add_node("world") + +graph.add_edge(hello, world) + +print graph.to_dot +~~~ + +## Features + +![Diagram for `dot`](uml-dot.svg) + +### `DotGraph` - A Graph representation suited for dot format. + +Creating a new graph + +~~~ +var graph = new DotGraph("G", "digraph") +graph["rankdir"] = "BT" +graph["ranksep"] = 0.3 +graph["nodesep"] = 0.3 +graph.nodes_attrs["fontname"] = "helvetica" +graph.edges_attrs["color"] = "gray" +~~~ + +Properties: + +* `DotGraph::add` - Add a node to the graph +* `DotGraph::add_edge` - Add an edge to the graph +* `DotGraph::add_node` - Add a new node to the graph +* `DotGraph::show` - Show dot in graphviz (blocking) +* `DotGraph::to_svg` - Render `self` as an SVG image + +### `DotNode` - A dot node + +Nodes can be created from scratch + +~~~ +var node = new DotNode("id") +node["label"] = "ID" +~~~ + +Then added to a graph + +~~~ +var graph = new DotGraph("G", "digraph") +graph.add node +~~~ + +Or can be created directly from an existing graph + +~~~ +var node2 = graph.add_node("id2") +node2["label"] = "ID2" +~~~ + +Example from `dot::clusters`: + +~~~ +# Example from http://www.graphviz.org/content/cluster +module clusters is example + +import dot + +var graph = new DotGraph("G", "digraph") + +var cl0 = new DotGraph("cluster_0", "subgraph") +cl0["label"] = "process #1" +cl0["style"] = "filled" +cl0["color"] = "lightgrey" +cl0.nodes_attrs["style"] = "filled" +cl0.nodes_attrs["color"] = "white" + +var a0 = cl0.add_node("a0") +var a1 = cl0.add_node("a1") +var a2 = cl0.add_node("a2") +var a3 = cl0.add_node("a3") +cl0.add_edge(a0, a1) +cl0.add_edge(a1, a2) +cl0.add_edge(a2, a3) + +graph.add cl0 + +var cl1 = new DotGraph("cluster_1", "subgraph") +cl1["label"] = "process #2" +cl1["color"] = "blue" +cl1.nodes_attrs["style"] = "filled" + +var b0 = cl1.add_node("b0") +var b1 = cl1.add_node("b1") +var b2 = cl1.add_node("b2") +var b3 = cl1.add_node("b3") +cl1.add_edge(b0, b1) +cl1.add_edge(b1, b2) +cl1.add_edge(b2, b3) + +graph.add cl1 + +var start = graph.add_node("start") +start["shape"] = "Mdiamond" + +var nend = graph.add_node("end") +nend["shape"] = "Msquare" + +graph.add_edge(start, a0) +graph.add_edge(start, b0) +graph.add_edge(a1, b3) +graph.add_edge(b2, a3) +graph.add_edge(a3, a0) +graph.add_edge(a3, nend) +graph.add_edge(b3, nend) + +if args.is_empty then + print graph.to_dot + # graph.show +else + graph.to_dot.write_to_file args.first +end +~~~ + +### `DotEdge` - A dot edge that links two nodes + +Edges can be created from scratch + +~~~ +var a1 = new DotNode("a1") +var b1 = new DotNode("b1") +var edge = new DotEdge(a1, b1) +edge["color"] = "blue" +~~~ + +Then added to a graph + +~~~ +sh var graph = new DotGraph("G", "digraph") +graph.add edge +~~~ + +Or can be created directly from an existing graph + +~~~ +var a2 = graph.add_node("a2") +var b2 = graph.add_node("b2") +var edge2 = graph.add_edge(a2, b2) +edge2["color"] = "red" +~~~ + +Example from `dot::hello`: + +~~~ +# Example from http://www.graphviz.org/content/hello +module hello is example + +import dot + +var graph = new DotGraph("G", "digraph") + +var hello = graph.add_node("hello") +var world = graph.add_node("world") +graph.add_edge(hello, world) + +if args.is_empty then + print graph.to_dot +else + graph.to_dot.write_to_file args.first +end +~~~ + +### `DotCluster` - A dot cluster allows nested nodes + +Creating clusters + +~~~ +var graph = new DotGraph("G", "digraph") +graph["rankdir"] = "BT" + +var sub = new DotCluster("cluster_sub", "subgraph") +sub["label"] = "process #1" + +var a0 = sub.add_node("a0") +var a1 = sub.add_node("a1") +sub.add_edge(a0, a1) + +graph.add sub +~~~ + +Example from `dot::undirected_clusters`: + +~~~ +# Example from http://www.graphviz.org/Gallery/undirected/fdpclust.html +module undirected_clusters is example + +import dot + +var graph = new DotGraph("G", "graph") + +var a = new DotNode("a") +var b = new DotNode("b") +var c = new DotNode("c") +var d = new DotNode("d") +var e = new DotNode("e") +var f = new DotNode("f") +var g = new DotNode("g") + +var clA = new DotGraph("clusterA", "subgraph") +clA.add_edge(a, b).directed = false +graph.add clA + +var clB = new DotGraph("clusterB", "subgraph") +clB.add_edge(c, d).directed = false +clA.add clB + +var clC = new DotGraph("clusterC", "subgraph") +clC.add_edge(e, g).directed = false +graph.add clC + +graph.add_edge(e, d).directed = false +graph.add_edge(f, g).directed = false + +if args.is_empty then + print graph.to_dot +else + graph.to_dot.write_to_file args.first +end +~~~ + +## Other features + +* `AttributeMap` - Map of graph/node/edge attribute that can be rendered to dot. +* `DotElement` - Something that can be rendered in dot format. + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/dummy_array/README.docdown.md b/lib/dummy_array/README.docdown.md new file mode 100644 index 0000000000..d7b3139a40 --- /dev/null +++ b/lib/dummy_array/README.docdown.md @@ -0,0 +1,9 @@ +# `dummy_array` + +## Features + +[[features: dummy_array | mentities: dummy_array::DummyArray;dummy_array::DummyIterator]] + +## Authors + +This project is maintained by [[ini-maintainer: dummy_array]]. diff --git a/lib/dummy_array/README.md b/lib/dummy_array/README.md new file mode 100644 index 0000000000..1246d63479 --- /dev/null +++ b/lib/dummy_array/README.md @@ -0,0 +1,10 @@ +# `dummy_array` + +## Features + +* `DummyArray` - A `Set` that contains only integers. +* `DummyIterator` - An iterator over a `DummyArray`. + +## Authors + +This project is maintained by **Floréal Morandat **. diff --git a/lib/egl/README.docdown.md b/lib/egl/README.docdown.md new file mode 100644 index 0000000000..9c4dfce8ca --- /dev/null +++ b/lib/egl/README.docdown.md @@ -0,0 +1,11 @@ +# `egl` - [[ini-desc: egl]] + +[[doc: egl::egl]] + +## Features + +[[features: egl | mentities: egl::EGLNativeDisplayType;egl::EGLDisplay;egl::EGLConfig;egl::EGLSurface;egl::EGLContext;egl::EGLConfigAttribs;egl::EGLConfigCaveat;egl::EGLConformant;egl::EGLSurfaceAttribs;egl::EGLError;egl::EGLContextAttribute;egl::EGLConfigChooser]] + +## Authors + +This project is maintained by [[ini-maintainer: egl]]. diff --git a/lib/egl/README.md b/lib/egl/README.md new file mode 100644 index 0000000000..acdfa3c70b --- /dev/null +++ b/lib/egl/README.md @@ -0,0 +1,25 @@ +# `egl` - Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system + +Most services of this module are a direct wrapper of the underlying +C library. If a method or class is not documented in Nit, refer to +the official documentation by the Khronos Group at: +http://www.khronos.org/registry/egl/sdk/docs/man/xhtml/ + +## Features + +* `EGLConfig` +* `EGLConfigAttribs` - Attributes of a config for a given EGL display +* `EGLConfigCaveat` +* `EGLConfigChooser` - Utility class to choose an EGLConfig +* `EGLConformant` +* `EGLContext` +* `EGLContextAttribute` +* `EGLDisplay` +* `EGLError` +* `EGLNativeDisplayType` +* `EGLSurface` +* `EGLSurfaceAttribs` - Attributes of a surface for a given EGL display + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/emscripten/README.docdown.md b/lib/emscripten/README.docdown.md new file mode 100644 index 0000000000..706bc83c50 --- /dev/null +++ b/lib/emscripten/README.docdown.md @@ -0,0 +1,11 @@ +# `emscripten` - [[ini-desc: emscripten]] + +[[doc: emscripten::emscripten]] + +## Features + +[[features: emscripten | mentities: emscripten::emscripten::Text::run_js;emscripten::emscripten::Text::escape_to_js;emscripten::emscripten::Text::alert]] + +## Authors + +This project is maintained by [[ini-maintainer: emscripten]]. diff --git a/lib/emscripten/README.md b/lib/emscripten/README.md new file mode 100644 index 0000000000..a9f68b11d9 --- /dev/null +++ b/lib/emscripten/README.md @@ -0,0 +1,14 @@ +# `emscripten` - Platform for the _emscripten_ framework + +Importing this module from your project will tell `nitc` to compile +to JavaScript for the _emscripten_ framework. + +## Features + +* `Text::alert` - Raise a JavaScript alert +* `Text::escape_to_js` - Escape the content of `self` to pass to JavaScript code +* `Text::run_js` - Run `self` as JavaScript code + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/event_queue/README.docdown.md b/lib/event_queue/README.docdown.md new file mode 100644 index 0000000000..8fe3baac97 --- /dev/null +++ b/lib/event_queue/README.docdown.md @@ -0,0 +1,23 @@ +# `event_queue` - [[ini-desc: event_queue]] + +[[toc: event_queue]] + +[[doc: event_queue::event_queue]] + +## Features + +### `EventInfo` - Information and management about a registered event + +[[doc: event_queue::EventInfo | no-synopsis]] + +Properties: + +[[features: event_queue::EventInfo | min-visibility: public, no-redef]] + +## Other features + +[[features: event_queue | mentities: event_queue::EventQueue]] + +## Authors + +This project is maintained by [[ini-maintainer: event_queue]]. diff --git a/lib/event_queue/README.md b/lib/event_queue/README.md new file mode 100644 index 0000000000..085af699b9 --- /dev/null +++ b/lib/event_queue/README.md @@ -0,0 +1,178 @@ +# `event_queue` - Register, update and discard events in a timeline + +* [Features](#Features) +* [`EventInfo` - Information and management about a registered event](#`EventInfo`---Information-and-management-about-a-registered-event) +* [Other features](#Other-features) +* [Authors](#Authors) + +A queue of event is used to register objects associated with a start time and +a duration and to return them when they are active. + +The main class is `EventQueue`. It controls a timeline and register events. +Event can be any kind of object, usually specific time-related domain objects should be used. + +The auxiliary class `EventInfo` registers and control information about each event. +It can also be used for fluent programming and create new events relatively to existing ones. + +## Basic usage + +The event queue is created empty, and can handle any kind of data. + +~~~ +var eq = new EventQueue[String] +~~~ + +To register an event, add it with a start time and a duration. +Note that the time is relative to the current time frame in the queue. + +~~~ +eq.add("1..2", 1.0, 1.0) +eq.add("2..10", 2.0, 8.0) +~~~ + +To register instantaneous event, use a 0.0 duration (or no duration) + +~~~ +eq.add("1.5", 1.5) +~~~ + +To get active events, use `update` with a time difference. +This returns a sequence of currently active events. + +~~~ +var es = eq.update(1.0) # What is active after 1 unit of time? +assert es.length == 1 # only "1..2" is active +~~~ + +Each `update` increments the time frame of the queue and returns an updated information about active events. + +~~~ +es = eq.update(1.0) # What is active after an other unit of time? +assert eq.time == 2.0 + +assert es.length == 3 # there is now 3 active events +~~~ + +Results of the `update` method contains a lot of information. + +Obviously the original events: + +~~~ +assert es[0].event == "1..2" +assert es[1].event == "1.5" +assert es[2].event == "2..10" +~~~ + +The time since the begin of the event: + +~~~ +assert es[0].time == 1.0 # Started 1 unit of time ago +assert es[1].time == 0.5 +assert es[2].time == 0.0 # Started just now +~~~ + +The completion ratio of the event until its termination: + +~~~ +assert es[0].completion == 1.0 # has just finished +assert es[1].completion == inf # completion ratio does not make sense for instant events +assert es[2].completion == 0.0 # has just started +~~~ + +And a lot of other things, just look at `EventInfo`. + +## Expiration and control + +When `update` returns events, `occurrences` count the number of time an +event is returned by update. It can be used for instance to see if it +is the first time that a specific event is active. + +~~~ +assert es[0].occurrences == 2 # it is the second time we see it +assert es[1].occurrences == 1 # instant one +assert es[2].occurrences == 1 # first time we see it +~~~ + +The duration is used to automatically manage the expiration of the event. + +Note that if a event expires during an `update`, then it is still returned by the function. +This is the way to handle instant events and newly expired events. + +To distinguish them `has_expired` can be used. + +~~~ +assert es[0].has_expired == true # just finished +assert es[1].has_expired == true # instant one +assert es[2].has_expired == false # sill active +~~~ + +On the next `update`, the already expired events are not returned again. + +~~~ +es = eq.update(1.0) # What is active after an other unit of time? +assert eq.time == 3.0 +assert es.length == 1 +assert es.first.event == "2..10" # No more "1..2" or "1.5" +~~~ + +The `expire` method can force the expiration of an event. + +~~~ +es.first.expire +es = eq.update(1.0) +assert es.is_empty # Sorry, "2..10" was expired +~~~ + +## Fluent programming + +The `add` method (and its derivates) returns a `EventInfo` object that can be used to have +information about the newly registered event but also to chain the creation of time-related events. + +For instance, the following example registers 4 events, each one relative to the previous one: + +~~~ +eq = new EventQueue[String] +eq.add("e1", 10.0, 5.0). + add_after("e2", 2.0, 5.0). + add_sync("e3", 2.0, 5.0). + add_before("e4", 2.0, 5.0) +~~~ + +This can be decomposed as: + +~~~ +eq = new EventQueue[String] +var e1 = eq.add("e1", 10.0, 5.0) +assert e1.start == 10.0 # First event starts at 10 + +var e2 = e1.add_after("e2", 2.0, 5.0) # starts 2 units of time after the end of e1 +assert e2.start == 17.0 # So starts at 10 + 5 + 2 + +var e3 = e2.add_sync("e3", 2.0, 5.0) # starts 2 units of time after the begin of e2 +assert e3.start == 19.0 # So starts at 17 + 2 + +var e4 = e3.add_before("e4", 2.0, 5.0) # ends 2 units of time before the start of e3 +assert e4.start == 12.0 # So starts at 19 - 2 - 5 +~~~ + +## Features + +### `EventInfo` - Information and management about a registered event + +It allows to retrieve static and dynamic information about an event. +It also allows to register other time-related events with a fluent programming way. + +Properties: + +* `EventInfo::add_after` - Register an event that starts after the end of the current one. +* `EventInfo::add_before` - Register an event that finishes before the begin of current one. +* `EventInfo::add_sync` - Register an event that starts with the current one. +* `EventInfo::expire` - Force the event to expire. + +## Other features + +* `EventQueue` - Queuing and management of arbitrary events in a timeline + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/fca/README.docdown.md b/lib/fca/README.docdown.md new file mode 100644 index 0000000000..acff54c9c9 --- /dev/null +++ b/lib/fca/README.docdown.md @@ -0,0 +1,35 @@ +# `fca` - [[ini-desc: fca]] + +[[toc: fca]] + +[[doc: fca::fca]] + +## Features + +### `FormalContext` - Formal Context + +[[doc: fca::FormalContext | no-synopsis]] + +Properties: + +[[features: fca::FormalContext | min-visibility: public, no-redef]] + +### `FormalConcept` - Formal Concept + +[[doc: fca::FormalConcept | no-synopsis]] + +Properties: + +[[features: fca::FormalConcept | min-visibility: public, no-redef]] + +### `ConceptLattice` - Concept Lattice + +[[doc: fca::ConceptLattice | no-synopsis]] + +Properties: + +[[features: fca::ConceptLattice | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: fca]]. diff --git a/lib/fca/README.md b/lib/fca/README.md new file mode 100644 index 0000000000..4cd143f252 --- /dev/null +++ b/lib/fca/README.md @@ -0,0 +1,109 @@ +# `fca` - Formal Concept Analysis for Nit + +* [Features](#Features) +* [`FormalContext` - Formal Context](#`FormalContext`---Formal-Context) +* [`FormalConcept` - Formal Concept](#`FormalConcept`---Formal-Concept) +* [`ConceptLattice` - Concept Lattice](#`ConceptLattice`---Concept-Lattice) +* [Authors](#Authors) + +Formal concept analysis (FCA) is a principled way of deriving a concept hierarchy +or formal ontology from a collection of objects and their properties. +This means deriving implicit relationships between objects regarding their +attributes. + +Each concept in the hierarchy represents the set of objects sharing the same +values for a certain set of properties; and each sub-concept in the hierarchy +contains a subset of the objects in the concepts above it. + +Formal concept analysis finds practical application in fields including data +mining, text mining, machine learning or semantic web. + +## Building a FormalContext + +We use the example from https://en.wikipedia.org/wiki/Formal_concept_analysis: + +~~~ +var fc = new FormalContext[Int, String] +fc.set_object_attributes(1, ["odd", "square"]) +fc.set_object_attributes(2, ["even", "prime"]) +fc.set_object_attributes(3, ["odd", "prime"]) +fc.set_object_attributes(4, ["even", "composite", "square"]) +fc.set_object_attributes(5, ["odd", "prime"]) +fc.set_object_attributes(6, ["even", "composite"]) +fc.set_object_attributes(7, ["odd", "prime"]) +fc.set_object_attributes(8, ["even", "composite"]) +fc.set_object_attributes(9, ["odd", "square", "composite"]) +fc.set_object_attributes(10, ["even", "composite"]) +~~~ + +## Computing the set of FormalConcept + +~~~ +var concepts = fc.formal_concepts +for concept in concepts do + print concept +end +~~~ + +## Visualizing formal concept with ConceptLattice + +~~~nitish +var cl = new ConceptLattice[Int, String].from_concepts(concepts) +cl.show_dot +~~~ + +## Features + +### `FormalContext` - Formal Context + +A formal context is a triple *K = (G, M, I)*, where *G* is a set of `objects`, +*M* is a set of `attributes`, and *I ⊆ G × M* is a binary relation called incidence +that expresses which objects have which attributes (`objects_attributes`). + +Predicate *gIm* designates object *g*'s having attribute *m*. +For a subset *A ⊆ G* of objects and a subset *B ⊆ M* of attributes, one defines +two derivation operators as follows: + +* *A' = {m ∈ M | ∀ g ∈ A, gIm}*, and dually +* *B' = {g ∈ G | ∀ m ∈ B, gIm}*. + +Properties: + +* `FormalContext::formal_concepts` - Derive the set of formal concepts from the objects and attributes +* `FormalContext::set_object_attribute` - Associate an `attribute` to `object` +* `FormalContext::set_object_attributes` - Associate a set of `attributes` to `object` + +### `FormalConcept` - Formal Concept + +A pair *(A,B)* is a formal concept of a FormalContext *(G, M, I)* provided that: + +* *A ⊆ G*, +* *B ⊆ M*, +* *A′ = B*, and +* *B′ = A*. + +Equivalently and more intuitively, *(A,B)* is a formal concept precisely when: + +* every object in *A* has every attribute in *B*, +* for every object in *G* that is not in *A*, there is some attribute in *B* that + the object does not have, +* for every attribute in *M* that is not in *B*, there is some object in *A* + that does not have that attribute. + +Properties: + +* `FormalConcept::is_subconcept` - Is `self` a subconcept of `super_concept`? + +### `ConceptLattice` - Concept Lattice + +Formal concepts are partially ordered with regard to inclusion of their extents +or (which is equivalent) inverse inclusion of their intent. + +Properties: + +* `ConceptLattice::from_concepts` - Build `self` from a set of formal `concepts`. +* `ConceptLattice::is_lower_neighbour` - Is `sub` the greatest lower bound of `sup` considering all `concepts`? + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/filter_stream/README.docdown.md b/lib/filter_stream/README.docdown.md new file mode 100644 index 0000000000..560984b94e --- /dev/null +++ b/lib/filter_stream/README.docdown.md @@ -0,0 +1,9 @@ +# `filter_stream` + +## Features + +[[features: filter_stream | mentities: filter_stream::FilterReader;filter_stream::FilterWriter;filter_stream::StreamCat;filter_stream::StreamDemux]] + +## Authors + +This project is maintained by [[ini-maintainer: filter_stream]]. diff --git a/lib/filter_stream/README.md b/lib/filter_stream/README.md new file mode 100644 index 0000000000..47e0654732 --- /dev/null +++ b/lib/filter_stream/README.md @@ -0,0 +1,12 @@ +# `filter_stream` + +## Features + +* `FilterReader` +* `FilterWriter` +* `StreamCat` +* `StreamDemux` + +## Authors + +This project is maintained by **Floréal Morandat **. diff --git a/lib/for_abuse/README.docdown.md b/lib/for_abuse/README.docdown.md new file mode 100644 index 0000000000..64992c1845 --- /dev/null +++ b/lib/for_abuse/README.docdown.md @@ -0,0 +1,23 @@ +# `for_abuse` - [[ini-desc: for_abuse]] + +[[toc: for_abuse]] + +[[doc: for_abuse::for_abuse]] + +## Features + +### `ForAbuser` - Encapsulation of service in a `for`-compatible interface. + +[[doc: for_abuse::ForAbuser | no-synopsis]] + +Properties: + +[[features: for_abuse::ForAbuser | min-visibility: public, no-redef]] + +### `CompareQuery` - A comparison query. + +[[doc: for_abuse::CompareQuery | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: for_abuse]]. diff --git a/lib/for_abuse/README.md b/lib/for_abuse/README.md new file mode 100644 index 0000000000..1005610a60 --- /dev/null +++ b/lib/for_abuse/README.md @@ -0,0 +1,47 @@ +# `for_abuse` - Service management through the `for` control structure + +* [Features](#Features) +* [`ForAbuser` - Encapsulation of service in a `for`-compatible interface.](#`ForAbuser`---Encapsulation-of-service-in-a-`for`-compatible-interface.) +* [`CompareQuery` - A comparison query.](#`CompareQuery`---A-comparison-query.) +* [Authors](#Authors) + +The module is a proof-of-concept to investigate the abuse of +the `for` structure to implement various services. + +The idea is that, with a `for`, the service-provider can: + +* control the end of the service (thus can finalize things + like releasing ressources) +* communicate data with the user on each iteration; the used can + also communicate results to the provider. + +## Features + +### `ForAbuser` - Encapsulation of service in a `for`-compatible interface. + +The service is not effectively started until the iterate method +is called. Then, each step of the iteration is a step in the service. + +While, for a typing point of view, abusers are just classes with an +iterator method, the point of this class is to tag services that return +a ForAbuser object. + +Note that using having `ForAbuser` as a genuine subclass of `Collection` +works but is not recommended since it may cause mental health issues. + +Properties: + +* `ForAbuser::iterator` - Starts and control the service + +### `CompareQuery` - A comparison query. + +* if `a < b` then the user sets `res` to -1 +* if `a > b` then the user sets `res` to 1 +* if `a == b` then the user sets `res` to 0 + +It is the responsibility of the user to implement a total order. +ie. the implemented comparison must be asymmetric, transitive and total. + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/gamnit/README.docdown.md b/lib/gamnit/README.docdown.md new file mode 100644 index 0000000000..3dbea1fc78 --- /dev/null +++ b/lib/gamnit/README.docdown.md @@ -0,0 +1,55 @@ +# `gamnit` - [[ini-desc: gamnit]] + +[[toc: gamnit]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: gamnit]] + +### Run `texture_atlas_parser` + +Compile `texture_atlas_parser` with the following command: + +[[main-compile: gamnit::texture_atlas_parser]] + +## Features + +[[uml: gamnit | format: svg, mentities: gamnit>;gamnit>depth>;gamnit>flat>;gamnit>model_parsers>;gamnit>network>;gamnit>virtual_gamepad>;gamnit>virtual_gamepad>art>;gamnit>virtual_gamepad>assets>;gamnit>virtual_gamepad>assets>images>]] + +### `android19` - Variation using features from Android API 19 + +[[doc: gamnit::android19 | no-synopsis]] + +### `bmfont` - Parse Angel Code BMFont format and draw text + +[[doc: gamnit::bmfont | no-synopsis]] + +### `display_android` - Gamnit display implementation for Android + +[[doc: gamnit::display_android | no-synopsis]] + +### `dynamic_resolution` - Virtual screen with a resolution independent from the real screen + +[[doc: gamnit::dynamic_resolution | no-synopsis]] + +### `keys` - Simple service keeping track of which keys are currently pressed + +[[doc: gamnit::keys | no-synopsis]] + +## Other features + +[[features: gamnit | mentities: gamnit::camera_control;gamnit::camera_control_android;gamnit::camera_control_linux;gamnit::cameras;gamnit::cameras_cache;gamnit::display;gamnit::display_ios;gamnit::display_linux;gamnit::egl;gamnit::font;gamnit::gamnit_android;gamnit::gamnit_ios;gamnit::gamnit_linux;gamnit::input_ios;gamnit::landscape;gamnit::limit_fps;gamnit::portrait;gamnit::programs;gamnit::texture_atlas_parser;gamnit::textures;gamnit::tileset]] + +Then run it with: + +[[main-run: gamnit::texture_atlas_parser]] + +## Authors + +This project is maintained by [[ini-maintainer: gamnit]]. diff --git a/lib/gamnit/README.md b/lib/gamnit/README.md new file mode 100644 index 0000000000..dc987c8c00 --- /dev/null +++ b/lib/gamnit/README.md @@ -0,0 +1,147 @@ +# `gamnit` - Portable game and multimedia framework for Nit + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `texture_atlas_parser`](#Run-`texture_atlas_parser`) +* [Features](#Features) +* [`android19` - Variation using features from Android API 19](#`android19`---Variation-using-features-from-Android-API-19) +* [`bmfont` - Parse Angel Code BMFont format and draw text](#`bmfont`---Parse-Angel-Code-BMFont-format-and-draw-text) +* [`display_android` - Gamnit display implementation for Android](#`display_android`---Gamnit-display-implementation-for-Android) +* [`dynamic_resolution` - Virtual screen with a resolution independent from the real screen](#`dynamic_resolution`---Virtual-screen-with-a-resolution-independent-from-the-real-screen) +* [`keys` - Simple service keeping track of which keys are currently pressed](#`keys`---Simple-service-keeping-track-of-which-keys-are-currently-pressed) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `android` - Android platform support and APIs +* `app` - _app.nit_, a framework for portable applications +* `core` - Nit common library of core classes and methods +* `dom` - Easy XML DOM parser +* `egl` - Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system +* `gen_nit` - Support to generate and otherwise manipulate Nit code +* `geometry` - Basic geometry data structures and services +* `glesv2` - OpenGL graphics rendering library for embedded systems, version 2.0 +* `ios` - iOS support for _app.nit_ +* `linux` - Implementation of app.nit for the Linux platform +* `matrix` - Services for matrices of `Float` values +* `mnit` - `mnit` +* `more_collections` - Highly specific, but useful, collections-related classes +* `msgpack` - MessagePack, an efficient binary serialization format +* `opts` - Management of options on the command line +* `parser_base` - Simple base for hand-made parsers of all kinds +* `performance_analysis` - Services to gather information on the performance of events by categories +* `realtime` - Services to keep time of the wall clock time +* `sdl2` - This is a low-level wrapper of the SDL 2.0 library (as `sdl2`) and SDL_image 2.0 (as `sdl2::image`) +* `socket` - Socket services + +### Run `texture_atlas_parser` + +Compile `texture_atlas_parser` with the following command: + +~~~bash +nitc ./texture_atlas_parser.nit +~~~ + +## Features + +![Diagram for `gamnit`](uml-gamnit.svg) + +### `android19` - Variation using features from Android API 19 + +Add support for `TextureAsset::premultiply_alpha = false` on Android. + +### `bmfont` - Parse Angel Code BMFont format and draw text + +The BMFont format supports packed textures, varying advance per character and +even kernings. It can be generated with a number of tools, inluding: + +* BMFont, free software Windows app, http://www.angelcode.com/products/bmfont/ +* Littera, a web app, http://kvazars.com/littera/ + +Format reference: http://www.angelcode.com/products/bmfont/doc/file_format.html + +### `display_android` - Gamnit display implementation for Android + +Gamnit apps on Android require OpenGL ES 3.0 because, even if it uses only +the OpenGL ES 2.0 API, the default shaders have more than 8 vertex attributes. +OpenGL ES 3.0 ensures at least 8 vertex attributes, while 2.0 ensures only 4. + +This module relies on `android::native_app_glue` and the Android NDK. + +### `dynamic_resolution` - Virtual screen with a resolution independent from the real screen + +The attribute `dynamic_resolution_ratio` sets the size of the virtual screen +in relation to the real screen. See its documentation for more information. + +Reference implementation: +https://software.intel.com/en-us/articles/dynamic-resolution-rendering-on-opengl-es-2 + +### `keys` - Simple service keeping track of which keys are currently pressed + +This service revolves around `app.pressed_keys`, a `Set` of the names of currently pressed keys. +As a `Set`, `app.pressed_keys` can be iterated and queried with `has`. + +Limitations: The keys names are platform dependent. + +~~~nitish +redef class App + redef fun accept_event(event) + do + # First, pass the event to `super`, `pressed_keys` must see all + # events but it doesn't intercept any of them. + if super then return true + return false + end + + redef fun update(dt) + do + for key in pressed_keys do + if k == "left" or k == "a" then + # Act on key pressed down + print "left or a is pressed down" + end + end + end +end +~~~ + +## Other features + +* `camera_control` - Simple camera control for user, as the method `accept_scroll_and_zoom` +* `camera_control_android` - Two fingers camera manipulation, pinch to zoom and slide to scroll +* `camera_control_linux` - Mouse wheel and middle mouse button to control camera +* `cameras` - Camera services producing Model-View-Projection matrices +* `cameras_cache` - Cache the `Matrix` produced by `Camera::mvp_matrix` +* `display` - Abstract display services +* `display_ios` - Gamnit display implementation for iOS +* `display_linux` - Gamnit display implementation for GNU/Linux using `egl`, `sdl` and `x11` +* `egl` - Use of EGL to implement Gamnit on GNU/Linux and Android +* `font` - Abstract font drawing services, implemented by `bmfont` and `tileset` +* `gamnit_android` - Support services for Gamnit on Android +* `gamnit_ios` - Support services for gamnit on iOS +* `gamnit_linux` - Support services for Gamnit on GNU/Linux +* `input_ios` - Gamnit event support for iOS +* `landscape` - Lock the application in the landscape orientation +* `limit_fps` - Frame-rate control for applications +* `portrait` - Lock the application in the portrait orientation +* `programs` - Services for graphical programs with shaders, attributes and uniforms +* `texture_atlas_parser` - Tool to parse XML texture atlas and generated Nit code to access subtextures +* `textures` - Load textures, create subtextures and manage their life-cycle +* `tileset` - Support for `TileSet`, `TileSetFont` and drawing text with `TextSprites` + +Then run it with: + +~~~bash +./texture_atlas_parser +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/gen_nit/README.docdown.md b/lib/gen_nit/README.docdown.md new file mode 100644 index 0000000000..3e349a0619 --- /dev/null +++ b/lib/gen_nit/README.docdown.md @@ -0,0 +1,9 @@ +# `gen_nit` - [[ini-desc: gen_nit]] + +## Features + +[[features: gen_nit | mentities: gen_nit::NitModule]] + +## Authors + +This project is maintained by [[ini-maintainer: gen_nit]]. diff --git a/lib/gen_nit/README.md b/lib/gen_nit/README.md new file mode 100644 index 0000000000..397ae32f0a --- /dev/null +++ b/lib/gen_nit/README.md @@ -0,0 +1,9 @@ +# `gen_nit` - Support to generate and otherwise manipulate Nit code + +## Features + +* `NitModule` - Template of a Nit module to generate Nit code + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/geometry/README.docdown.md b/lib/geometry/README.docdown.md new file mode 100644 index 0000000000..ee40a637f6 --- /dev/null +++ b/lib/geometry/README.docdown.md @@ -0,0 +1,19 @@ +# `geometry` - [[ini-desc: geometry]] + +[[toc: geometry]] + +## Features + +[[uml: geometry | format: svg, mentities: geometry::angles;geometry::boxes;geometry::geometry;geometry::points_and_lines;geometry::polygon;geometry::quadtree]] + +### `quadtree` - QuadTree API mostly used for 2 dimensional collision detection + +[[doc: geometry::quadtree | no-synopsis]] + +## Other features + +[[features: geometry | mentities: geometry::angles;geometry::boxes;geometry::points_and_lines;geometry::polygon]] + +## Authors + +This project is maintained by [[ini-maintainer: geometry]]. diff --git a/lib/geometry/README.md b/lib/geometry/README.md new file mode 100644 index 0000000000..ec0512f2e9 --- /dev/null +++ b/lib/geometry/README.md @@ -0,0 +1,28 @@ +# `geometry` - Basic geometry data structures and services + +* [Features](#Features) +* [`quadtree` - QuadTree API mostly used for 2 dimensional collision detection](#`quadtree`---QuadTree-API-mostly-used-for-2-dimensional-collision-detection) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `geometry`](uml-geometry.svg) + +### `quadtree` - QuadTree API mostly used for 2 dimensional collision detection + +The QuadTree data structure partition a 2D space by recursively +subdividing it into 4 regions when its capacity is reached. +This module introduces 2 main implementation of the structure, +a static and a dynamic QuadTree. + +## Other features + +* `angles` - Angle related service using `Float` to represent an angle in radians +* `boxes` - Provides interfaces and classes to represent basic geometry needs. +* `points_and_lines` - Interfaces and classes to represent basic geometry needs. +* `polygon` - Convex Polygons manipulations + +## Authors + +This project is maintained by **Romain Chanoir **. diff --git a/lib/gettext/README.docdown.md b/lib/gettext/README.docdown.md new file mode 100644 index 0000000000..f89e2b263a --- /dev/null +++ b/lib/gettext/README.docdown.md @@ -0,0 +1,17 @@ +# `gettext` - [[ini-desc: gettext]] + +[[toc: gettext]] + +## Features + +### `String::get_translation` - Gets the translation of `self` via gettext from `dir` using `domain` + +[[doc: gettext::gettext::String::get_translation | no-synopsis]] + +Example from `gettext::langannot`: + +[[code: gettext::langannot]] + +## Authors + +This project is maintained by [[ini-maintainer: gettext]]. diff --git a/lib/gettext/README.md b/lib/gettext/README.md new file mode 100644 index 0000000000..b23893af88 --- /dev/null +++ b/lib/gettext/README.md @@ -0,0 +1,52 @@ +# `gettext` - Internationalization of Strings using `gettext` library + +* [Features](#Features) +* [`String::get_translation` - Gets the translation of `self` via gettext from `dir` using `domain`](#`String::get_translation`---Gets-the-translation-of-`self`-via-gettext-from-`dir`-using-`domain`) +* [Authors](#Authors) + +## Features + +### `String::get_translation` - Gets the translation of `self` via gettext from `dir` using `domain` + +`domain`: Gettext domain, i.e. file/module name +`dir`: Where the locale/LC_MESSAGES folder for this domain is located + +Example from `gettext::langannot`: + +~~~ +# Sample module showing the use of the i18n annotation +module langannot is example, i18n + +import gettext + +# Some class +class X + # Some method + fun foo: String do + return "This String is a test" + end +end + +var t = new X +print t.foo + +print "This String is a test" + +print """Multiline string + +example + + +of the language annotation capacities +""" + +var s = "example" + +print "This superstring {s} rocks" + +print "This superstring %1 rocks".format(s) +~~~ + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/github/README.docdown.md b/lib/github/README.docdown.md new file mode 100644 index 0000000000..2c27669eaf --- /dev/null +++ b/lib/github/README.docdown.md @@ -0,0 +1,67 @@ +# `github` - [[ini-desc: github]] + +[[toc: github]] + +[[doc: github::github]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: github]] + +### Run `loader` + +Compile `loader` with the following command: + +[[main-compile: github::loader]] + +## Features + +[[uml: github | format: svg, mentities: github::api;github::cache;github::events;github::github;github::github_curl;github::hooks;github::loader;github::wallet]] + +### `api` - Nit object oriented interface to [Github api](https://developer.github.com/v3/). + +[[doc: github::api | no-synopsis]] + +### `cache` - Enable caching on Github API accesses. + +[[doc: github::cache | no-synopsis]] + +### `events` - Events are emitted by Github Hooks. + +[[doc: github::events | no-synopsis]] + +### `hooks` - Github hook event listening with `nitcorn`. + +[[doc: github::hooks | no-synopsis]] + +### `wallet` - Github OAuth tokens management + +[[doc: github::wallet | no-synopsis]] + +## Other features + +[[features: github | mentities: github::github_curl;github::loader]] + +Then run it with: + +[[main-run: github::loader]] + +Options: + +[[main-opts: github::loader]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: github]] + +## Authors + +This project is maintained by [[ini-maintainer: github]]. diff --git a/lib/github/README.md b/lib/github/README.md new file mode 100644 index 0000000000..5925db4ded --- /dev/null +++ b/lib/github/README.md @@ -0,0 +1,219 @@ +# `github` - Nit wrapper for Github API + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `loader`](#Run-`loader`) +* [Features](#Features) +* [`api` - Nit object oriented interface to [Github api](https://developer.github.com/v3/).](#`api`---Nit-object-oriented-interface-to-[Github-api](https://developer.github.com/v3/).) +* [`cache` - Enable caching on Github API accesses.](#`cache`---Enable-caching-on-Github-API-accesses.) +* [`events` - Events are emitted by Github Hooks.](#`events`---Events-are-emitted-by-Github-Hooks.) +* [`hooks` - Github hook event listening with `nitcorn`.](#`hooks`---Github-hook-event-listening-with-`nitcorn`.) +* [`wallet` - Github OAuth tokens management](#`wallet`---Github-OAuth-tokens-management) +* [Other features](#Other-features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +This module provides a Nit object oriented interface to access the +[Github api](https://developer.github.com/v3/). + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `console` - Defines some ANSI Terminal Control Escape Sequences +* `curl` - Data transfer powered by the native curl library +* `json` - read and write JSON formatted text +* `nitcorn` - Lightweight framework for Web applications development +* `popcorn` - Web application framework for Nit + +### Run `loader` + +Compile `loader` with the following command: + +~~~bash +nitc ./loader.nit +~~~ + +## Features + +![Diagram for `github`](uml-github.svg) + +### `api` - Nit object oriented interface to [Github api](https://developer.github.com/v3/). + +This modules reifies Github API elements as Nit classes. + +For most use-cases you need to use the `GithubAPI` client. + +### `cache` - Enable caching on Github API accesses. + +If `GithubAPI::enable_cache` is set to true then Github JSON responses +will be cached locally using `JsonStore`. + +Cache can be used to limit the number of access on the API and lighten +the rate limit on your github key. + +Usage: + +~~~ +var api = new GithubAPI(get_github_oauth) +api.enable_cache = true + +var name = "nitlang/nit" +assert not api.has_cache(name) +var repo = api.load_repo(name) # load from GitHub +#assert api.has_cache(name) FIXME bring back this assert +repo = api.load_repo(name) # load from cache + +api.clear_cache +assert not api.has_cache(name) +~~~ + +### `events` - Events are emitted by Github Hooks. + +See + +### `hooks` - Github hook event listening with `nitcorn`. + +Usage: + +~~~ +import github::hooks + +# A simple hook listener that print received events in stdout. +class LogHookListener + super HookListener + + # Use double dispatch to implement log behavior. + redef fun apply_event(event) do event.log_event(self) +end + +redef class GithubEvent + # Log this event. + # + # Do nothing by default. + fun log_event(l: LogHookListener) do end +end + +redef class CommitCommentEvent + + redef fun log_event(l) do + print "new comment on commit {comment.commit_id}" + end +end + +var api = new GithubAPI(get_github_oauth) +var listener = new LogHookListener(api, "127.0.0.1", 8080) +# listener.listen # uncomment to start listening +~~~ + +### `wallet` - Github OAuth tokens management + +When using batch mode with the `github` API, we can rapidly reach the rate +limit allowed by Github. + +One solution consists in using a wallet of tokens so we can rely on more than +one token and switch them when one become exhausted. + +## Using the Github wallet to check tokens + +One functionality of the wallet is to check the validity of a token against +the API. `check_token` will return false if a token is invalid or exhausted. + +~~~ +var wallet = new GithubWallet +assert not wallet.check_token("this is a bad token") +~~~ + +## Storing tokens + +The wallet can also be used to store tokens and check all of them. + +~~~ +wallet = new GithubWallet +wallet.add "some token" +wallet.add "some other token" +~~~ + +or + +~~~ +wallet = new GithubWallet.from_tokens(["token 1", "token 2"]) +~~~ + +The `show_status` method can be used to display a summary of the validity of +each token in the wallet. + +~~~ +wallet.show_status +~~~ + +Will display something like this: + +~~~raw +Wallet (2 tokens): + * [OK] token 1 + * [KO] token 2 +~~~ + +## Using the wallet to obtain a Github API client + +Using the wallet you can cycle through tokens and obtain a new Github API client +instance with a fresh rate limit. + +~~~ +wallet = new GithubWallet.from_tokens(["token 1", "token 2"]) +var api = wallet.api +~~~ + +The wallet will automatically cycle through the registered tokens to find one +that works. + +If no valid token is found after all of them was tried, the wallet returns a +client based on the last tried one. + +## Other features + +* `github_curl` - Curl extention to access the Github API +* `loader` + +Then run it with: + +~~~bash +loader +~~~ + +Options: + +~~~bash +* -h, -?, --help Show this help message. +* --config Path to config file. +* --db-host MongoDb host. +* --db-name MongoDb database name. +* --tokens Token list. +* --show-wallet Show wallet status. +* -v, --verbose Verbosity level. +* --no-colors Do not use colors in output. +* --show-jobs Show jobs status. +* --no-commits Do not load commits from default branch. +* --no-issues Do not load issues. +* --no-comments Do not load issue comments. +* --no-events Do not load issues events. +* --from Start loading issues from a number. +* --clear Clear job for given repo name. +~~~ + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/glesv2/README.docdown.md b/lib/glesv2/README.docdown.md new file mode 100644 index 0000000000..b44dd5e4d9 --- /dev/null +++ b/lib/glesv2/README.docdown.md @@ -0,0 +1,23 @@ +# `glesv2` - [[ini-desc: glesv2]] + +[[toc: glesv2]] + +[[doc: glesv2::glesv2]] + +Example from `glesv2::opengles2_hello_triangle`: + +[[code: glesv2::opengles2_hello_triangle]] + +## Features + +### `GLDataType` - All data types of OpenGL ES 2.0 shaders + +[[doc: glesv2::GLDataType | no-synopsis]] + +## Other features + +[[features: glesv2 | mentities: glesv2::GLProgram;glesv2::GLShader;glesv2::GLGetParameterName;glesv2::GLShaderType;glesv2::GLFragmentShader;glesv2::GLVertexShader;glesv2::VertexArray;glesv2::GLfloatArray;glesv2::NativeGLfloatArray;glesv2::GLEnum;glesv2::GLError;glesv2::GLTextureUnit;glesv2::GLPack;glesv2::GLTexParameteri;glesv2::GLTextureTarget;glesv2::GLCap;glesv2::GLRenderbufferFormat;glesv2::GLAttachment;glesv2::GLES;glesv2::GLTexParameteriName;glesv2::GLFramebufferTarget;glesv2::GLRenderbufferTarget;glesv2::GLBufferUsage;glesv2::GLArrayBuffer;glesv2::GLFramebufferStatus;glesv2::GLHintTarget;glesv2::GLHintMode;glesv2::GLCapabilities;glesv2::GLDrawMode;glesv2::GLBlendFactor;glesv2::GLDepthFunc;glesv2::GLPixelFormat;glesv2::GLBuffer;glesv2::GLFrontFaceMode;glesv2::GLCullFaceMode]] + +## Authors + +This project is maintained by [[ini-maintainer: glesv2]]. diff --git a/lib/glesv2/README.md b/lib/glesv2/README.md new file mode 100644 index 0000000000..453b107e1b --- /dev/null +++ b/lib/glesv2/README.md @@ -0,0 +1,259 @@ +# `glesv2` - OpenGL graphics rendering library for embedded systems, version 2.0 + +* [Features](#Features) +* [`GLDataType` - All data types of OpenGL ES 2.0 shaders](#`GLDataType`---All-data-types-of-OpenGL-ES-2.0-shaders) +* [Other features](#Other-features) +* [Authors](#Authors) + +This is a low-level wrapper, it can be useful for developers already familiar +with the C API of OpenGL. Most developers will prefer to use the higher level +graphic API `gammit`. + +Defines the annotations `glsl_vertex_shader` and `glsl_fragment_shader` +applicable on string literals to check shader code using `glslangValidator`. +The tool must be in PATH. It can be downloaded from +https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/ + +Most services of this module are a direct wrapper of the underlying +C library. If a method or class is not documented in Nit, refer to +the official documentation by the Khronos Group at: +http://www.khronos.org/opengles/sdk/docs/man/ + +Example from `glesv2::opengles2_hello_triangle`: + +~~~ +# Basic example of OpenGL ES 2.0 usage using SDL 2 +# +# From the book OpenGL ES 2.0 Programming Guide, see code reference: +# https://code.google.com/p/opengles-book-samples/source/browse/trunk/LinuxX11/Chapter_2/Hello_Triangle/Hello_Triangle.c +module opengles2_hello_triangle is example + +import glesv2 +import egl +import sdl2 + +import realtime + +if "NIT_TESTING".environ == "true" then exit(0) + +var window_width = 800 +var window_height = 600 + +# +## SDL2 +# +assert sdl.initialize((new SDLInitFlags).video) else + print sdl.error +end + +var sdl_window = new SDLWindow("Title".to_cstring, window_width, window_height, (new SDLWindowFlags).opengl) +assert not sdl_window.address_is_null else print sdl.error + +var sdl_wm_info = sdl_window.wm_info +var native_window = sdl_wm_info.window_handle +var native_display = sdl_wm_info.display_handle +assert not native_display.address_is_null else print "Failed to get handle to native display" + +# +## EGL +# +var egl_display = new EGLDisplay(native_display) +assert egl_display.is_valid else print "EGL display is not valid" + +egl_display.initialize +assert egl_display.is_valid else print egl_display.error + +print "EGL version: {egl_display.version}" +print "EGL vendor: {egl_display.vendor}" +print "EGL extensions: \n* {egl_display.extensions.join("\n* ")}" +print "EGL client APIs: {egl_display.client_apis.join(", ")}" + +var config_chooser = new EGLConfigChooser +#config_chooser.surface_type_egl +config_chooser.blue_size = 8 +config_chooser.green_size = 8 +config_chooser.red_size = 8 +#config_chooser.alpha_size = 8 +#config_chooser.depth_size = 8 +#config_chooser.stencil_size = 8 +#config_chooser.sample_buffers = 1 +config_chooser.close + +var configs = config_chooser.choose(egl_display) +assert configs != null else print "choosing config failed: {egl_display.error}" +assert not configs.is_empty else print "no EGL config" + +print "{configs.length} EGL configs available" +for config in configs do + var attribs = config.attribs(egl_display) + print "* caveats: {attribs.caveat}" + print " conformant to: {attribs.conformant}" + print " size of RGBA: {attribs.red_size} {attribs.green_size} {attribs.blue_size} {attribs.alpha_size}" + print " buffer, depth, stencil: {attribs.buffer_size} {attribs.depth_size} {attribs.stencil_size}" +end + +var config = configs.first + +var surface = egl_display.create_window_surface(config, native_window, [0]) +assert surface.is_ok else print egl_display.error + +var context = egl_display.create_context(config) +assert context.is_ok else print egl_display.error + +var make_current_res = egl_display.make_current(surface, surface, context) +assert make_current_res else print egl_display.error + +var width = surface.attribs(egl_display).width +var height = surface.attribs(egl_display).height +print "Width: {width}" +print "Height: {height}" + +assert egl_bind_opengl_es_api else print "eglBingAPI failed: {egl_display.error}" + +# +## GLESv2 +# + +print "Can compile shaders? {gl.shader_compiler}" +assert_no_gl_error + +assert gl.shader_compiler else print "Cannot compile shaders" + +# gl program +print glGetError.to_s +var program = new GLProgram +if not glIsProgram(program) then + print "Program is not ok: {glGetError.to_s}\nLog:" + print glGetProgramInfoLog(program) + abort +end +assert_no_gl_error + +# vertex shader +var vertex_shader = new GLVertexShader +assert glIsShader(vertex_shader) else print "Vertex shader is not ok: {glGetError}" +glShaderSource(vertex_shader, """ +attribute vec4 vPosition; +void main() +{ + gl_Position = vPosition; +} +""".to_cstring) +glCompileShader vertex_shader +assert vertex_shader.is_compiled else print "Vertex shader compilation failed with: {glGetShaderInfoLog(vertex_shader)} {glGetProgramInfoLog(program)}" +assert_no_gl_error + +# fragment shader +var fragment_shader = new GLFragmentShader +assert glIsShader(fragment_shader) else print "Fragment shader is not ok: {glGetError}" +glShaderSource(fragment_shader, """ +precision mediump float; +void main() +{ + gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0); +} +""".to_cstring) +glCompileShader(fragment_shader) +assert fragment_shader.is_compiled else print "Fragment shader compilation failed with: {glGetShaderInfoLog(fragment_shader)}" +assert_no_gl_error + +glAttachShader(program, vertex_shader) +glAttachShader(program, fragment_shader) +program.bind_attrib_location(0, "vPosition") +glLinkProgram program +assert program.is_linked else print "Linking failed: {glGetProgramInfoLog(program)}" +assert_no_gl_error + +# prepare +glViewport(0, 0, width, height) +glClearColor(0.5, 0.0, 0.5, 1.0) + +# draw! +var vertices = [0.0, 0.5, 0.0, -0.5, -0.5, 0.0, 0.5, -0.5, 0.0] +var vertex_array = new VertexArray(0, 3, vertices) +vertex_array.attrib_pointer + +var clock = new Clock + +var n_frames = 1000 +for i in [0..n_frames[ do + printn "." + assert_no_gl_error + + glClear gl_COLOR_BUFFER_BIT + glUseProgram program + vertex_array.enable + glDrawArrays(gl_TRIANGLES, 0, 3) + egl_display.swap_buffers(surface) +end + +print "FPS: {n_frames.to_f/clock.lapse.to_f}" + +# delete +glDeleteProgram program +glDeleteShader vertex_shader +glDeleteShader fragment_shader + +# +## EGL +# +# close +egl_display.make_current(new EGLSurface.none, new EGLSurface.none, new EGLContext.none) +egl_display.destroy_context context +egl_display.destroy_surface surface + +# +## SDL2 +# +# close +sdl.quit +~~~ + +## Features + +### `GLDataType` - All data types of OpenGL ES 2.0 shaders + +These types can be used by shader uniforms, as seen with +`GLProgram::active_uniform_type`. + +## Other features + +* `GLArrayBuffer` - Target to which bind the buffer with `glBindBuffer` +* `GLAttachment` - Renderbuffer attachment point to a framebuffer +* `GLBlendFactor` - Pixel arithmetic for blending operations +* `GLBuffer` - Set of buffers as a bitwise OR mask +* `GLBufferUsage` - Expected usage of a buffer +* `GLCap` - A server-side capability +* `GLCapabilities` - Entry point to OpenGL server-side capabilities +* `GLCullFaceMode` - Candidates for culling +* `GLDepthFunc` - Condition under which a pixel will be drawn +* `GLDrawMode` - Kind of primitives to render +* `GLES` - OpenGL ES 2.0 services +* `GLEnum` - General type for OpenGL enumerations +* `GLError` - An OpenGL ES 2.0 error code +* `GLFragmentShader` - An OpenGL ES 2.0 fragment shader +* `GLFramebufferStatus` - Return value of `glCheckFramebufferStatus` +* `GLFramebufferTarget` - Target of `glBindFramebuffer` +* `GLFrontFaceMode` - Orientation of front-facing polygons +* `GLGetParameterName` - Shader parameter +* `GLHintMode` - Hint mode for `glHint` +* `GLHintTarget` - Hint target for `glHint` +* `GLPack` - Symbolic name of the parameter to be set with `glPixelStorei` +* `GLPixelFormat` - Format of pixel data +* `GLProgram` - OpenGL ES program to which we attach shaders +* `GLRenderbufferFormat` - Format for a renderbuffer +* `GLRenderbufferTarget` - Target of `glBindRenderbuffer` +* `GLShader` - Abstract OpenGL ES shader object, implemented by `GLFragmentShader` and `GLVertexShader` +* `GLShaderType` - Shader type +* `GLTexParameteri` - Texture minifying and magnifying function +* `GLTexParameteriName` - Name of parameters of textures +* `GLTextureTarget` - Target texture +* `GLTextureUnit` - Texture unit, the number of texture units is implementation dependent +* `GLVertexShader` - An OpenGL ES 2.0 vertex shader +* `GLfloatArray` - Low level array of `Float` +* `NativeGLfloatArray` - An array of `GLfloat` in C (`GLfloat*`) +* `VertexArray` - An array of `Float` associated to a program variable + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/gmp/README.docdown.md b/lib/gmp/README.docdown.md new file mode 100644 index 0000000000..be5eaf0e67 --- /dev/null +++ b/lib/gmp/README.docdown.md @@ -0,0 +1,19 @@ +# `gmp` - [[ini-desc: gmp]] + +[[toc: gmp]] + +## Features + +[[uml: gmp | format: svg, mentities: gmp::gmp;gmp::native_gmp]] + +[[features: gmp | mentities: gmp::native_gmp]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: gmp]] + +## Authors + +This project is maintained by [[ini-maintainer: gmp]]. diff --git a/lib/gmp/README.md b/lib/gmp/README.md new file mode 100644 index 0000000000..f7e945d8dc --- /dev/null +++ b/lib/gmp/README.md @@ -0,0 +1,23 @@ +# `gmp` - Multi precision integer and rational number using gmp lib + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +## Features + +![Diagram for `gmp`](uml-gmp.svg) + +* `native_gmp` - Low-level GMP features + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **PatrickBlanchette **. diff --git a/lib/graph/README.docdown.md b/lib/graph/README.docdown.md new file mode 100644 index 0000000000..32d43199b5 --- /dev/null +++ b/lib/graph/README.docdown.md @@ -0,0 +1,19 @@ +# `graph` - [[ini-desc: graph]] + +[[toc: graph]] + +## Features + +[[uml: graph | format: svg, mentities: graph::digraph;graph::pagerank]] + +### `digraph` - Implementation of directed graphs, also called digraphs. + +[[doc: graph::digraph | no-synopsis]] + +## Other features + +[[features: graph | mentities: graph::pagerank]] + +## Authors + +This project is maintained by [[ini-maintainer: graph]]. diff --git a/lib/graph/README.md b/lib/graph/README.md new file mode 100644 index 0000000000..531e2358bf --- /dev/null +++ b/lib/graph/README.md @@ -0,0 +1,150 @@ +# `graph` - Graph library for Nit + +* [Features](#Features) +* [`digraph` - Implementation of directed graphs, also called digraphs.](#`digraph`---Implementation-of-directed-graphs,-also-called-digraphs.) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `graph`](uml-graph.svg) + +### `digraph` - Implementation of directed graphs, also called digraphs. + +Overview +======== + +This module provides a simple interface together with a concrete +implementation of directed graphs (or digraphs). + +The upper level interface is `Digraph` and contains all methods for digraphs +that do not depend on the underlying data structure. More precisely, if basic +operations such as `predecessors`, `successors`, `num_vertices`, etc. are +implemented, then high level operations (such as computing the connected +components or a shortest path between two vertices) can be easily derived. +Also, all methods found in `Digraph` do no modify the graph. For mutable +methods, one needs to check the `MutableDigraph` child class. Vertices can be +any `Object`, but there is no information stored in the arcs, which are +simple arrays of the form `[u,v]`, where `u` is the source of the arc and `v` +is the target. + +There is currently only one concrete implementation named `HashDigraph` that +makes use of the HashMap class for storing the predecessors and successors. +It is therefore simple to provide another implementation: One only has to +create a concrete specialization of either `Digraph` or `MutableDigraph`. + +Basic methods +============= + +To create an (empty) new graph whose keys are integers, one simply type + +~~~ +var g0 = new HashDigraph[Int] +~~~ + +Then we can add vertices and arcs. Note that if an arc is added whose source +and target are not already in the digraph, the vertices are added beforehand. + +~~~ +var g1 = new HashDigraph[Int] +g1.add_vertex(0) +g1.add_vertex(1) +g1.add_arc(0,1) +g1.add_arc(1,2) +assert g1.to_s == "Digraph of 3 vertices and 2 arcs" +~~~ + +One might also create digraphs with strings in vertices, for instance to +represent some directed relation. However, it is currently not possible to +store values in the arcs. + +~~~ +var g2 = new HashDigraph[String] +g2.add_vertex("Amy") +g2.add_vertex("Bill") +g2.add_vertex("Chris") +g2.add_vertex("Diane") +g2.add_arc("Amy", "Bill") # Amy likes Bill +g2.add_arc("Bill", "Amy") # Bill likes Amy +g2.add_arc("Chris", "Diane") # and so on +g2.add_arc("Diane", "Amy") # and so on +~~~ + +`HashDigraph`s are mutable, i.e. one might remove arcs and/or vertices: + +~~~ +var g3 = new HashDigraph[Int] +g3.add_arc(0,1) +g3.add_arc(0,2) +g3.add_arc(1,2) +g3.add_arc(2,3) +g3.add_arc(2,4) +g3.remove_vertex(1) +g3.remove_arc(2, 4) +assert g3.to_s == "Digraph of 4 vertices and 2 arcs" +~~~ + +If one has installed [Graphviz](http://graphviz.org), it is easy to produce a +*dot* file which Graphviz process into a picture: + +~~~ +var g4 = new HashDigraph[Int] +g4.add_arcs([[0,1],[0,2],[1,2],[2,3],[2,4]]) +print g4.to_dot +# Then call "dot -Tpng -o graph.png" +~~~ + +![A graph drawing produced by Graphviz](https://github.com/nitlang/nit/blob/master/lib/graph.png) + +Other methods +============= + +There exist other methods available for digraphs and many other will be +implemented in the future. For more details, one should look at the methods +directly. For instance, the [strongly connected components] +(https://en.wikipedia.org/wiki/Strongly_connected_component) of a digraph are +returned as a [disjoint set data structure] +(https://en.wikipedia.org/wiki/Disjoint-set_data_structure) (i.e. a set of +sets): + +~~~ +var g5 = new HashDigraph[Int] +g5.add_arcs([[1,2],[2,1],[2,3],[3,4],[4,5],[5,3]]) +for component in g5.strongly_connected_components.to_partitions +do + print component +end +# Prints [1,2] and [3,4,5] +~~~ + +It is also possible to compute a shortest (directed) path between two +vertices: + +~~~ +var g6 = new HashDigraph[Int] +g6.add_arcs([[1,2],[2,1],[2,3],[3,4],[4,5],[5,3]]) +var path = g6.a_shortest_path(2, 4) +if path != null then print path else print "No path" +# Prints [2,3,4] +path = g6.a_shortest_path(4, 2) +if path != null then print path else print "No path" +# Prints "No path" +~~~ + +Extending the library +===================== + +There are at least two ways of providing new methods on digraphs. If the +method is standard and could be useful to other users, you should consider +including your implementation directly in this library. + +Otherwise, for personal use, you should simply define a new class inheriting +from `HashDigraph` and add the new services. + +## Other features + +* `pagerank` - Add PageRank computation for vertices in Digraph. + +## Authors + +This project is maintained by **Alexandre Blondin Massé **. diff --git a/lib/gtk/README.docdown.md b/lib/gtk/README.docdown.md new file mode 100644 index 0000000000..efa42c371b --- /dev/null +++ b/lib/gtk/README.docdown.md @@ -0,0 +1,13 @@ +# `gtk` - [[ini-desc: gtk]] + +[[doc: gtk::gtk]] + +## Features + +[[uml: gtk | format: svg, mentities: gtk>;gtk>v3_4>]] + +[[features: gtk | mentities: gtk::v3_10;gtk::v3_6;gtk::v3_8]] + +## Authors + +This project is maintained by [[ini-maintainer: gtk]]. diff --git a/lib/gtk/README.md b/lib/gtk/README.md new file mode 100644 index 0000000000..a053fbc83c --- /dev/null +++ b/lib/gtk/README.md @@ -0,0 +1,16 @@ +# `gtk` - GTK+ widgets and services + +By default provides services from GTK+ v3.4. +Newer features from v3.6 and v3.8 are available in the submodules v3_6 and v3_8 respectively. + +## Features + +![Diagram for `gtk`](uml-gtk.svg) + +* `v3_10` - GTK+ services added at version 3.10 +* `v3_6` - GTK+ services added at version 3.6 +* `v3_8` - GTK+ services added at version 3.8 + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/hash_debug/README.docdown.md b/lib/hash_debug/README.docdown.md new file mode 100644 index 0000000000..51af58096d --- /dev/null +++ b/lib/hash_debug/README.docdown.md @@ -0,0 +1,11 @@ +# `hash_debug` - [[ini-desc: hash_debug]] + +[[doc: hash_debug::hash_debug]] + +## Features + +[[features: hash_debug | mentities: hash_debug::hash_debug::Sys::show_hash_stats;hash_debug::hash_debug::Sys::clear_hash_stats]] + +## Authors + +This project is maintained by [[ini-maintainer: hash_debug]]. diff --git a/lib/hash_debug/README.md b/lib/hash_debug/README.md new file mode 100644 index 0000000000..150c08508c --- /dev/null +++ b/lib/hash_debug/README.md @@ -0,0 +1,26 @@ +# `hash_debug` - Inject behavior analysis to hash-collections (HashMap, HashSet, etc.) + +This module helps to detect, and track bad behavior on hash-collections, +especially collisions. + +Simple usage: + +1. compile your program with `-m hash_debug` +2. execute your program. + +Advanced usage: + +import this module and use the functions `Sys::show_hash_stats` and +`Sys::clear_hash_stats` at strategic points. + +You can also use some dynamic call-graph tools (like valgrind) and look +at callers of `HashCollection::gt_collide` and `HashCollection::st_collide`. + +## Features + +* `Sys::clear_hash_stats` - Reset the hash statistics to 0 +* `Sys::show_hash_stats` - Force the display of the current hash statistics + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/html/README.docdown.md b/lib/html/README.docdown.md new file mode 100644 index 0000000000..d09723fa80 --- /dev/null +++ b/lib/html/README.docdown.md @@ -0,0 +1,19 @@ +# `html` - [[ini-desc: html]] + +[[toc: html]] + +## Features + +[[uml: html | format: svg, mentities: html::bootstrap;html::html]] + +### `bootstrap` - HTML templates for Bootstrap components. + +[[doc: html::bootstrap | no-synopsis]] + +Example from `html::html_page`: + +[[code: html::html_page]] + +## Authors + +This project is maintained by [[ini-maintainer: html]]. diff --git a/lib/html/README.md b/lib/html/README.md new file mode 100644 index 0000000000..b199617733 --- /dev/null +++ b/lib/html/README.md @@ -0,0 +1,115 @@ +# `html` - HTML output facilities + +* [Features](#Features) +* [`bootstrap` - HTML templates for Bootstrap components.](#`bootstrap`---HTML-templates-for-Bootstrap-components.) +* [Authors](#Authors) + +## Features + +![Diagram for `html`](uml-html.svg) + +### `bootstrap` - HTML templates for Bootstrap components. + +See http://getbootstrap.com/components/ + +Example from `html::html_page`: + +~~~ +module html_page is example + +import html + +class NitHomepage + super HTMLPage + + redef fun head do + add("meta").attr("charset", "utf-8") + add("title").text("Nit") + add("link").attr("rel", "icon").attr("href", "http://nitlanguage.org/favicon.ico").attr("type", "image/x-icon") + add("link").attr("rel", "stylesheet").attr("href", "http://nitlanguage.org/style.css").attr("type", "text/css") + add("link").attr("rel", "stylesheet").attr("href", "http://nitlanguage.org/local.css").attr("type", "text/css") + end + + redef fun body do + open("article").add_class("page") + open("section").add_class("pageheader") + add_html("theNitProgramming Language") + open("header").add_class("header") + open("div").add_class("topsubtitle") + add("p").text("A Fun Language for Serious Programming") + close("div") + close("header") + close("section") + + open("div").attr("id", "pagebody") + open("section").attr("id", "content") + add("h1").text("# What is Nit?") + add("p").text("Nit is an object-oriented programming language. The goal of Nit is to propose a robust statically typed programming language where structure is not a pain.") + add("p").text("So, what does the famous hello world program look like, in Nit?") + add_html("
print 'Hello, World!'
") + + add("h1").text("# Feature Highlights") + add("h2").text("Usability") + add("p").text("Nit's goal is to be usable by real programmers for real projects") + + open("ul") + open("li") + add("a").attr("href", "http://en.wikipedia.org/wiki/KISS_principle").text("KISS principle") + close("li") + add("li").text("Script-like language without verbosity nor cryptic statements") + add("li").text("Painless static types: static typing should help programmers") + add("li").text("Efficient development, efficient execution, efficient evolution.") + close("ul") + + add("h2").text("Robustness") + add("p").text("Nit will help you to write bug-free programs") + + open("ul") + add("li").text("Strong static typing") + add("li").text("No more NullPointerException") + close("ul") + + add("h2").text("Object-Oriented") + add("p").text("Nit's guideline is to follow the most powerful OO principles") + + open("ul") + open("li") + add("a").attr("href", "./everything_is_an_object/").text("Everything is an object") + close("li") + open("li") + add("a").attr("href", "./multiple_inheritance/").text("Multiple inheritance") + close("li") + open("li") + add("a").attr("href", "./refinement/").text("Open classes") + close("li") + open("li") + add("a").attr("href", "./virtual_types/").text("Virtual types") + close("li") + close("ul") + + + add("h1").text("# Getting Started") + add("p").text("Get Nit from its Git repository:") + + add_html("
$ git clone http://nitlanguage.org/nit.git
") + add("p").text("Build the compiler (may be long):") + add_html("
$ cd nit\n")
+					add_html("$ make
") + add("p").text("Compile a program:") + add_html("
$ bin/nitc examples/hello_world.nit
") + add("p").text("Execute the program:") + add_html("
$ ./hello_world
") + close("section") + close("div") + close("article") + end +end + +var page = new NitHomepage +page.write_to stdout +page.write_to_file("nit.html") +~~~ + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/ini/README.docdown.md b/lib/ini/README.docdown.md new file mode 100644 index 0000000000..56c510fdee --- /dev/null +++ b/lib/ini/README.docdown.md @@ -0,0 +1,19 @@ +# `ini` - [[ini-desc: ini]] + +[[toc: ini]] + +[[doc: ini::ConfigTree]] + +## Features + +### `ConfigTree` - A configuration tree that can read and store data in ini format + +[[doc: ini::ConfigTree | no-synopsis]] + +Properties: + +[[features: ini::ConfigTree | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: ini]]. diff --git a/lib/ini/README.md b/lib/ini/README.md new file mode 100644 index 0000000000..0d3bc4e280 --- /dev/null +++ b/lib/ini/README.md @@ -0,0 +1,53 @@ +# `ini` - Handle ini config files + +* [Features](#Features) +* [`ConfigTree` - A configuration tree that can read and store data in ini format](#`ConfigTree`---A-configuration-tree-that-can-read-and-store-data-in-ini-format) +* [Authors](#Authors) + +Write example: + + var config = new ConfigTree("config.ini") + config["goo"] = "goo" + config["foo.bar"] = "foobar" + config["foo.baz"] = "foobaz" + config.save + assert config.to_map.length == 3 + +Read example: + + config = new ConfigTree("config.ini") + assert config.has_key("foo.bar") + assert config["foo.bar"] == "foobar" + +## Features + +### `ConfigTree` - A configuration tree that can read and store data in ini format + +Write example: + + var config = new ConfigTree("config.ini") + config["goo"] = "goo" + config["foo.bar"] = "foobar" + config["foo.baz"] = "foobaz" + config.save + assert config.to_map.length == 3 + +Read example: + + config = new ConfigTree("config.ini") + assert config.has_key("foo.bar") + assert config["foo.bar"] == "foobar" + +Properties: + +* `ConfigTree::[]` - Get the config value for `key` +* `ConfigTree::[]=` - Set `value` at `key` +* `ConfigTree::at` - Get the config values under `key` +* `ConfigTree::has_key` - Is `key` in the config? +* `ConfigTree::load` - Reload config from file +* `ConfigTree::save` - Save config to file +* `ConfigTree::to_map` - Get `self` as a Map of `key`, `value` + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/ios/README.docdown.md b/lib/ios/README.docdown.md new file mode 100644 index 0000000000..6cdaf8f1aa --- /dev/null +++ b/lib/ios/README.docdown.md @@ -0,0 +1,37 @@ +# `ios` - [[ini-desc: ios]] + +[[toc: ios]] + +Example from `ios::hello_ios`: + +[[code: ios::hello_ios]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: ios]] + +### Run `app` + +Compile `app` with the following command: + +[[main-compile: ios::app]] + +## Features + +[[uml: ios | format: svg, mentities: ios>;ios>ui>]] + +[[features: ios | mentities: ios::app;ios::assets;ios::audio;ios::data_store;ios::glkit;ios::http_request;ios::platform]] + +Then run it with: + +[[main-run: ios::app]] + +## Authors + +This project is maintained by [[ini-maintainer: ios]]. diff --git a/lib/ios/README.md b/lib/ios/README.md new file mode 100644 index 0000000000..5451422582 --- /dev/null +++ b/lib/ios/README.md @@ -0,0 +1,100 @@ +# `ios` - iOS support for _app.nit_ + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `app`](#Run-`app`) +* [Features](#Features) +* [Authors](#Authors) + +Example from `ios::hello_ios`: + +~~~ +# Simple iOS app with a single label +module hello_ios is + example + app_name "Hello iOS" + app_namespace "nit.app.hello_ios" + app_version(0, 5, git_revision) +end + +import ios + +redef class App + redef fun did_finish_launching_with_options + do + return app_delegate.hello_world + end +end + +redef class AppDelegate + + # Print and show "Hello World!" + private fun hello_world: Bool in "ObjC" `{ + + // Print to the console + NSLog(@"Hello World!"); + + // Display "Hello world!" on the screen + CGRect frame = [[UIScreen mainScreen] bounds]; + self.window = [[UIWindow alloc] initWithFrame: frame]; + self.window.backgroundColor = [UIColor whiteColor]; + + UILabel *label = [[UILabel alloc] init]; + label.text = @"Hello World!"; + label.center = CGPointMake(100, 100); + [label sizeToFit]; + + // As with `self.window` we must set a `rootViewController` + self.window.rootViewController = [[UIViewController alloc]initWithNibName:nil bundle:nil]; + self.window.rootViewController.view = label; + + [self.window addSubview: label]; + [self.window makeKeyAndVisible]; + + return YES; + `} +end +~~~ + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `app` - _app.nit_, a framework for portable applications +* `cocoa` - Cocoa API, the development layer of OS X +* `core` - Nit common library of core classes and methods +* `json` - read and write JSON formatted text + +### Run `app` + +Compile `app` with the following command: + +~~~bash +nitc ./app.nit +~~~ + +## Features + +![Diagram for `ios`](uml-ios.svg) + +* `app` - Basic structure for Nit apps on iOS +* `assets` - Implementation of `app::assets` +* `audio` - iOS implementation of `app::audio` using `AVAudioPlayer` +* `data_store` - Implements `app::data_store` using `NSUserDefaults` +* `glkit` - GLKit services to create an OpenGL ES context on iOS +* `http_request` - Implementation of `app::http_request` for iOS +* `platform` - Triggers compilation for the iOS platform + +Then run it with: + +~~~bash +./app +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/java/README.docdown.md b/lib/java/README.docdown.md new file mode 100644 index 0000000000..fe5198d8d9 --- /dev/null +++ b/lib/java/README.docdown.md @@ -0,0 +1,25 @@ +# `java` - [[ini-desc: java]] + +[[toc: java]] + +[[doc: java::java]] + +## Features + +[[uml: java | format: svg, mentities: java::collections;java::ffi_support;java::io;java::java]] + +### `collections` - Basic Java collections + +[[doc: java::collections | no-synopsis]] + +### `ffi_support` - Core supporting services for the FFI with Java + +[[doc: java::ffi_support | no-synopsis]] + +### `io` - Services from the `java.io` package + +[[doc: java::io | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: java]]. diff --git a/lib/java/README.md b/lib/java/README.md new file mode 100644 index 0000000000..f3660ff819 --- /dev/null +++ b/lib/java/README.md @@ -0,0 +1,50 @@ +# `java` - Supporting services for the FFI with Java and to access Java libraries + +* [Features](#Features) +* [`collections` - Basic Java collections](#`collections`---Basic-Java-collections) +* [`ffi_support` - Core supporting services for the FFI with Java](#`ffi_support`---Core-supporting-services-for-the-FFI-with-Java) +* [`io` - Services from the `java.io` package](#`io`---Services-from-the-`java.io`-package) +* [Authors](#Authors) + +This modules relies on `Sys::jvm`, `Sys::jni_env` and +`Sys::create_default_jvm` to get a handle on a JVM. You can adapt the +behavior of the FFI and services in this module by redefing +`Sys::create_default_jvm` and supply your own JVM object. You can manage +multiple java thread by switching the current environment in a redef +of `Sys::jni_env`, and multiple JVM using `Sys::jvm`. + +See also, the module `jvm` to control the JVM instances and access JNI functions. +You can use it to further customize the behavior of your code. + +## Features + +![Diagram for `java`](uml-java.svg) + +### `collections` - Basic Java collections + +~~~ +var coll = new JavaArray(2) + +assert coll[0].is_java_null +coll[0] = "zero".to_java_string +coll[1] = "one".to_java_string + +assert coll.length == 2 +assert coll.first.to_s == "zero" +assert coll[1].to_s == "one" +assert [for e in coll do e.to_s] == ["zero", "one"] +~~~ + +### `ffi_support` - Core supporting services for the FFI with Java + +This module *must* be imported by modules using the Java FFI. +Some might prefer to import the whole `java` package as it provides +other useful services. + +### `io` - Services from the `java.io` package + +This module is used by `android::assets_and_resources` and `android::audio`. + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/json/README.docdown.md b/lib/json/README.docdown.md new file mode 100644 index 0000000000..1372a6b15b --- /dev/null +++ b/lib/json/README.docdown.md @@ -0,0 +1,27 @@ +# `json` - [[ini-desc: json]] + +[[toc: json]] + +## Features + +[[uml: json | format: svg, mentities: json::dynamic;json::error;json::json;json::serialization_read;json::serialization_write;json::static;json::store]] + +### `dynamic` - Dynamic interface to read values from JSON strings + +[[doc: json::dynamic | no-synopsis]] + +### `static` - Static interface to read Nit objects from JSON strings + +[[doc: json::static | no-synopsis]] + +### `store` - Store and load json data. + +[[doc: json::store | no-synopsis]] + +## Other features + +[[features: json | mentities: json::error;json::serialization_read;json::serialization_write]] + +## Authors + +This project is maintained by [[ini-maintainer: json]]. diff --git a/lib/json/README.md b/lib/json/README.md new file mode 100644 index 0000000000..b357e0deac --- /dev/null +++ b/lib/json/README.md @@ -0,0 +1,114 @@ +# `json` - read and write JSON formatted text + +* [Features](#Features) +* [`dynamic` - Dynamic interface to read values from JSON strings](#`dynamic`---Dynamic-interface-to-read-values-from-JSON-strings) +* [`static` - Static interface to read Nit objects from JSON strings](#`static`---Static-interface-to-read-Nit-objects-from-JSON-strings) +* [`store` - Store and load json data.](#`store`---Store-and-load-json-data.) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `json`](uml-json.svg) + +### `dynamic` - Dynamic interface to read values from JSON strings + +Most services are in `JsonValue`, which is created by `Text::to_json_value`. + +### `static` - Static interface to read Nit objects from JSON strings + +`Text::parse_json` returns a simple Nit object from the JSON source. +This object can then be type checked as usual with `isa` and `as`. + +### `store` - Store and load json data. + +This simple system can be used to store and retrieve json data. + +## Usage + +### Initialization + +JsonStore use the file system to store and load json files. + +For initialization you need to give the directory used in the +file system to save objects. + +~~~ +var store = new JsonStore("store_dir") +~~~ + +### Documents + +With JsonStore you manage *documents*. +Documents are simple json files that can be stored and loaded from json store. + +JsonStore can store documents of type JsonObject and JsonArray. + +~~~ +var red = new JsonObject +red["name"] = "red" +red["code"] = "FF0000" +~~~ + +Data are stored under a *key*. +This is the path to the document from `JsonStore::store_dir` +without the `.json` extension. + +Examples: + +* key `document` will store data under `store_dir / "document.json"` +* key `collection/data` will store data under `store_dir / "collection/data.json"` + +~~~ +var key = "colors/red" +~~~ + +Store the object. + +~~~ +store.store_object(key, red) +~~~ + +Load the object. + +~~~ +assert store.has_key(key) +var obj = store.load_object(key) +assert obj["name"] == obj["name"] +~~~ + +### Collections + +A collection is a set of documents stored under the same path. + +~~~ +var green = new JsonObject +green["name"] = "green" +green["code"] = "00FF00" +store.store_object("colors/green", green) + +assert store.has_collection("colors") + +var col = store.list_collection("colors") +assert col.length == 2 +assert col.has("green") +assert col.has("red") +~~~ + +### Clearing store + +You can delete all the data contained in the `JsonStore::store_dir` with `clear`. + +~~~ +store.clear +~~~ + +## Other features + +* `error` - Intro `JsonParseError` which is exposed by all JSON reading APIs +* `serialization_read` - Services to read JSON: `deserialize_json` and `JsonDeserializer` +* `serialization_write` - Services to write Nit objects to JSON strings: `serialize_to_json` and `JsonSerializer` + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/jvm/README.docdown.md b/lib/jvm/README.docdown.md new file mode 100644 index 0000000000..16d5304962 --- /dev/null +++ b/lib/jvm/README.docdown.md @@ -0,0 +1,23 @@ +# `jvm` - [[ini-desc: jvm]] + +[[toc: jvm]] + +[[doc: jvm::jvm]] + +## Features + +### `JavaVMBuilder` - Utility to select options to create the VM using `create_jvm` + +[[doc: jvm::JavaVMBuilder | no-synopsis]] + +Properties: + +[[features: jvm::JavaVMBuilder | min-visibility: public, no-redef]] + +## Other features + +[[features: jvm | mentities: jvm::JavaVM;jvm::JniEnv;jvm::JClass;jvm::JMethodID;jvm::JavaObject;jvm::JNINativeMethod;jvm::JFieldID;jvm::JValue]] + +## Authors + +This project is maintained by [[ini-maintainer: jvm]]. diff --git a/lib/jvm/README.md b/lib/jvm/README.md new file mode 100644 index 0000000000..1f33eefa89 --- /dev/null +++ b/lib/jvm/README.md @@ -0,0 +1,51 @@ +# `jvm` - Java Virtual Machine invocation API and others services from the JNI C API + +* [Features](#Features) +* [`JavaVMBuilder` - Utility to select options to create the VM using `create_jvm`](#`JavaVMBuilder`---Utility-to-select-options-to-create-the-VM-using-`create_jvm`) +* [Other features](#Other-features) +* [Authors](#Authors) + +Users of this module and the Java FFI, on desktop computers, must define three environment variables: + +* `JAVA_HOME` points to the installation folder of the target Java VM. + This folder should contain the JNI header file `include/jni.h`. + e.g. `/usr/lib/jvm/default-java` on Debian Jessie. +* `JNI_LIB_PATH` points to the folder with `libjvm.so`. + e.g. `/usr/lib/jvm/default-java/jre/lib/amd64/server/` on Debian Jessie. +* `LD_LIBRARY_PATH` has the path to the folder with `libjvm.so`. + It's the same value as `JNI_LIB_PATH` but `LD_LIBRARY_PATH` is a colon separated list + which may contain other paths. + +See: http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/jniTOC.html + +## Features + +### `JavaVMBuilder` - Utility to select options to create the VM using `create_jvm` + +Usage example: + +~~~~nitish +var builder = new JavaVMBuilder +builder.options.add "-Djava.class.path=." +var jvm = builder.create_jvm +var env = builder.jni_env +~~~~ + +Properties: + +* `JavaVMBuilder::create_jvm` - Create a JVM instance, or return `null` on error + +## Other features + +* `JClass` - Represents a jni jclass +* `JFieldID` - Represents a jni jfieldID +* `JMethodID` - Represents a jni jmethodID +* `JNINativeMethod` - Represents a jni JNINNativeMethod +* `JValue` - Reprents a jni jvalue +* `JavaObject` - Represens a jni jobject +* `JavaVM` - Represents a jni JavaVM +* `JniEnv` - Represents a jni JNIEnv, which is a thread in a JavaVM + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/libevent/README.docdown.md b/lib/libevent/README.docdown.md new file mode 100644 index 0000000000..0e683922d7 --- /dev/null +++ b/lib/libevent/README.docdown.md @@ -0,0 +1,33 @@ +# `libevent` - [[ini-desc: libevent]] + +[[toc: libevent]] + +[[doc: libevent::libevent]] + +## Features + +[[uml: libevent | format: svg, mentities: libevent::NativeEventBase;libevent::NativeEvent;libevent::NativeEvSignal;libevent::EventCallback;libevent::Connection;libevent::NativeBufferEvent;libevent::NativeEvBuffer;libevent::InputNativeEvBuffer;libevent::OutputNativeEvBuffer;libevent::ConnectionListener;libevent::ConnectionFactory]] + +### `NativeEventBase` - Structure to hold information and state for a Libevent dispatch loop. + +[[doc: libevent::NativeEventBase | no-synopsis]] + +Properties: + +[[features: libevent::NativeEventBase | min-visibility: public, no-redef]] + +### `Connection` - Spawned to manage a specific connection + +[[doc: libevent::Connection | no-synopsis]] + +Properties: + +[[features: libevent::Connection | min-visibility: public, no-redef]] + +## Other features + +[[features: libevent | mentities: libevent::NativeEvent;libevent::NativeEvSignal;libevent::EventCallback;libevent::NativeBufferEvent;libevent::NativeEvBuffer;libevent::InputNativeEvBuffer;libevent::OutputNativeEvBuffer;libevent::ConnectionListener;libevent::ConnectionFactory]] + +## Authors + +This project is maintained by [[ini-maintainer: libevent]]. diff --git a/lib/libevent/README.md b/lib/libevent/README.md new file mode 100644 index 0000000000..4c55d71cfa --- /dev/null +++ b/lib/libevent/README.md @@ -0,0 +1,56 @@ +# `libevent` - Low-level wrapper around the libevent library to manage events on file descriptors + +* [Features](#Features) +* [`NativeEventBase` - Structure to hold information and state for a Libevent dispatch loop.](#`NativeEventBase`---Structure-to-hold-information-and-state-for-a-Libevent-dispatch-loop.) +* [`Connection` - Spawned to manage a specific connection](#`Connection`---Spawned-to-manage-a-specific-connection) +* [Other features](#Other-features) +* [Authors](#Authors) + +For mor information, refer to the libevent documentation at +http://monkey.org/~provos/libevent/doxygen-2.0.1/ + +## Features + +![Diagram for `libevent`](uml-libevent.svg) + +### `NativeEventBase` - Structure to hold information and state for a Libevent dispatch loop. + +The event_base lies at the center of Libevent; every application will +have one. It keeps track of all pending and active events, and +notifies your application of the active ones. + +Properties: + +* `NativeEventBase::dispatch` - Event dispatching loop +* `NativeEventBase::is_valid` - Has `self` been correctly initialized? +* `NativeEventBase::loopexit` - Exit the event loop +* `NativeEventBase::new` - Create a new event_base to use with the rest of Libevent +* `NativeEventBase::reinit` - Reinitialize the event base after a fork + +### `Connection` - Spawned to manage a specific connection + +TODO, use polls + +Properties: + +* `Connection::event_callback` - Callback method on events: EOF, user-defined timeout and unrecoverable errors +* `Connection::force_close` - Force closing this connection and freeing `native_buffer_event` +* `Connection::read_callback` - Callback method when data is available to read +* `Connection::write_callback` - Callback method on a write event +* `Connection::write_file` - Write a file to the connection + +## Other features + +* `ConnectionFactory` - Factory to listen on sockets and create new `Connection` +* `ConnectionListener` - A listener acting on an interface and port, spawns `Connection` on new connections +* `EventCallback` - Receiver of event callbacks +* `InputNativeEvBuffer` - An input buffer +* `NativeBufferEvent` - A buffer event structure, strongly associated to a connection, an input buffer and an output_buffer +* `NativeEvBuffer` - A single buffer +* `NativeEvSignal` - Signal event +* `NativeEvent` - Event, libevent's basic unit of operation +* `OutputNativeEvBuffer` - An output buffer + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/linux/README.docdown.md b/lib/linux/README.docdown.md new file mode 100644 index 0000000000..d3f4b9a80b --- /dev/null +++ b/lib/linux/README.docdown.md @@ -0,0 +1,11 @@ +# `linux` - [[ini-desc: linux]] + +## Features + +[[uml: linux | format: svg, mentities: linux::audio;linux::data_store;linux::http_request;linux::linux;linux::ui]] + +[[features: linux | mentities: linux::audio;linux::data_store;linux::http_request;linux::ui]] + +## Authors + +This project is maintained by [[ini-maintainer: linux]]. diff --git a/lib/linux/README.md b/lib/linux/README.md new file mode 100644 index 0000000000..200ae3b04d --- /dev/null +++ b/lib/linux/README.md @@ -0,0 +1,14 @@ +# `linux` - Implementation of app.nit for the Linux platform + +## Features + +![Diagram for `linux`](uml-linux.svg) + +* `audio` - `app::audio` implementation for GNU/Linux using SDL2 mixer +* `data_store` - `app::data_store` implementation on GNU/Linux +* `http_request` - Implementation of `app::http_request` using GDK and Curl +* `ui` - Implementation of the app.nit UI module for GNU/Linux + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/logic/README.docdown.md b/lib/logic/README.docdown.md new file mode 100644 index 0000000000..84e97fa99e --- /dev/null +++ b/lib/logic/README.docdown.md @@ -0,0 +1,15 @@ +# `logic` - [[ini-desc: logic]] + +[[toc: logic]] + +## Features + +[[uml: logic | format: svg, mentities: logic::lexpr;logic::logic]] + +### `lexpr` - Logical expression. + +[[doc: logic::lexpr | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: logic]]. diff --git a/lib/logic/README.md b/lib/logic/README.md new file mode 100644 index 0000000000..c73f39a6a9 --- /dev/null +++ b/lib/logic/README.md @@ -0,0 +1,44 @@ +# `logic` - First-order logic data structure and algorithm + +* [Features](#Features) +* [`lexpr` - Logical expression.](#`lexpr`---Logical-expression.) +* [Authors](#Authors) + +## Features + +![Diagram for `logic`](uml-logic.svg) + +### `lexpr` - Logical expression. + +This module provides a simple data structure for first order logic. +Basic logical operators and algorithms are provided. + +~~~ +var a = new LVar("a") +var b = new LVar("b") +var c = new LVar("c") + +assert a.to_s == "a" +assert (a|b).to_s == "(a | b)" +assert (~(a|b)).to_s == "~(a | b)" +~~~ + +Compute a negative normal form: + +~~~ +var ex = a | (b & c) +var nex = ~ex +assert ex.nnf.to_s == "(a | (b & c))" +assert nex.nnf.to_s == "(~a & (~b | ~c))" +~~~ + +Compute a conjunctive normal form: + +~~~ +assert ex.cnf.simplify.to_s == "(a|b) & (a|c)" +assert nex.cnf.simplify.to_s == "(~a) & (~b|~c)" +~~~ + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/markdown/README.docdown.md b/lib/markdown/README.docdown.md new file mode 100644 index 0000000000..ed5ce432e8 --- /dev/null +++ b/lib/markdown/README.docdown.md @@ -0,0 +1,49 @@ +# `markdown` - [[ini-desc: markdown]] + +[[toc: markdown]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: markdown]] + +### Run `nitmd` + +Compile `nitmd` with the following command: + +[[main-compile: markdown::nitmd]] + +Then run it with: + +[[main-run: markdown::nitmd]] + +Options: + +[[main-opts: markdown::nitmd]] + +## Features + +[[uml: markdown | format: svg, mentities: markdown::decorators;markdown::man;markdown::markdown;markdown::nitmd;markdown::wikilinks]] + +### `wikilinks` - Wikilinks handling. + +[[doc: markdown::wikilinks | no-synopsis]] + +## Other features + +[[features: markdown | mentities: markdown::decorators;markdown::man;markdown::nitmd]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: markdown]] + +## Authors + +This project is maintained by [[ini-maintainer: markdown]]. diff --git a/lib/markdown/README.md b/lib/markdown/README.md new file mode 100644 index 0000000000..f12ceeaa9a --- /dev/null +++ b/lib/markdown/README.md @@ -0,0 +1,73 @@ +# `markdown` - A markdown parser for Nit + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `nitmd`](#Run-`nitmd`) +* [Features](#Features) +* [`wikilinks` - Wikilinks handling.](#`wikilinks`---Wikilinks-handling.) +* [Other features](#Other-features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `config` - Configuration options for nit tools and apps +* `template` - Basic template system + +### Run `nitmd` + +Compile `nitmd` with the following command: + +~~~bash +nitc ./nitmd.nit +~~~ + +Then run it with: + +~~~bash +nitmd [-t format] +~~~ + +Options: + +~~~bash +* -h, -?, --help Show this help message. +* -t, --to Specify output format (html, md, man). +~~~ + +## Features + +![Diagram for `markdown`](uml-markdown.svg) + +### `wikilinks` - Wikilinks handling. + +Wikilinks are on the form `[[link]]`. +They can also contain a custom title with the syntax `[[title|link]]`. + +By importing this module, you enable the `MarkdownProcessor` to recognize +`TokenWikiLink` but nothing will happen until you define a +`Decorator::add_wikilink` customized to your applciation domain. + +## Other features + +* `decorators` - Decorators for `markdown` parsing. +* `man` - Simple *groff* decorator restricted for manpages. +* `nitmd` - A Markdown parser for Nit. + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/markdown2/README.docdown.md b/lib/markdown2/README.docdown.md new file mode 100644 index 0000000000..462f434561 --- /dev/null +++ b/lib/markdown2/README.docdown.md @@ -0,0 +1,67 @@ +# `markdown2` - [[ini-desc: markdown2]] + +[[toc: markdown2]] + +Example from `markdown2::example_html_rendering`: + +[[code: markdown2::example_html_rendering]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: markdown2]] + +### Run `nitmd` + +Compile `nitmd` with the following command: + +[[main-compile: markdown2::nitmd]] + +Then run it with: + +[[main-run: markdown2::nitmd]] + +Options: + +[[main-opts: markdown2::nitmd]] + +## Features + +### `markdown_block_parsing` - Markdown blocks parsing + +[[doc: markdown2::markdown_block_parsing | no-synopsis]] + +### `markdown_github` - Markdown Github mode + +[[doc: markdown2::markdown_github | no-synopsis]] + +### `markdown_inline_parsing` - Parser for inline markdown + +[[doc: markdown2::markdown_inline_parsing | no-synopsis]] + +### `markdown_maths` - Markdown Maths mode + +[[doc: markdown2::markdown_maths | no-synopsis]] + +### `markdown_wikilinks` - Markdown wikilinks processing + +[[doc: markdown2::markdown_wikilinks | no-synopsis]] + +## Other features + +[[features: markdown2 | mentities: markdown2::markdown_ast;markdown2::markdown_html_rendering;markdown2::markdown_latex_rendering;markdown2::markdown_man_rendering;markdown2::markdown_md_rendering;markdown2::markdown_rendering;markdown2::nitmd]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: markdown2]] + +## Authors + +This project is maintained by [[ini-maintainer: markdown2]]. diff --git a/lib/markdown2/README.md b/lib/markdown2/README.md new file mode 100644 index 0000000000..a7e9dd4b57 --- /dev/null +++ b/lib/markdown2/README.md @@ -0,0 +1,131 @@ +# `markdown2` - A markdown parser for Nit + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `nitmd`](#Run-`nitmd`) +* [Features](#Features) +* [`markdown_block_parsing` - Markdown blocks parsing](#`markdown_block_parsing`---Markdown-blocks-parsing) +* [`markdown_github` - Markdown Github mode](#`markdown_github`---Markdown-Github-mode) +* [`markdown_inline_parsing` - Parser for inline markdown](#`markdown_inline_parsing`---Parser-for-inline-markdown) +* [`markdown_maths` - Markdown Maths mode](#`markdown_maths`---Markdown-Maths-mode) +* [`markdown_wikilinks` - Markdown wikilinks processing](#`markdown_wikilinks`---Markdown-wikilinks-processing) +* [Other features](#Other-features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +Example from `markdown2::example_html_rendering`: + +~~~ +# An example of how you can customize the HTML output rendering for a MdNode +module example_html_rendering is example + +import markdown2::markdown_html_rendering + +# Redefine the HTML output for a `MdParagraph` +redef class MdParagraph + redef fun render_html(v) do + v.add_raw "

" + visit_all(v) + v.add_raw "

" + end +end + +# Redefine the HTML output for a `MdThematicBreak` +redef class MdThematicBreak + redef fun render_html(v) do + v.add_line + v.add_raw "
" + v.add_line + end +end +~~~ + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `config` - Configuration options for nit tools and apps +* `core` - Nit common library of core classes and methods +* `json` - read and write JSON formatted text +* `md5` - Native MD5 digest implementation as `Text::md5` +* `template` - Basic template system + +### Run `nitmd` + +Compile `nitmd` with the following command: + +~~~bash +nitc ./nitmd.nit +~~~ + +Then run it with: + +~~~bash +nitmd [-t format] +~~~ + +Options: + +~~~bash +* -t, --to Specify output format (html, md, man) +* -h, -?, --help Show Help (the list of options). +~~~ + +## Features + +### `markdown_block_parsing` - Markdown blocks parsing + +Introduce the parsers for the different Markdown blocks such as headings, lists +code blocks etc. + +### `markdown_github` - Markdown Github mode + +Enables: + +* strike processing: ~strike~ +* super processing: ^super^ + +TODO table +TODO todo lists + +### `markdown_inline_parsing` - Parser for inline markdown + +Used to create the AST representation of inline nodes like emphasis, code, links +images etc. + +### `markdown_maths` - Markdown Maths mode + +Allows to write Maths equation with the LaTeX Maths mode. + +This mode requires `tex2im` to be installed and added to the path. +See: + +### `markdown_wikilinks` - Markdown wikilinks processing + +Enables parsing of `[[wikilinks]]` syntax. + +## Other features + +* `markdown_ast` - Markdown AST representation +* `markdown_html_rendering` - HTML rendering of Markdown documents +* `markdown_latex_rendering` - LaTeX rendering of Markdown documents +* `markdown_man_rendering` - Manpages rendering of Markdown documents +* `markdown_md_rendering` - Markdown rendering of Markdown documents +* `markdown_rendering` - Markdown document rendering +* `nitmd` - A Markdown parser for Nit. + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/matrix/README.docdown.md b/lib/matrix/README.docdown.md new file mode 100644 index 0000000000..ffec8a4e87 --- /dev/null +++ b/lib/matrix/README.docdown.md @@ -0,0 +1,11 @@ +# `matrix` - [[ini-desc: matrix]] + +## Features + +[[uml: matrix | format: svg, mentities: matrix::matrix;matrix::projection]] + +[[features: matrix | mentities: matrix::projection]] + +## Authors + +This project is maintained by [[ini-maintainer: matrix]]. diff --git a/lib/matrix/README.md b/lib/matrix/README.md new file mode 100644 index 0000000000..8a9baefcee --- /dev/null +++ b/lib/matrix/README.md @@ -0,0 +1,11 @@ +# `matrix` - Services for matrices of `Float` values + +## Features + +![Diagram for `matrix`](uml-matrix.svg) + +* `projection` - Services on `Matrix` to transform and project 3D coordinates + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/md5/README.docdown.md b/lib/md5/README.docdown.md new file mode 100644 index 0000000000..f3afb05e05 --- /dev/null +++ b/lib/md5/README.docdown.md @@ -0,0 +1,19 @@ +# `md5` - [[ini-desc: md5]] + +[[toc: md5]] + +## Features + +### `Text::md5` - MD5 digest of `self` + +[[doc: md5::md5::Text::md5 | no-synopsis]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: md5]] + +## Authors + +This project is maintained by [[ini-maintainer: md5]]. diff --git a/lib/md5/README.md b/lib/md5/README.md new file mode 100644 index 0000000000..e31c89384e --- /dev/null +++ b/lib/md5/README.md @@ -0,0 +1,28 @@ +# `md5` - Native MD5 digest implementation as `Text::md5` + +* [Features](#Features) +* [`Text::md5` - MD5 digest of `self`](#`Text::md5`---MD5-digest-of-`self`) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +## Features + +### `Text::md5` - MD5 digest of `self` + +~~~ +assert "".md5 == "d41d8cd98f00b204e9800998ecf8427e" +assert "a".md5 == "0cc175b9c0f1b6a831c399e269772661" +assert "abc".md5 == "900150983cd24fb0d6963f7d28e17f72" +~~~ + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/meta/README.docdown.md b/lib/meta/README.docdown.md new file mode 100644 index 0000000000..3c7e159ad6 --- /dev/null +++ b/lib/meta/README.docdown.md @@ -0,0 +1,19 @@ +# `meta` - [[ini-desc: meta]] + +[[toc: meta]] + +[[doc: meta::meta]] + +## Features + +### `GetName` - Helper to get the name of a type + +[[doc: meta::GetName | no-synopsis]] + +## Other features + +[[features: meta | mentities: meta::Class]] + +## Authors + +This project is maintained by [[ini-maintainer: meta]]. diff --git a/lib/meta/README.md b/lib/meta/README.md new file mode 100644 index 0000000000..5db05296b6 --- /dev/null +++ b/lib/meta/README.md @@ -0,0 +1,82 @@ +# `meta` - Simple user-defined meta-level to manipulate types of instances as object + +* [Features](#Features) +* [`GetName` - Helper to get the name of a type](#`GetName`---Helper-to-get-the-name-of-a-type) +* [Other features](#Other-features) +* [Authors](#Authors) + +Unfortunately, since the meta-objects are user-defined they are provided without +any pre-defined information or behavior. +For the same reasons, the Nit OO mechanisms do not rely on this user-defined meta-level. + +However `meta` permits the definition of user-defined meta-classes at any level +of meta, even with user-defined meta-loops. + +## Meta-classes + +Meta-classes can be defined easily in 3 steps: + +* define a root for the class hierarchy (eg `XObject`) +* define a meta-class (eq `XClass[E: XObject] super Class[E]`) +* redefine `CLASS` and `class_factory` in the root + +~~~nitish because broke with nitc, see Limitation bellow +class XObject + redef CLASS: XClass[SELF] + redef class_factory(name) do return new XClass[SELF](name) +end +class XClass[E: XObject] super Class[E] end + +var x1 = new XObject +var x2 = new XObject +assert x1.get_class == x2.get_class +assert x1.get_class isa XClass[XObject] +assert x1.get_class.get_class isa Class[XClass[XObject]] +~~~ + +## Limitation + +Currently works only with the interpreter `nit` and the compiler with `--erasure` (without `--rta`). + +`--rta` will try to detect all the runtime types, and will infinitely discover `Class[Class[Class[....]]]`. +Unfortunately, `--separate` and `--global` require `--rta`. + +Moreover, the interpreter and `--erasure` have a different behavior with generics since +with `--erasure` a single meta-instance is shared for all type variations of a same generic class. + +Class names are used as a primary key to identify classes. +But name conflicts are not managed and will make the program crashes at runtime (on some cast error) + +## Features + +### `GetName` - Helper to get the name of a type + +This is one of the hackiest way to retrieve the name of a random type. + +~~~ +var dummy = new GetName[Sequence[nullable Comparable]] +assert dummy.to_s == "Sequence[nullable Comparable]" +~~~ + +This also works to resolve formal types + +~~~ +class G[T] + type V: Collection[T] + + var name_of_v: String = (new GetName[V]).to_s is lazy +end + +var g = new G[Bool] +assert g.name_of_v == "Collection[Bool]" +~~~ + +Warning: this does not work if --erasure is used. + +## Other features + +* `Class` - This meta-class is the root the meta-class hierarchy + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/mnit/README.docdown.md b/lib/mnit/README.docdown.md new file mode 100644 index 0000000000..01a0336d8e --- /dev/null +++ b/lib/mnit/README.docdown.md @@ -0,0 +1,23 @@ +# `mnit` + +[[toc: mnit]] + +## Features + +[[uml: mnit | format: svg, mentities: mnit::InputEvent;mnit::PointerEvent;mnit::MotionEvent;mnit::TouchEvent;mnit::KeyEvent;mnit::MobileKeyEvent;mnit::SensorEvent;mnit::QuitEvent]] + +### `MotionEvent` - A motion event on screen composed of many `PointerEvent` + +[[doc: mnit::MotionEvent | no-synopsis]] + +Properties: + +[[features: mnit::MotionEvent | min-visibility: public, no-redef]] + +## Other features + +[[features: mnit | mentities: mnit::InputEvent;mnit::PointerEvent;mnit::TouchEvent;mnit::KeyEvent;mnit::MobileKeyEvent;mnit::SensorEvent;mnit::QuitEvent]] + +## Authors + +This project is maintained by [[ini-maintainer: mnit]]. diff --git a/lib/mnit/README.md b/lib/mnit/README.md new file mode 100644 index 0000000000..6dee186523 --- /dev/null +++ b/lib/mnit/README.md @@ -0,0 +1,33 @@ +# `mnit` + +* [Features](#Features) +* [`MotionEvent` - A motion event on screen composed of many `PointerEvent`](#`MotionEvent`---A-motion-event-on-screen-composed-of-many-`PointerEvent`) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `mnit`](uml-mnit.svg) + +### `MotionEvent` - A motion event on screen composed of many `PointerEvent` + +Example of a `MotionEvent` a gesture such as pinching using two fingers. + +Properties: + +* `MotionEvent::down_pointer` - Which pointer is down, if any +* `MotionEvent::just_went_down` - A pointer just went down? + +## Other features + +* `InputEvent` - Input to the App, propagated through `App::input`. +* `KeyEvent` - Keyboard or other keys event +* `MobileKeyEvent` - Mobile hardware (or pseudo hardware) event +* `PointerEvent` - Mouse and touch input events +* `QuitEvent` - Quit event, used for window close button +* `SensorEvent` - Sensor events like accelerometer, gyroscope etc for mobile apps +* `TouchEvent` - Specific touch event + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/mongodb/README.docdown.md b/lib/mongodb/README.docdown.md new file mode 100644 index 0000000000..d401e38109 --- /dev/null +++ b/lib/mongodb/README.docdown.md @@ -0,0 +1,21 @@ +# `mongodb` - [[ini-desc: mongodb]] + +[[toc: mongodb]] + +[[doc: mongodb::mongodb]] + +## Features + +[[uml: mongodb | format: svg, mentities: mongodb::mongodb;mongodb::native_mongodb;mongodb::queries]] + +### `native_mongodb` - Native wrapper for the MongoDB C Driver + +[[doc: mongodb::native_mongodb | no-synopsis]] + +### `queries` - Mongo queries framework + +[[doc: mongodb::queries | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: mongodb]]. diff --git a/lib/mongodb/README.md b/lib/mongodb/README.md new file mode 100644 index 0000000000..fe444b4656 --- /dev/null +++ b/lib/mongodb/README.md @@ -0,0 +1,81 @@ +# `mongodb` - MongoDB Nit Driver + +* [Features](#Features) +* [`native_mongodb` - Native wrapper for the MongoDB C Driver](#`native_mongodb`---Native-wrapper-for-the-MongoDB-C-Driver) +* [`queries` - Mongo queries framework](#`queries`---Mongo-queries-framework) +* [Authors](#Authors) + +This is actually a wrapper around the [MongoDB C Driver](http://api.mongodb.org/c/1.1.4/index.html). + +Usage: + +~~~ +# Opens the connexion with the Mongo server. +var client = new MongoClient("mongodb://localhost:27017/") + +# Select the database. +var db_suffix = "NIT_TESTING_ID".environ +var db_name = "test_{db_suffix}" +var db = client.database(db_name) + +# Retrieve a collection. +var col = db.collection("test") + +# Insert a document in the collection. +var doc = new JsonObject +doc["foo"] = 10 +doc["bar"] = "bar" +doc["baz"] = new JsonArray +assert col.insert(doc) + +# Retrieve a document from the collection. +var query = new JsonObject +query["foo"] = 10 +var res = col.find(query) +assert res["bar"] == "bar" +~~~ + +## Features + +![Diagram for `mongodb`](uml-mongodb.svg) + +### `native_mongodb` - Native wrapper for the MongoDB C Driver + +See [mongoc](http://api.mongodb.org/c/1.1.4/index.html). + +### `queries` - Mongo queries framework + +The `queries` framework is used to build Mongo queries as JsonObject with +a fluent interface. + +Using the `queries` framework we can get from this: + +~~~nitish +var exists = new JsonObject +exists["$exists"] = true + +var query = new JsonObject +query["login"] = "Morriar" +query["email"] = exists + +collection.find(query) +~~~ + +To this: + +~~~nitish +collection.find((new MongoMatch).eq("login", "Morriar").exists("email", true)) +~~~ + +The framework provides three classes used to map the MongoDB query API: + +* `MongoMatch` the base query that can be used with most Mongo services +* `MongoPipeline` the array of queries that is expected by `MongoCollection::aggregate` +* `MongoGroup` the group query for a `MongoPipeline` + +More on this features can be found in the official MongoDB documentation: +https://docs.mongodb.com/manual/reference/operator/ + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/more_collections/README.docdown.md b/lib/more_collections/README.docdown.md new file mode 100644 index 0000000000..60dd8141d2 --- /dev/null +++ b/lib/more_collections/README.docdown.md @@ -0,0 +1,9 @@ +# `more_collections` - [[ini-desc: more_collections]] + +## Features + +[[features: more_collections | mentities: more_collections::MultiHashMap;more_collections::HashMap2;more_collections::HashMap3;more_collections::HashMap4;more_collections::DefaultMap;more_collections::UnrolledList;more_collections::BestDistance]] + +## Authors + +This project is maintained by [[ini-maintainer: more_collections]]. diff --git a/lib/more_collections/README.md b/lib/more_collections/README.md new file mode 100644 index 0000000000..052d0f830b --- /dev/null +++ b/lib/more_collections/README.md @@ -0,0 +1,15 @@ +# `more_collections` - Highly specific, but useful, collections-related classes + +## Features + +* `BestDistance` - Keep track of the best elements according to a distance value. +* `DefaultMap` - A map with a default value. +* `HashMap2` - Simple way to store an `HashMap[K1, HashMap[K2, V]]` +* `HashMap3` - Simple way to store an `HashMap[K1, HashMap[K2, HashMap[K3, V]]]` +* `HashMap4` - Simple way to store an `HashMap[K1, HashMap[K2, HashMap[K3, HashMap[K4, V]]]]` +* `MultiHashMap` - Simple way to store an `HashMap[K, Array[V]]` +* `UnrolledList` - An unrolled linked list + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/mpd/README.docdown.md b/lib/mpd/README.docdown.md new file mode 100644 index 0000000000..8815384f97 --- /dev/null +++ b/lib/mpd/README.docdown.md @@ -0,0 +1,9 @@ +# `mpd` - [[ini-desc: mpd]] + +## Features + +[[features: mpd | mentities: mpd::MPDConnection;mpd::SongInfo;mpd::ServerStatus]] + +## Authors + +This project is maintained by [[ini-maintainer: mpd]]. diff --git a/lib/mpd/README.md b/lib/mpd/README.md new file mode 100644 index 0000000000..82ec451403 --- /dev/null +++ b/lib/mpd/README.md @@ -0,0 +1,11 @@ +# `mpd` - Music Player Daemon client library + +## Features + +* `MPDConnection` - Connection to a MPD server +* `ServerStatus` - MPD server status +* `SongInfo` - MPD song info + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/mpi/README.docdown.md b/lib/mpi/README.docdown.md new file mode 100644 index 0000000000..094d06a237 --- /dev/null +++ b/lib/mpi/README.docdown.md @@ -0,0 +1,35 @@ +# `mpi` - [[ini-desc: mpi]] + +[[toc: mpi]] + +[[doc: mpi::mpi]] + +## Features + +### `Op` - An MPI operation + +[[doc: mpi::Op | no-synopsis]] + +Properties: + +[[features: mpi::Op | min-visibility: public, no-redef]] + +Example from `mpi::mpi_simple`: + +[[code: mpi::mpi_simple]] + +### `Sendable` - Something sendable directly and efficiently over MPI + +[[doc: mpi::Sendable | no-synopsis]] + +### `Receptacle` - Something which can receive data directly and efficiently from MPI + +[[doc: mpi::Receptacle | no-synopsis]] + +## Other features + +[[features: mpi | mentities: mpi::MPI;mpi::Comm;mpi::DataType;mpi::Status;mpi::SuccessOrError;mpi::ErrorClass;mpi::Rank;mpi::Tag]] + +## Authors + +This project is maintained by [[ini-maintainer: mpi]]. diff --git a/lib/mpi/README.md b/lib/mpi/README.md new file mode 100644 index 0000000000..e7ee07509e --- /dev/null +++ b/lib/mpi/README.md @@ -0,0 +1,163 @@ +# `mpi` - Implementation of the Message Passing Interface protocol by wrapping OpenMPI + +* [Features](#Features) +* [`Op` - An MPI operation](#`Op`---An-MPI-operation) +* [`Sendable` - Something sendable directly and efficiently over MPI](#`Sendable`---Something-sendable-directly-and-efficiently-over-MPI) +* [`Receptacle` - Something which can receive data directly and efficiently from MPI](#`Receptacle`---Something-which-can-receive-data-directly-and-efficiently-from-MPI) +* [Other features](#Other-features) +* [Authors](#Authors) + +OpenMPI is used only at linking and for it's `mpi.h`. Other implementations +could be used without much modification. + +Supports transfer of any valid `Serializable` instances as well as basic +C arrays defined in module `c`. Using C arrays is encouraged when performance +is critical. + +Since this module is a thin wrapper around OpenMPI, in case of missing +documentation, you can refer to https://www.open-mpi.org/doc/v1.8/. + +## Features + +### `Op` - An MPI operation + +Used with the `reduce` method. + +See + +Properties: + +* `Op::band` - Get a MPI bit-wise and operation. +* `Op::bor` - Get a MPI bit-wise or operation. +* `Op::bxor` - Get a MPI bit-wise xor operation. +* `Op::land` - Get a MPI logical and operation. +* `Op::lor` - Get a MPI logical or operation. +* `Op::lxor` - Get a MPI logical xor operation. +* `Op::max` - Get a MPI maximum operation. +* `Op::maxloc` - Get a MPI maxloc operation. +* `Op::min` - Get a MPI minimum operation. +* `Op::minloc` - Get a MPI minloc operation. +* `Op::op_null` - Get a MPI null operation. +* `Op::prod` - Get a MPI product operation. +* `Op::replace` - Get a MPI replace operation. +* `Op::sum` - Get a MPI sum operation. + +Example from `mpi::mpi_simple`: + +~~~ +module mpi_simple is example + +import mpi + +# Simple class transfered between processors +class ProcessorInfo + auto_serializable + + var rank: Int + var size: Int + var name: String + var string_of_random_length: String + + init(mpi: MPI) + do + self.rank = comm_world.rank.to_i + self.size = comm_world.size + self.name = mpi.processor_name + self.string_of_random_length = "+" * 10.rand + end + + redef fun to_s do return "<{name}: {rank}/{size} {string_of_random_length}>" +end + +var mpi = new MPI + +var data = new CIntArray(2) +if comm_world.size == 1 then + print "not enough nodes, got only 1" + mpi.finalize + exit 1 +end + +print "stdout: processor '{mpi.processor_name}' {comm_world.rank}/{comm_world.size}" + +if comm_world.rank == 0.rank then + # send - ints + data[0] = 123 + data[1] = 456 + mpi.send_from(data, 0, 2, 1.rank, 0.tag, comm_world) + + # send - simple string + mpi.send_all("Hello", 1.rank, 0.tag, comm_world) + mpi.send_from(" World", 0, 6, 1.rank, 0.tag, comm_world) + mpi.send_from("+-!0?", 2, 2, 1.rank, 0.tag, comm_world) +else if comm_world.rank == 1.rank then + + # recv - ints + mpi.recv_into(data, 0, 2, 0.rank, 0.tag, comm_world) + print "received data: {data[0]} {data[1]}" + + # recv - simple string + var buf = new FlatBuffer.with_capacity(5) + mpi.recv_fill(buf, 0.rank, 0.tag, comm_world) + print "received string: {buf}" + + mpi.recv_into(buf, 5, 6, 0.rank, 0.tag, comm_world) + print "received string: {buf}" + + mpi.recv_into(buf, 3, 2, 0.rank, 0.tag, comm_world) + print "received string: {buf}" +end + +# Passing complex objects and inverse sender/receiver +if comm_world.rank == 0.rank then + var errors = 0 + var processors_per_host = new HashMap[String, Int] + + # recv - serializable + for p in [1 .. comm_world.size[ do + var a = mpi.recv(new Rank.any, 0.tag, comm_world) + print "received serialized: {a or else ""}" + + if a != null and a isa ProcessorInfo then + if not processors_per_host.keys.has(a.name) then + processors_per_host[a.name] = 1 + else processors_per_host[a.name] += 1 + else errors += 1 + end + + print "errors: {errors}" + print "processors: {processors_per_host.join(", ", ": ")}" +else + # send - serializable + srand_from comm_world.rank.to_i + var a = new ProcessorInfo(mpi) + mpi.send(a, 0.rank, 0.tag, comm_world) +end + +mpi.finalize +~~~ + +### `Sendable` - Something sendable directly and efficiently over MPI + +Subclasses of `Sendable` should use the native MPI send function, without +using Nit serialization. + +### `Receptacle` - Something which can receive data directly and efficiently from MPI + +Subclasses of `Receptacle` should use the native MPI recveive function, +without using Nit serialization. + +## Other features + +* `Comm` - An MPI communicator +* `DataType` - An MPI data type +* `ErrorClass` - An MPI error class +* `MPI` - Handle to most MPI services +* `Rank` - An MPI rank within a communcator +* `Status` - Status of a communication used by `MPI::probe` +* `SuccessOrError` - An MPI return code to report success or errors +* `Tag` - An MPI tag, can be defined using `Int::tag` + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/msgpack/README.docdown.md b/lib/msgpack/README.docdown.md new file mode 100644 index 0000000000..4d1b5f6ae4 --- /dev/null +++ b/lib/msgpack/README.docdown.md @@ -0,0 +1,45 @@ +# `msgpack` - [[ini-desc: msgpack]] + +[[toc: msgpack]] + +[[doc: msgpack::msgpack]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: msgpack]] + +### Run `msgpack_to_json` + +Compile `msgpack_to_json` with the following command: + +[[main-compile: msgpack::msgpack_to_json]] + +## Features + +[[uml: msgpack | format: svg, mentities: msgpack::ext;msgpack::msgpack;msgpack::msgpack_to_json;msgpack::read;msgpack::serialization_common;msgpack::serialization_read;msgpack::serialization_write;msgpack::write]] + +### `serialization_read` - Deserialize full Nit objects from MessagePack format + +[[doc: msgpack::serialization_read | no-synopsis]] + +### `serialization_write` - Serialize full Nit objects to MessagePack format + +[[doc: msgpack::serialization_write | no-synopsis]] + +## Other features + +[[features: msgpack | mentities: msgpack::ext;msgpack::msgpack_to_json;msgpack::read;msgpack::serialization_common;msgpack::write]] + +Then run it with: + +[[main-run: msgpack::msgpack_to_json]] + +## Authors + +This project is maintained by [[ini-maintainer: msgpack]]. diff --git a/lib/msgpack/README.md b/lib/msgpack/README.md new file mode 100644 index 0000000000..3a8bea3ebc --- /dev/null +++ b/lib/msgpack/README.md @@ -0,0 +1,212 @@ +# `msgpack` - MessagePack, an efficient binary serialization format + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `msgpack_to_json`](#Run-`msgpack_to_json`) +* [Features](#Features) +* [`serialization_read` - Deserialize full Nit objects from MessagePack format](#`serialization_read`---Deserialize-full-Nit-objects-from-MessagePack-format) +* [`serialization_write` - Serialize full Nit objects to MessagePack format](#`serialization_write`---Serialize-full-Nit-objects-to-MessagePack-format) +* [Other features](#Other-features) +* [Authors](#Authors) + +This modules provides services at different levels: + +* Serialize Nit objects using either the quick and easy `Serializable::serialize_msgpack` + and `Write::serialize_msgpack`, or the extensible `MsgPackSerializer`. + +* Deserialize MessagePack to Nit objects using the quick and easy methods + `Reader|Bytes::deserialize_msgpack`, or inspect errors with the extensible + `MsgPackDeserializer`. + +* Read and write MessagePack data at a low-level (for engines and the likes) + by importing `msgpack::read` or `msgpack::write`. These services support + only which support only core Nit types with a corresponding MessagePack type. + See `Reader::read_msgpack` and services on `Writer` including `write_msgpack_ext`. + +Here we discuss the recommended serialization services supporting core +Nit and MessagePack types as well as full Nit objects. + +## Primitive MessagePack types + +Most Nit core types are serialized to the smallest corresponding MessagePack type. + +~~~ +assert false.serialize_msgpack == b"\xC2" +assert b"\xC2".deserialize_msgpack == false + +assert true.serialize_msgpack == b"\xC3" +assert b"\xC3".deserialize_msgpack == true + +assert 1.234.serialize_msgpack == b"\xCB\x3F\xF3\xBE\x76\xC8\xB4\x39\x58" +assert b"\xCB\x3F\xF3\xBE\x76\xC8\xB4\x39\x58".deserialize_msgpack == 1.234 + +assert "ABC".serialize_msgpack == b"\xA3ABC" +assert b"\xA3ABC".deserialize_msgpack == "ABC" + +assert [0x11, 0x22, 0x33].serialize_msgpack(plain=true) == b"\x93\x11\x22\x33" +assert b"\x93\x11\x22\x33".deserialize_msgpack == [0x11, 0x22, 0x33] + +var map = new Map[String, nullable Object] +map["i"] = 1 +map["o"] = null +assert map.serialize_msgpack(plain=true) == b"\x82\xA1\x69\x01\xA1\x6F\xC0" +~~~ + +Ints are serialized to the smallest MessagePack type, so a small integer fits +in a single byte and larger integers take more bytes as needed. + +~~~ +assert 1.serialize_msgpack == b"\x01" +assert (-32).serialize_msgpack == b"\xE0" +assert 0x7F.serialize_msgpack == b"\x7F" +assert 0x80.serialize_msgpack == b"\xCC\x80" +assert 0x1234.serialize_msgpack == b"\xCD\x12\x34" +assert (-0x1234).serialize_msgpack == b"\xD1\xED\xCC" +assert 0x12345678.serialize_msgpack == b"\xCE\x12\x34\x56\x78" +assert 0x0123456789.serialize_msgpack == b"\xCF\x00\x00\x00\x01\x23\x45\x67\x89" + +assert b"\x01".deserialize_msgpack == 1 +assert b"\xE0".deserialize_msgpack == -32 +assert b"\x7F".deserialize_msgpack == 0x7F +assert b"\xCC\x80".deserialize_msgpack == 0x80 +assert b"\xCD\x12\x34".deserialize_msgpack == 0x1234 +assert b"\xD1\xED\xCC".deserialize_msgpack == -0x1234 +assert b"\xCE\x12\x34\x56\x78".deserialize_msgpack == 0x12345678 +assert b"\xCF\x00\x00\x00\x01\x23\x45\x67\x89".deserialize_msgpack == 0x0123456789 +~~~ + +## Primitive Nit type without a MessagePack equivalent + +Chars are serialized as a string in plain mode. + +~~~ +assert 'A'.serialize_msgpack(plain=true) == b"\xA1\x41" +assert b"\xA1\x41".deserialize_msgpack == "A" # Not a Char +~~~ + +Or, with metadata, chars are serialized to an ext with id 0x7C. + +~~~ +assert 'A'.serialize_msgpack == b"\xD4\x7C\x41" +assert b"\xD4\x7C\x41".deserialize_msgpack == 'A' +~~~ + +Byte instances are serialized as an integer in plain mode. + +~~~ +assert 0x01u8.serialize_msgpack(plain=true) == b"\x01" +assert b"\x01".deserialize_msgpack == 1 # Not a Byte +~~~ + +Or, with metadata, byte instances are serialized to an ext with id 0x7E. + +~~~ +assert 0x01u8.serialize_msgpack == b"\xD4\x7E\x01" +assert b"\xD4\x7E\x01".deserialize_msgpack == 1 +~~~ + +## Full objects + +Objects are serialized to a map in plain mode, replacing cycles by `null` values. +This creates plain MessagePack easy to read for other non-Nit programs, +but cycles and the dynamic type information are lost. + +~~~ +class A + serialize + + var i = 1 + var o: nullable A = self + + redef fun ==(o) do return o isa A and o.i == i # Skip the cyclic `o` +end + +var a = new A +var bytes = a.serialize_msgpack(plain=true) +assert bytes == b"\x82\xA1\x69\x01\xA1\x6F\xC0" +assert bytes.deserialize_msgpack isa Map[nullable Serializable, nullable Serializable] # Not an A +~~~ + +Or, with metadata, the same object is serialized with information on object +uniqueness (with an id and references) and its dynamic type. +The whole object is contained in a MessagePack array: + +* The array holds the metadata and attributes or each object, + here it is a fixarray of 3 items: 0x93 +* Define an object (ext type 0x7B) with the id 0, here a fixext1: 0xD47B00 +* The dynamic type name, here a fixstr with the letter 'A': 0xA141 +* The attributes as a map, here a fixmap of 2 items: 0x82 +* First attribute name, here a fixstr for "i": 0xA169 +* First attribute value, here a fixint for 1: 0x01 +* Second attribute name, here a fixstr for "o": 0xA16F +* Second attribute value, a reference (ext type 0x7D) to object id 0, + here a fixext1: 0xD47D00 + +~~~ +bytes = a.serialize_msgpack +assert bytes == b"\x93\xD4\x7B\x00\xA1\x41\x82\xA1\x69\x01\xA1\x6F\xD4\x7D\x00" +assert bytes.deserialize_msgpack == a +~~~ + +## References + +Format description and other implementations: http://msgpack.org/ + +Format specification: https://github.com/msgpack/msgpack/blob/master/spec.md + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `binary` - Read and write binary data with any `Reader` and `Writer` +* `core` - Nit common library of core classes and methods +* `json` - read and write JSON formatted text +* `serialization` - Abstract serialization services + +### Run `msgpack_to_json` + +Compile `msgpack_to_json` with the following command: + +~~~bash +nitc ./msgpack_to_json.nit +~~~ + +## Features + +![Diagram for `msgpack`](uml-msgpack.svg) + +### `serialization_read` - Deserialize full Nit objects from MessagePack format + +See the package `msgpack` for more details on the serialization +of Nit objects. + +### `serialization_write` - Serialize full Nit objects to MessagePack format + +There are 3 main entrypoint services: + +* `Writer::serialize_msgpack` adds an object to any stream writer. +* `Serializable::serialize_msgpack` serializes the object to bytes. +* `MsgPackSerializer` gives full control over the serialization of + Nit objets to the MessagePack format. + +## Other features + +* `ext` - Application specific MessagePack extension `MsgPackExt` +* `msgpack_to_json` - Convert MessagePack format to JSON +* `read` - Low-level read MessagePack format from `Reader` streams +* `serialization_common` - Serialization services for `serialization_write` and `serialization_read` +* `write` - Low-level write in MessagePack format to `Writer` streams + +Then run it with: + +~~~bash +./msgpack_to_json +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/neo4j/README.docdown.md b/lib/neo4j/README.docdown.md new file mode 100644 index 0000000000..9b051a14ad --- /dev/null +++ b/lib/neo4j/README.docdown.md @@ -0,0 +1,13 @@ +# `neo4j` - [[ini-desc: neo4j]] + +[[doc: neo4j::neo4j]] + +## Features + +[[uml: neo4j | format: svg, mentities: neo4j>;neo4j>graph>]] + +[[features: neo4j | mentities: neo4j::curl_json;neo4j::error]] + +## Authors + +This project is maintained by [[ini-maintainer: neo4j]]. diff --git a/lib/neo4j/README.md b/lib/neo4j/README.md new file mode 100644 index 0000000000..6c8b6ab873 --- /dev/null +++ b/lib/neo4j/README.md @@ -0,0 +1,60 @@ +# `neo4j` - Neo4j connector through its JSON REST API using curl + +For ease of use and testing this module provide a wrapper to the `neo4j` command: + + # Start the Neo4j server + var srv = new Neo4jServer + assert srv.start_quiet + +In order to connect to Neo4j you need a connector: + + # Create new Neo4j client + var client = new Neo4jClient("http://localhost:7474") + assert client.is_ok + +The fundamental units that form a graph are nodes and relationships. + +Nodes are used to represent entities stored in base: + + # Create a disconnected node + var andres = new NeoNode + andres["name"] = "Andres" + # Connect the node to Neo4j + client.save_node(andres) + assert andres.is_linked + + # Create a second node + var kate = new NeoNode + kate["name"] = "Kate" + client.save_node(kate) + assert kate.is_linked + +Relationships between nodes are a key part of a graph database. +They allow for finding related data. Just like nodes, relationships can have properties. + + # Create a relationship + var loves = new NeoEdge(andres, "LOVES", kate) + client.save_edge(loves) + assert loves.is_linked + +Nodes can also be loaded fron Neo4j: + + # Get a node from DB and explore edges + var url = andres.url.to_s + var from = client.load_node(url) + assert from["name"].to_s == "Andres" + var to = from.out_nodes("LOVES").first # follow the first LOVES relationship + assert to["name"].to_s == "Kate" + +For more details, see http://docs.neo4j.org/chunked/milestone/rest-api.html + +## Features + +![Diagram for `neo4j`](uml-neo4j.svg) + +* `curl_json` - cURL requests compatible with the JSON REST APIs. +* `error` - Errors thrown by the `neo4j` library. + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/nitcc_runtime/README.docdown.md b/lib/nitcc_runtime/README.docdown.md new file mode 100644 index 0000000000..2417dae805 --- /dev/null +++ b/lib/nitcc_runtime/README.docdown.md @@ -0,0 +1,9 @@ +# `nitcc_runtime` - [[ini-desc: nitcc_runtime]] + +## Features + +[[features: nitcc_runtime | mentities: nitcc_runtime::Parser;nitcc_runtime::LRState;nitcc_runtime::LRGoto;nitcc_runtime::Lexer;nitcc_runtime::DFAState;nitcc_runtime::Visitor;nitcc_runtime::TreePrinterVisitor;nitcc_runtime::Position;nitcc_runtime::Node;nitcc_runtime::NToken;nitcc_runtime::NEof;nitcc_runtime::NError;nitcc_runtime::NLexerError;nitcc_runtime::NParserError;nitcc_runtime::Nodes;nitcc_runtime::NProd;nitcc_runtime::TestParser]] + +## Authors + +This project is maintained by [[ini-maintainer: nitcc_runtime]]. diff --git a/lib/nitcc_runtime/README.md b/lib/nitcc_runtime/README.md new file mode 100644 index 0000000000..f55f870cf9 --- /dev/null +++ b/lib/nitcc_runtime/README.md @@ -0,0 +1,25 @@ +# `nitcc_runtime` - Runtime library required by parsers and lexers generated by nitcc + +## Features + +* `DFAState` - A state in a lexer automaton generated by nitcc +* `LRGoto` - A concrete production in a parser LR automation generated by nitcc +* `LRState` - A state in a parser LR automaton generated by nitcc +* `Lexer` - A abstract lexer engine generated by nitcc +* `NEof` - The special token for the end of stream +* `NError` - A special token used to represent a parser or lexer error +* `NLexerError` - A lexer error as a token for the unexpected characted +* `NParserError` - A parser error linked to a unexpected token +* `NProd` - A production with a specific, named and statically typed children +* `NToken` - A token produced by the lexer and used in a syntactic tree +* `Node` - A node of a syntactic tree +* `Nodes` - A hogeneous sequence of node, used to represent unbounded lists (and + modifier) +* `Parser` - A abstract parser engine generated by nitcc +* `Position` - A position into a input stream +* `TestParser` - All-in-one abstract class to test generated parsers on a given +* `TreePrinterVisitor` - Print a node (using to_s) on a line and recustively each children indented (with two spaces) +* `Visitor` - A abstract visitor on syntactic trees generated by nitcc + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/nitcorn/README.docdown.md b/lib/nitcorn/README.docdown.md new file mode 100644 index 0000000000..f056d493a4 --- /dev/null +++ b/lib/nitcorn/README.docdown.md @@ -0,0 +1,42 @@ +# `nitcorn` - [[ini-desc: nitcorn]] + +[[toc: nitcorn]] + +[[doc: nitcorn::nitcorn]] + +## Features + +### `restful` - Support module for the `nitrestful` tool and the `restful` annotation + +[[doc: nitcorn::restful | no-synopsis]] + +Example from `nitcorn::restful_annot`: + +[[code: nitcorn::restful_annot]] + +### `server_config` - Classes and services to configure the server + +[[doc: nitcorn::server_config | no-synopsis]] + +### `sessions` - Automated session management + +[[doc: nitcorn::sessions | no-synopsis]] + +### `vararg_routes` - Routes with parameters. + +[[doc: nitcorn::vararg_routes | no-synopsis]] + +Example from `nitcorn::htcpcp_server`: + +[[code: nitcorn::htcpcp_server]] + +## Other features + +[[features: nitcorn | mentities: nitcorn::file_server;nitcorn::http_errors;nitcorn::http_request;nitcorn::http_request_buffer;nitcorn::http_response;nitcorn::log;nitcorn::media_types;nitcorn::proxy;nitcorn::pthreads;nitcorn::reactor;nitcorn::signal_handler;nitcorn::token]] + +## Authors + +This project is maintained by [[ini-maintainer: nitcorn]]. + +Thanks to the contribution of: +[[ini-contributors: nitcorn]] diff --git a/lib/nitcorn/README.md b/lib/nitcorn/README.md new file mode 100644 index 0000000000..e2cf7f4217 --- /dev/null +++ b/lib/nitcorn/README.md @@ -0,0 +1,457 @@ +# `nitcorn` - Lightweight framework for Web applications development + +* [Features](#Features) +* [`restful` - Support module for the `nitrestful` tool and the `restful` annotation](#`restful`---Support-module-for-the-`nitrestful`-tool-and-the-`restful`-annotation) +* [`server_config` - Classes and services to configure the server](#`server_config`---Classes-and-services-to-configure-the-server) +* [`sessions` - Automated session management](#`sessions`---Automated-session-management) +* [`vararg_routes` - Routes with parameters.](#`vararg_routes`---Routes-with-parameters.) +* [Other features](#Other-features) +* [Authors](#Authors) + +The main classes are: + +* `Action` to answer to requests. +* `Route` to represent a path to an action. +* `VirtualHost` to listen on a specific interface and behave accordingly +* `HttpFactory` which is the base dispatcher class. + +Basic usage example: + +~~~~ +class MyAction + super Action + + redef fun answer(http_request, turi) + do + var response = new HttpResponse(200) + response.body = """ + + + + Hello World + + +

Hello World

+ +""" + return response + end +end + +# Listen to port 8080 on all interfaces +var vh = new VirtualHost("0.0.0.0:8080") + +# Serve index.html with our custom handler +vh.routes.add new Route("/index.html", new MyAction) + +# Serve everything else with a standard `FileServer` +vh.routes.add new Route(null, new FileServer("/var/www/")) + +var factory = new HttpFactory.and_libevent +factory.config.virtual_hosts.add vh +factory.run +~~~~ + +## Features + +### `restful` - Support module for the `nitrestful` tool and the `restful` annotation + +The `restful` annotation is applied on a method to assign it to an HTTP resource. +The `restful` method must be a property of a subclass of `RestfulAction` and +return an `HTTPResponse`. +Once an instance of the class is assigned to a route, the method +can be invoked as a resource under that route. +The returned `HTTPResponse` will be sent back to the client. + +The arguments of the method must be deserializable. +So use simple data types like `String`, `Int`, `Float`, etc. +or any other `Serializable` class. +The method is invoked only if all the arguments are correctly passed +in the JSON format by the HTTP client. +There is one exception, `String` arguments are returned as is, +they don't need the surrounding `""`. +If an argument is missing or there a format error, the `answer` method responds to the request. +Arguments that are `nullable` are optional, +if they are missing `null` is passed to the `restful` method. + +The annotation accepts three kinds of arguments, in any order: + +* String literals rename or add an alias for the HTTP resource. + By default, the name of the HTTP resource is the name of the `restful` method. + The first string literal replaces the default name, + while additional string literals add aliases. + +* Ids such as `GET`, `POST`, `PUT` and `DELETE` restrict which HTTP methods + are accepted. By default, all HTTP methods are accepted. + +* The `async` keyword triggers executing calls to this service asynchronously + by the `thread_pool` attribute of the `RestfulAction`. + By default, each call are executed on the same thread in a FIFO order. + +See the example at `lib/nitcorn/examples/restful_annot.nit` or +a real world use case at `contrib/benitlux/src/server/benitlux_controller.nit`. + +The `restful` annotation is implemented by then `nitrestful` tool. +To compile a module (`my_module.nit`) that uses the `restful` annotation: + +* Run `nitrestful my_module.nit` to produce `my_module_rest.nit` +* Link `my_module_rest.nit` at compilation: `nitc my_module.nit -m my_module_rest.nit`. + +Example from `nitcorn::restful_annot`: + +~~~ +# Example for the `restful` annotation documented at `lib/nitcorn/restful.nit` +module restful_annot is example + +import nitcorn::restful +import nitcorn::pthreads + +# An action root to its `restful` methods +class MyAction + super RestfulAction + + # Method answering requests such as `foo?s=some_string&i=42&b=true` + # + # By default, the name of the HTTP resource is the name of the method. + # Responds to all HTTP methods, including GET, POST, PUT and DELETE. + # + # All arguments are deserialized from a JSON format, + # except for strings that are used as is. + fun foo(s: String, i: Int, b: Bool): HttpResponse + is restful do + var resp = new HttpResponse(200) + resp.body = "foo {s} {i} {b}" + return resp + end + + # Method answering requests such as `api_name?s=these_arguments_are_optional` + # + # This method is available as both `api_name` and `alt_name` in HTTP. + # Responds only to the GET and PUT HTTP method. + fun bar(s: nullable String, i: nullable Int, b: nullable Bool): HttpResponse + is restful("api_name", "alt_name", GET, PUT) do + + var resp = new HttpResponse(200) + resp.body = "bar {s or else "null"} {i or else "null"} {b or else "null"}" + return resp + end + + # Asynchronous method answering requests such as `async_service?str=some_string` + # + # This method is executed by the `thread_pool` attribute of this class. + # Be careful when using the `async` argument to follow all the good + # concurrent programming pratices. + fun async_service(str: String): HttpResponse + is restful(async) do + + # "Work" for 2 seconds + 2.0.sleep + + # Answer + var resp = new HttpResponse(200) + resp.body = "async_service {str}" + return resp + end + + # Method with two complex parameters answering requests such as + # `complex_args?array=["a","b"]&data={"str":"asdf","more":{"str":"ASDF"}}` + # + # Collections and other classes can also be used as parameters, + # they will be deserialized from JSON format. + # By default, the JSON objects will be parsed as the type of the parameter. + # In the example above, the argument passed as `data` is deserialized as a `MyData`. + # However, you can use metadata in the JSON object to deserialize it + # as a subclass of `MyData`, as in this request where `data` is a `MyOtherData`: + # + # `complex_args?array=["a","b"]&data={"__class":"MyOtherData","str":"asdf","i":1234}` + # + # See the `json` package documentation for more information on JSON + # deserialization and the metadata values. + fun complex_args(array: Array[String], data: MyData): HttpResponse + is restful do + var resp = new HttpResponse(200) + resp.body = "complex_args {array} {data}" + return resp + end + + # Catch all other request + redef fun answer(request, turi) + do + var resp = new HttpResponse(404) + resp.body = "Fallback answer" + return resp + end +end + +# Simple data structure for `MyAction::complex_args` +class MyData + serialize + + # Some string + var str: String + + # Some more data + var more: nullable MyData + + redef fun to_s do return "" +end + +# Another data structure, subclass to `MyData` +class MyOtherData + super MyData + serialize + + # An integer + var i: Int + + redef fun to_s do return "" +end + +var vh = new VirtualHost("localhost:8080") + +# Set `rest_path` as the root for an instance of `MyAction`, so: +# * `MyClass::foo` is available as `localhost:8080/rest_path/foo?s=s&i=12&b=true`, +# * `MyClass::bar` is available as both `localhost:8080/rest_path/api_name?s=s` +# and `localhost:8080/rest_path/alt_name?...`. +# * `MyClass::async_service` is available as `localhost:8080/rest_path/async_service?str=str` +# * `MyClass::complex_args` is available as +# `localhost:8080/rest_path/complex_args?array=["a","b"]&data={"str":"asdf"}` +vh.routes.add new Route("rest_path", new MyAction) + +var factory = new HttpFactory.and_libevent +factory.config.virtual_hosts.add vh +factory.run +~~~ + +### `server_config` - Classes and services to configure the server + +The classes of interest are `VirtualHost`, `Interface`, `Route` and `Action` + +### `sessions` - Automated session management + +When parsing a request, this module associate a pre-existing session +to the request if there is one. It will also send the required cookie +with the response if a session has been associated to the response object. + +### `vararg_routes` - Routes with parameters. + +Using `vararg_routes`, a `Route` path can contain variable parts +that will be matched against a `HttpRequest` URL. + +Variable parameters of a route path can be specified using the `:` prefix: + +~~~nitish +var iface = "http://localhost:3000" +var vh = new VirtualHost(iface) +vh.routes.add new Route("/blog/articles/:articleId", new BlogArticleAction) +~~~ + +Route arguments can be accessed from the `HttpRequest` within a nitcorn `Action`: + +~~~nitish +class BlogArticleAction + super Action + + redef fun answer(request, url) do + var param = request.param("articleId") + if param == null then + return new HttpResponse(400) + end + + print url # let's say "/blog/articles/12" + print param # 12 + + return new HttpResponse(200) + end +end +~~~ + +## Route matching + +Route can match variables expression. + +~~~ +# We need an Action to try routes. +class DummyAction super Action end +var action = new DummyAction + +var route = new Route("/users/:id", action) +assert not route.match("/users") +assert route.match("/users/1234") +assert route.match("/users/") # empty id +~~~ + +Route without uri parameters still behave like before. + +~~~ +route = new Route("/users", action) +assert route.match("/users") +assert route.match("/users/1234") +assert not route.match("/issues/1234") +~~~ + +## Route priority + +Priority depends on the order the routes were added to the `Routes` dispatcher. + +~~~ +var host = new VirtualHost("") +var routes = new Routes(host) + +routes.add new Route("/:a/:b/:c", action) +routes.add new Route("/users/:id", action) +routes.add new Route("/:foo", action) + +assert routes["/a/b/c"].path == "/:a/:b/:c" +assert routes["/a/b/c/d"].path == "/:a/:b/:c" +assert routes["/users/1234/foo"].path == "/:a/:b/:c" + +assert routes["/users/"].path == "/users/:id" +assert routes["users/"].path == "/users/:id" +assert routes["/users/1234"].path == "/users/:id" + +assert routes["/users"].path == "/:foo" +assert routes["/"].path == "/:foo" +assert routes[""].path == "/:foo" +~~~ + +## Accessing uri parameter and values + +Parameters can be accessed by parsing the uri. + +~~~ +route = new Route("/users/:id", action) +var params = route.parse_params("/users/1234") +assert params.has_key("id") +assert not params.has_key("foo") +assert params["id"] == "1234" +~~~ + +Or from the `HttpRequest`. + +~~~ +route = new Route("/users/:id", action) +var req = new HttpRequest +req.uri_params = route.parse_params("/users/1234") +assert req.params == ["id"] +assert req.param("id") == "1234" +assert req.param("foo") == null +~~~ + +Example from `nitcorn::htcpcp_server`: + +~~~ +# A server that implements HTCPCP. At the moment there are no additions. +module htcpcp_server is example + +import nitcorn + +# Nitcorn Action used to answer requests. +class HTCPCPAction + super Action + + # Brewing status. + var brewing = false + + # Teapot status. + var is_teapot = false + + redef fun answer(http_request, turi) do + var message: String + var method = http_request.method + var response: HttpResponse + + if is_teapot then + response = new HttpResponse(418) + response.body = "I'm a teapot!\n" + response.header["Content-Type"] = "text" + return response + end + + if method == "POST" or method == "BREW" then + if brewing then + message = "Pot Busy" + response = new HttpResponse(400) + else + message = "Brewing a new pot of coffee\n" + brewing = true + response = new HttpResponse(200) + end + else if method == "WHEN" then + if brewing then + message = "Stopped adding milk, your coffee is ready!\n" + brewing = false + response = new HttpResponse(200) + else + message = "There is no coffee brewing!\n" + response = new HttpResponse(405) + end + else if method == "PROPFIND" or method == "GET" then + if brewing then + message = "The pot is busy\n" + else + message = "The pot is ready to brew more coffee\n" + end + response = new HttpResponse(200) + else + message = "Unknown method: {method}" + brewing = false + response = new HttpResponse(405) + end + + response.header["Content-Type"] = "text" + response.body = message + + return response + end +end + +# Nitcorn server. +class HTCPCServer + + # Port to listen to. + var port: Int + + # Start listening. + fun run do + var vh = new VirtualHost("localhost:{port}") + vh.routes.add new Route("/", new HTCPCPAction) + var factory = new HttpFactory.and_libevent + factory.config.virtual_hosts.add vh + print "Nit4Coffee is now running at port: {port}" + factory.run + end +end + +var server = new HTCPCServer(1227) + +server.run +~~~ + +## Other features + +* `file_server` - Provides the `FileServer` action, which is a standard and minimal file server +* `http_errors` - Offers `ErrorTemplate` to display error pages +* `http_request` - Provides the `HttpRequest` class and services to create it +* `http_request_buffer` - Http request parsing for buffered inputs. +* `http_response` - Provides the `HttpResponse` class and `http_status_codes` +* `log` - Services inserting a timestamp in all prints and to log each requests +* `media_types` - Services to identify Internet media types (or MIME types, Content-types) +* `proxy` - Provides the `ProxyAction` action, which redirects requests to another interface +* `pthreads` - Activate the use of pthreads with `nitcorn` +* `reactor` - Core of the `nitcorn` project, provides `HttpFactory` and `Action` +* `signal_handler` - Handle SIGINT and SIGTERM to close the server after all active events +* `token` - Simple `generate_token` service, independent of the rest of the nitcorn framework + +## Authors + +This project is maintained by **Alexis Laferrière **. + +Thanks to the contribution of: + +* **Jean-Philippe Caissy ** +* **Guillaume Auger** +* **Frederic Sevillano** +* **Justin Michaud-Ouellette** +* **Stephan Michaud** +* **Maxime Bélanger** diff --git a/lib/niti_runtime/README.docdown.md b/lib/niti_runtime/README.docdown.md new file mode 100644 index 0000000000..d6ee7e27e4 --- /dev/null +++ b/lib/niti_runtime/README.docdown.md @@ -0,0 +1,7 @@ +# `niti_runtime` - [[ini-desc: niti_runtime]] + +[[doc: niti_runtime::niti_runtime]] + +## Authors + +This project is maintained by [[ini-maintainer: niti_runtime]]. diff --git a/lib/niti_runtime/README.md b/lib/niti_runtime/README.md new file mode 100644 index 0000000000..61105bb48e --- /dev/null +++ b/lib/niti_runtime/README.md @@ -0,0 +1,7 @@ +# `niti_runtime` - Runtime library to loop around the main program for each line in file-name arguments + +Used by the interpreter when `-n` is used + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/nlp/README.docdown.md b/lib/nlp/README.docdown.md new file mode 100644 index 0000000000..e2fa62b771 --- /dev/null +++ b/lib/nlp/README.docdown.md @@ -0,0 +1,17 @@ +# `nlp` - [[ini-desc: nlp]] + +[[toc: nlp]] + +[[doc: nlp::nlp]] + +## Features + +[[uml: nlp | format: svg, mentities: nlp::nlp;nlp::stanford]] + +### `stanford` - Natural Language Processor based on the StanfordNLP core. + +[[doc: nlp::stanford | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: nlp]]. diff --git a/lib/nlp/README.md b/lib/nlp/README.md new file mode 100644 index 0000000000..9bd0e7466e --- /dev/null +++ b/lib/nlp/README.md @@ -0,0 +1,19 @@ +# `nlp` - Nit wrapper for Stanford CoreNLP + +* [Features](#Features) +* [`stanford` - Natural Language Processor based on the StanfordNLP core.](#`stanford`---Natural-Language-Processor-based-on-the-StanfordNLP-core.) +* [Authors](#Authors) + +See http://nlp.stanford.edu/software/corenlp.shtml. + +## Features + +![Diagram for `nlp`](uml-nlp.svg) + +### `stanford` - Natural Language Processor based on the StanfordNLP core. + +See http://nlp.stanford.edu/software/corenlp.shtml. + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/noise/README.docdown.md b/lib/noise/README.docdown.md new file mode 100644 index 0000000000..5e63b429bc --- /dev/null +++ b/lib/noise/README.docdown.md @@ -0,0 +1,29 @@ +# `noise` - [[ini-desc: noise]] + +[[toc: noise]] + +## Features + +### `PerlinNoise` - 2D Perlin noise generator using layered `InterpolatedNoise` + +[[doc: noise::PerlinNoise | no-synopsis]] + +### `InterpolatedNoise` - Simple interpolated noise + +[[doc: noise::InterpolatedNoise | no-synopsis]] + +### `ImprovedNoise` - Direct translation of Ken Perlin's improved noise Java implementation + +[[doc: noise::ImprovedNoise | no-synopsis]] + +Properties: + +[[features: noise::ImprovedNoise | min-visibility: public, no-redef]] + +## Other features + +[[features: noise | mentities: noise::Noise]] + +## Authors + +This project is maintained by [[ini-maintainer: noise]]. diff --git a/lib/noise/README.md b/lib/noise/README.md new file mode 100644 index 0000000000..29a1287199 --- /dev/null +++ b/lib/noise/README.md @@ -0,0 +1,181 @@ +# `noise` - Noise generators `PerlinNoise` and `InterpolatedNoise` + +* [Features](#Features) +* [`PerlinNoise` - 2D Perlin noise generator using layered `InterpolatedNoise`](#`PerlinNoise`---2D-Perlin-noise-generator-using-layered-`InterpolatedNoise`) +* [`InterpolatedNoise` - Simple interpolated noise](#`InterpolatedNoise`---Simple-interpolated-noise) +* [`ImprovedNoise` - Direct translation of Ken Perlin's improved noise Java implementation](#`ImprovedNoise`---Direct-translation-of-Ken-Perlin's-improved-noise-Java-implementation) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +### `PerlinNoise` - 2D Perlin noise generator using layered `InterpolatedNoise` + +Get values at any coordinates with `[]`. +The behavior of this generator can be customized using its attributes `min`, +`max`, `period` and `seed`. + +This noise is more realistic and less smooth than the `InterpolatedNoise`. + +Due to implementation logic, the full amplitude cannot be reached. +In practice, only `amplitude * (1.0 - 1.0 / n_levels)` is covered. + +This implementation uses a custom deterministic pseudo random number +generator to set `InterpolatedNoise::seed` of the `layers`. +It is seeded with the local `seed` and can be further customized by +redefining `pseudo_random`. +This process do not require any state, so this class only holds the +attributes of the generator and does not keep any generated data. + +## Usage example + +~~~ +var map = new PerlinNoise +map.min = 0.0 +map.max = 16.0 +map.period = 20.0 +map.seed = 0 + +var max = 0.0 +var min = 100.0 +for y in 30.times do + for x in 70.times do + # Get a value at x, y + var val = map[x.to_f, y.to_f] + printn val.to_i.to_hex + + max = max.max(val) + min = min.min(val) + end + print "" +end +assert max <= map.max +assert min >= map.min +~~~ + +## Result at seed == 0 + +~~~raw +76666555444322234567789abbcbbaabbaa98777766665665566667888987655444444 +776665554443322234567789abbbbbbbbba98777766666665556666788998654444444 +777766544443322234566789abbbbbbbbaa99877777776665556666788888655444444 +777776444443322244556679abbbccbbbaa99877777776655556666688888655444444 +777766444444332244555678abbbccbbbaa99887787877655556666678888654444444 +8887654344443333444456789abcccbbaa999877888886555555666688777654444455 +8887654344443333444456789abbcdcbaa999887889887655555566677777654444456 +7876654434444444444456778abbcccaaa999888899888655555566677777654444556 +78765544344445544444567789bbccca99999888899988765555566666667654445566 +77765444344455554445567889bbccba99999998999988765555566555666654445667 +7765444334555665445556788abbbba988998999999988765555566545556554456677 +87654444334556655455567899bbbba998888899999887766555566544556555456777 +87655444334566665555567899bbbbba98888899988888776555566544556555556777 +97655544334566665555567899abbbba98888899988888776555655544456555667777 +97655544444566665556667899aaaaba98888999877777776555555444456666667777 +866555444456666666566789999aaaaa98889998877777766556544443456667777777 +976555445556776666666789aa99aaaa98889998876777666555544444456677887777 +9765554556667777776667899999aaaa98889988876676666555443444446678888888 +87655555666777788766678999899aaa99889988776666666554433344446789998888 +876555566777788888766889998899a999889987776666666543333334456899a99899 +766556677877889998877888888889a99998888777666666653222233345799aaa999a +6665556777777899998878988888899999999887777656666543222233446899aa999a +6655456777777899999888988888889999a988887776566666532222233457899a999a +665555677777789999998998888878899aa9888887765666655322222234578899aa9a +665555677777789999a98888888877899aa9888887766666655322222234467899aa9a +65666677667778999aaa988878877789aaa9888887776676654322222344467889aa9a +55566677767788899aaa987777777789aaa9888887776666654322222344567889aaa9 +5566767777788889aaaa987777777789aaaa988887777666555432122344556899aaa9 +5567777777788889aaaa977777777789aaaa99888777766555543212234555689aaaaa +5667877777889989aaa9876677777889aaaa99888777765554443212334555689aaaaa +~~~ + +### `InterpolatedNoise` - Simple interpolated noise + +Generates smoother noise than `PerlinNoise`. + +Each coordinates at a multiple of `period` defines a random vector and +values in between are interpolated from these vectors. + +This implementation uses a custom deterministic pseudo random number +generator seeded with `seed`. +It can be further customized by redefining `gradient_vector`. +This process do not require any state, so this class only holds the +attributes of the generator and does not keep any generated data. + +## Usage example + +~~~ +var map = new InterpolatedNoise +map.min = 0.0 +map.max = 16.0 +map.period = 20.0 +map.seed = 0 + +var max = 0.0 +var min = 100.0 +for y in 30.times do + for x in 70.times do + # Get a value at x, y + var val = map[x.to_f, y.to_f] + printn val.to_i.to_hex + + max = max.max(val) + min = min.min(val) + end + print "" +end +assert max <= map.max +assert min >= map.min +~~~ + +## Result at seed == 0 + +~~~raw +89abcddeeeeeeeddcba9877666555555555666778766555544444555566789abcddeee +789abcddeeeeeeddccba887766655555555566677766555544444555566779abcddeee +689abcddeeeeeeeddcba988776655555555555667666555554455555566778abccdeee +678abccdeeeeeeeedccba988766655555555555666655555555555556666789abcddee +5789abcddeeeeeeeddcba998776655544444555666655555555555556666789abcddee +5689abcddeeeeeeeedccba98776655544444455566555555555555566666789abccdde +4679abccdeeeffeeeddcba98776655444444445565555555555555666666789abbcddd +4678abccdeeeffeeeedcba98876555444444444555555555566666666666689aabccdd +46789abcdeeeeffeeedccb988765544443344445555566666666666666666789abccdd +45789abcddeeeffeeeddcb987765544433334445555666666666666666666789abbccd +45789abcddeeeeeeeeddcb987665444333333445556666666777777777766789aabccc +45789abcddeeeeeeeeddca987655443333333445566666777777777777776789aabbcc +45789abcddeeeeeeeedcca9876544333333333455666777777788877777767899aabbc +46789abcddeeeeeeeddcba9876544333222333455667777888888888877767899aabbb +46789abcdddeeeeedddcba87655433222223334566777888889998888877778899aabb +5678aabcdddeeeedddccb987654332222222334566778889999999998887778899aaab +5689abbcddddeedddccba9865443222222223345677889999aaaa99998877788999aaa +6789abbcddddddddccbba8765432221111223345678899aaaaaaaaaa9988778889999a +6789abccdddddddccbba9865433221111122344577899aabbbbbbbaaa9987788889999 +789abbccddddddccbba9876543211111111234567899aabbbccccbbbaa987788888899 +889abbccdddddccbba9886543211000001123456889abbcccccccccbba988888888888 +899abbcccddddcccbaa9875432211000011223457899abbcccccccccbba98888888888 +899abbccccddccccbba9876533211000001123456789aabccccddcccbbaa9998888888 +899abbccccccccccbbaa9765432111000011223456899abbcccdddcccbba9999988888 +899abbbcccccccccbbaa9865432211000011123456789abbccdddddcccbba999988888 +899aabbcccccccccbbaa9875433211100001122346789abbccddddddcccbaa99988888 +899aabbbcccccccbbbbaa876543211100001122345689aabccdddddddccbaaa9988887 +899aabbbbbbccbbbbbbaa876543221110001112335679aabccddddddddcbbaa9988877 +899aaabbbbbbbbbbbbbaa9765433211111111123356789abccddddddddccbaa9988777 +8999aaaabbbbbbbbbbaaa9765433221111111122356789abccdddeedddccbaa9988777 +~~~ + +### `ImprovedNoise` - Direct translation of Ken Perlin's improved noise Java implementation + +This implementation differs from `PerlinNoise` on two main points. +This noise is calculated for a 3D point, vs 2D in `PerlinNoise`. +`PerlinNoise` is based off a customizable seed, while this noise has a static data source. + +Properties: + +* `ImprovedNoise::noise` - Noise value in [-1..1] at 3D coordinates `x, y, z` + +## Other features + +* `Noise` - 2D noise generator + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/opts/README.docdown.md b/lib/opts/README.docdown.md new file mode 100644 index 0000000000..fb1e04e669 --- /dev/null +++ b/lib/opts/README.docdown.md @@ -0,0 +1,23 @@ +# `opts` - [[ini-desc: opts]] + +[[toc: opts]] + +## Features + +[[uml: opts | format: svg, mentities: opts::Option;opts::OptionText;opts::OptionBool;opts::OptionCount;opts::OptionParameter;opts::OptionString;opts::OptionEnum;opts::OptionInt;opts::OptionFloat;opts::OptionArray;opts::OptionContext]] + +### `OptionEnum` - An option to choose from an enumeration + +[[doc: opts::OptionEnum | no-synopsis]] + +Properties: + +[[features: opts::OptionEnum | min-visibility: public, no-redef]] + +## Other features + +[[features: opts | mentities: opts::Option;opts::OptionText;opts::OptionBool;opts::OptionCount;opts::OptionParameter;opts::OptionString;opts::OptionInt;opts::OptionFloat;opts::OptionArray;opts::OptionContext]] + +## Authors + +This project is maintained by [[ini-maintainer: opts]]. diff --git a/lib/opts/README.md b/lib/opts/README.md new file mode 100644 index 0000000000..4a4be160f1 --- /dev/null +++ b/lib/opts/README.md @@ -0,0 +1,37 @@ +# `opts` - Management of options on the command line + +* [Features](#Features) +* [`OptionEnum` - An option to choose from an enumeration](#`OptionEnum`---An-option-to-choose-from-an-enumeration) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `opts`](uml-opts.svg) + +### `OptionEnum` - An option to choose from an enumeration + +Declare an enumeration option with all its possible values as an array. +Once the arguments are processed, `value` is set as the index of the selected value, if any. + +Properties: + +* `OptionEnum::init` - Init a new OptionEnum from `values` with a `help` message and `names`. +* `OptionEnum::value_name` - Get the value name from `values`. + +## Other features + +* `Option` - Super class of all option's class +* `OptionArray` - An option with an array as parameter +* `OptionBool` - A boolean option, `true` when present, `false` if not +* `OptionContext` - Context where the options process +* `OptionCount` - A count option. Count the number of time this option is present +* `OptionFloat` - An option with a Float as parameter +* `OptionInt` - An option with an Int as parameter +* `OptionParameter` - Option with one parameter (mandatory by default) +* `OptionString` - An option with a `String` as parameter +* `OptionText` - Not really an option. Just add a line of text when displaying the usage + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/ordered_tree/README.docdown.md b/lib/ordered_tree/README.docdown.md new file mode 100644 index 0000000000..009c50f251 --- /dev/null +++ b/lib/ordered_tree/README.docdown.md @@ -0,0 +1,19 @@ +# `ordered_tree` - [[ini-desc: ordered_tree]] + +[[toc: ordered_tree]] + +[[doc: ordered_tree::OrderedTree]] + +## Features + +### `OrderedTree` - Generic structure to manage and display an ordered tree + +[[doc: ordered_tree::OrderedTree | no-synopsis]] + +Properties: + +[[features: ordered_tree::OrderedTree | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: ordered_tree]]. diff --git a/lib/ordered_tree/README.md b/lib/ordered_tree/README.md new file mode 100644 index 0000000000..517e070e32 --- /dev/null +++ b/lib/ordered_tree/README.md @@ -0,0 +1,101 @@ +# `ordered_tree` - Manipulation and presentation of ordered trees + +* [Features](#Features) +* [`OrderedTree` - Generic structure to manage and display an ordered tree](#`OrderedTree`---Generic-structure-to-manage-and-display-an-ordered-tree) +* [Authors](#Authors) + +Ordered tree are tree where the elements of a same parent are in a specific order + +Elements of the trees are added with the `add` method that takes a parent and +a sub-element. +If the parent is `null`, then the element is considered a root. + +~~~~ +var t = new OrderedTree[String] +t.add(null, "root") +t.add("root", "child1") +t.add("root", "child2") +t.add("child1", "grand-child") +assert t.length == 4 +~~~~ + +By default, the elements with a same parent +are visited in the order they are added. + +~~~ +assert t.to_a == ["root", "child1", "grand-child", "child2"] +assert t.write_to_string == """ +root +|--child1 +| `--grand-child +`--child2 +""" +~~~ + +The `sort_with` method can be used reorder elements + +~~~ +t.add("root", "aaa") +assert t.to_a == ["root", "child1", "grand-child", "child2", "aaa"] +t.sort_with(alpha_comparator) +assert t.to_a == ["root", "aaa", "child1", "grand-child", "child2"] +~~~ + +This class can be used as it to work with generic trees but can also be specialized to provide more specific +behavior or display. It is why the internal attributes are mutable. + +## Features + +### `OrderedTree` - Generic structure to manage and display an ordered tree + +Ordered tree are tree where the elements of a same parent are in a specific order + +Elements of the trees are added with the `add` method that takes a parent and +a sub-element. +If the parent is `null`, then the element is considered a root. + +~~~~ +var t = new OrderedTree[String] +t.add(null, "root") +t.add("root", "child1") +t.add("root", "child2") +t.add("child1", "grand-child") +assert t.length == 4 +~~~~ + +By default, the elements with a same parent +are visited in the order they are added. + +~~~ +assert t.to_a == ["root", "child1", "grand-child", "child2"] +assert t.write_to_string == """ +root +|--child1 +| `--grand-child +`--child2 +""" +~~~ + +The `sort_with` method can be used reorder elements + +~~~ +t.add("root", "aaa") +assert t.to_a == ["root", "child1", "grand-child", "child2", "aaa"] +t.sort_with(alpha_comparator) +assert t.to_a == ["root", "aaa", "child1", "grand-child", "child2"] +~~~ + +This class can be used as it to work with generic trees but can also be specialized to provide more specific +behavior or display. It is why the internal attributes are mutable. + +Properties: + +* `OrderedTree::add` - Add a new element `e` in the tree. +* `OrderedTree::add_all` - Append all nodes `es` as children of `p`. +* `OrderedTree::display` - How to display a specific element of the tree +* `OrderedTree::parent` - The parent of the element `e` +* `OrderedTree::sort_with` - Sort roots and other elements using a comparator method + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/parser_base/README.docdown.md b/lib/parser_base/README.docdown.md new file mode 100644 index 0000000000..3d3e23a29c --- /dev/null +++ b/lib/parser_base/README.docdown.md @@ -0,0 +1,9 @@ +# `parser_base` - [[ini-desc: parser_base]] + +## Features + +[[features: parser_base | mentities: parser_base::StringProcessor;parser_base::Location]] + +## Authors + +This project is maintained by [[ini-maintainer: parser_base]]. diff --git a/lib/parser_base/README.md b/lib/parser_base/README.md new file mode 100644 index 0000000000..a2a58f6f38 --- /dev/null +++ b/lib/parser_base/README.md @@ -0,0 +1,10 @@ +# `parser_base` - Simple base for hand-made parsers of all kinds + +## Features + +* `Location` - Information about the location of an entity in a source document +* `StringProcessor` - Basic facilities for common parser operations on String sources + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/perfect_hashing/README.docdown.md b/lib/perfect_hashing/README.docdown.md new file mode 100644 index 0000000000..1a54cf3f8a --- /dev/null +++ b/lib/perfect_hashing/README.docdown.md @@ -0,0 +1,9 @@ +# `perfect_hashing` - [[ini-desc: perfect_hashing]] + +## Features + +[[features: perfect_hashing | mentities: perfect_hashing::Perfecthashing]] + +## Authors + +This project is maintained by [[ini-maintainer: perfect_hashing]]. diff --git a/lib/perfect_hashing/README.md b/lib/perfect_hashing/README.md new file mode 100644 index 0000000000..33c285c638 --- /dev/null +++ b/lib/perfect_hashing/README.md @@ -0,0 +1,9 @@ +# `perfect_hashing` - Perfect hashing and perfect numbering + +## Features + +* `Perfecthashing` - Class for Perfect Hashing operations with perfect numbering + +## Authors + +This project is maintained by **Julien Pagès **. diff --git a/lib/performance_analysis/README.docdown.md b/lib/performance_analysis/README.docdown.md new file mode 100644 index 0000000000..dc9c15234a --- /dev/null +++ b/lib/performance_analysis/README.docdown.md @@ -0,0 +1,11 @@ +# `performance_analysis` - [[ini-desc: performance_analysis]] + +[[doc: performance_analysis::performance_analysis]] + +## Features + +[[features: performance_analysis | mentities: performance_analysis::PerfMap;performance_analysis::PerfEntry]] + +## Authors + +This project is maintained by [[ini-maintainer: performance_analysis]]. diff --git a/lib/performance_analysis/README.md b/lib/performance_analysis/README.md new file mode 100644 index 0000000000..09e50ff908 --- /dev/null +++ b/lib/performance_analysis/README.md @@ -0,0 +1,35 @@ +# `performance_analysis` - Services to gather information on the performance of events by categories + +Provides `PerfMap` to manage all the categories and +`PerfEntry` for per-category statistics. + +~~~ +for i in 100.times do + var clock = new Clock + + # Do some "work" here + nanosleep(0, 1000000) + + # Register the perf + sys.perfs["sleep 1ms"].add clock.lapse + + # Do some other "work" here + nanosleep(0, 5000000) + + # Register the perf + sys.perfs["sleep 5ms"].add clock.lapse +end + +assert sys.perfs["sleep 1ms"].count == 100 +assert sys.perfs["sleep 1ms"].avg.is_approx(0.001, 0.001) +assert sys.perfs["sleep 5ms"].avg.is_approx(0.005, 0.005) +~~~ + +## Features + +* `PerfEntry` - Statistics on wall clock execution time of a category of events by `name` +* `PerfMap` - Collection of statistics on many events + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/pipeline/README.docdown.md b/lib/pipeline/README.docdown.md new file mode 100644 index 0000000000..21527b04c2 --- /dev/null +++ b/lib/pipeline/README.docdown.md @@ -0,0 +1,27 @@ +# `pipeline` - [[ini-desc: pipeline]] + +[[toc: pipeline]] + +[[doc: pipeline::pipeline]] + +## Features + +### `Iterator2` - Concatenates a sequence of iterators. + +[[doc: pipeline::Iterator2 | no-synopsis]] + +### `NullSkipper` - Wraps an iterator to skip nulls. + +[[doc: pipeline::NullSkipper | no-synopsis]] + +### `Function` - Interface that reify a function. + +[[doc: pipeline::Function | no-synopsis]] + +Properties: + +[[features: pipeline::Function | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: pipeline]]. diff --git a/lib/pipeline/README.md b/lib/pipeline/README.md new file mode 100644 index 0000000000..708909fd49 --- /dev/null +++ b/lib/pipeline/README.md @@ -0,0 +1,75 @@ +# `pipeline` - Pipelined filters and operations on iterators + +* [Features](#Features) +* [`Iterator2` - Concatenates a sequence of iterators.](#`Iterator2`---Concatenates-a-sequence-of-iterators.) +* [`NullSkipper` - Wraps an iterator to skip nulls.](#`NullSkipper`---Wraps-an-iterator-to-skip-nulls.) +* [`Function` - Interface that reify a function.](#`Function`---Interface-that-reify-a-function.) +* [Authors](#Authors) + +This module enhances `Iterator` with some methods that enable a pipeline-like programing. +The processing of elements in a pipeline is done trough connected filters that are implemented with reasonable memory constraints. + +## Features + +### `Iterator2` - Concatenates a sequence of iterators. + +Wraps an iterator of sub-iterators and iterates over the elements of the +sub-iterators. + +~~~nit +var i: Iterator[Int] +var empty = new Array[Int] + +i = new Iterator2[Int]([ + [1, 2, 3].iterator, + empty.iterator, + [4, 5].iterator +].iterator) +assert i.to_a == [1, 2, 3, 4, 5] + +i = new Iterator2[Int]([ + empty.iterator, + [42].iterator, + empty.iterator +].iterator) +assert i.to_a == [42] +~~~ + +SEE: `Iterator::+` + +### `NullSkipper` - Wraps an iterator to skip nulls. + +~~~nit +var i: Iterator[Int] + +i = new NullSkipper[Int]([null, 1, null, 2, null: nullable Int].iterator) +assert i.to_a == [1, 2] + +i = new NullSkipper[Int]([1, null, 2, 3: nullable Int].iterator) +assert i.to_a == [1, 2, 3] +~~~ + +### `Function` - Interface that reify a function. + +This interface helps to manipulate function-like objects. + +The main usage it as a transformation; that takes an argument and produce a result. +See `map` for example. + +Another usage is as a predicate, with `Function[E, Bool]`. +See `Iterator::select` for example. + +Function with more than one argument can be reified with some uncurification. +Eg. `Function[ARG1, Function[ARG2, RES]]`. + +NOTE: Nit is not a functionnal language, this class is a very basic way to +simulate the reification of a simple function. + +Properties: + +* `Function::apply` - How an element is mapped to another one. +* `Function::map` - Filter: produce an iterator which each element is transformed. + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/popcorn/README.docdown.md b/lib/popcorn/README.docdown.md new file mode 100644 index 0000000000..139955263c --- /dev/null +++ b/lib/popcorn/README.docdown.md @@ -0,0 +1,21 @@ +# `popcorn` - [[ini-desc: popcorn]] + +[[toc: popcorn]] + +Example from `popcorn::example_angular`: + +[[code: popcorn::example_angular]] + +## Features + +[[features: popcorn | mentities: popcorn::pop_auth;popcorn::pop_config;popcorn::pop_json;popcorn::pop_repos;popcorn::pop_sessions;popcorn::pop_tasks;popcorn::pop_templates;popcorn::pop_tests;popcorn::pop_tracker;popcorn::pop_validation;popcorn::pop_handlers;popcorn::pop_logging;popcorn::pop_routes]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: popcorn]] + +## Authors + +This project is maintained by [[ini-maintainer: popcorn]]. diff --git a/lib/popcorn/README.md b/lib/popcorn/README.md new file mode 100644 index 0000000000..90578fc2f9 --- /dev/null +++ b/lib/popcorn/README.md @@ -0,0 +1,69 @@ +# `popcorn` - Web application framework for Nit + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +Example from `popcorn::example_angular`: + +~~~ +# This is an example of how to use angular.js with popcorn +module example_angular is example + +import popcorn +import popcorn::pop_json + +class CounterAPI + super Handler + + var counter = 0 + + fun json_counter: JsonObject do + var json = new JsonObject + json["label"] = "Visitors" + json["value"] = counter + return json + end + + redef fun get(req, res) do + res.json(json_counter) + end + + redef fun post(req, res) do + counter += 1 + res.json(json_counter) + end +end + +var app = new App +app.use("/counter", new CounterAPI) +app.use("/*", new StaticHandler("www/", "index.html")) +app.listen("localhost", 3000) +~~~ + +## Features + +* `pop_auth` - Authentification handlers. +* `pop_config` - Configuration file and options for Popcorn apps +* `pop_handlers` - Route handlers. +* `pop_json` - Introduce useful services for JSON REST API handlers. +* `pop_logging` +* `pop_repos` - Repositories for data management. +* `pop_routes` - Internal routes representation. +* `pop_sessions` - Session handlers +* `pop_tasks` - Popcorn threaded tasks +* `pop_templates` - Template rendering for popcorn +* `pop_tests` - Popcorn testing services +* `pop_tracker` - * `pop_validation` - Quick and easy validation framework for Json inputs + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/poset/README.docdown.md b/lib/poset/README.docdown.md new file mode 100644 index 0000000000..405a3ce9a6 --- /dev/null +++ b/lib/poset/README.docdown.md @@ -0,0 +1,25 @@ +# `poset` - [[ini-desc: poset]] + +[[toc: poset]] + +## Features + +### `POSet` - Pre-order set graph. + +[[doc: poset::POSet | no-synopsis]] + +Properties: + +[[features: poset::POSet | min-visibility: public, no-redef]] + +### `POSetElement` - View of an object in a poset + +[[doc: poset::POSetElement | no-synopsis]] + +Properties: + +[[features: poset::POSetElement | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: poset]]. diff --git a/lib/poset/README.md b/lib/poset/README.md new file mode 100644 index 0000000000..e8e63bfa40 --- /dev/null +++ b/lib/poset/README.md @@ -0,0 +1,106 @@ +# `poset` - Pre order sets and partial order set (ie hierarchies) + +* [Features](#Features) +* [`POSet` - Pre-order set graph.](#`POSet`---Pre-order-set-graph.) +* [`POSetElement` - View of an object in a poset](#`POSetElement`---View-of-an-object-in-a-poset) +* [Authors](#Authors) + +## Features + +### `POSet` - Pre-order set graph. + +* reflexivity: an element is in relation with itself (ie `self.has(e) implies self.has_edge(e,e)`) +* transitivity: `(self.has_edge(e,f) and self.has_edge(f,g)) implies self.has_edge(e,g)` + +Nodes and edges are added to the POSet. + +~~~ +var pos = new POSet[String] +pos.add_edge("A", "B") # add A->B +pos.add_edge("B", "C") # add B->C +pos.add_node("D") # add unconnected node "D" + +# A -> B -> C D + +assert pos.has_edge("A", "B") == true # direct +~~~ + +Since a poset is transitive, direct and indirect edges are considered by default. +Direct edges (transitive-reduction) can also be considered independently. + +~~~ +assert pos.has_edge("A", "C") == true # indirect +assert pos.has_edge("A", "D") == false # no edge +assert pos.has_edge("B", "A") == false # edges are directed + +assert pos.has_direct_edge("A", "B") == true # direct +assert pos.has_direct_edge("A", "C") == false # indirect +~~~ + +POSet are dynamic. +It means that the transitivity is updated while new nodes and edges are added. +The transitive-reduction (*direct edges*)) is also updated, +so adding new edges can make some direct edge to disappear. + +~~~ +pos.add_edge("A","D") +pos.add_edge("D","B") +pos.add_edge("A","E") +pos.add_edge("E","C") + +# A -> D -> B +# | | +# v v +# E ------> C + +assert pos.has_edge("D", "C") == true # new indirect edge +assert pos.has_edge("A", "B") == true # still an edge +assert pos.has_direct_edge("A", "B") == false # but no-more a direct one +~~~ + +Thanks to the `[]` method, elements can be considered relatively to the poset. +SEE `POSetElement` + +Properties: + +* `POSet::[]` - Return a view of `e` in the poset. +* `POSet::add_chain` - Add an edge between all elements of `es` in order. +* `POSet::add_edge` - Add an edge from `f` to `t`. +* `POSet::add_node` - Add a node (an element) to the posed +* `POSet::has_direct_edge` - Is there a direct edge from `f` to `t`? +* `POSet::has_edge` - Is there an edge (transitive or not) from `f` to `t`? +* `POSet::linearize` - Sort a sorted array of poset elements using linearization order +* `POSet::print_metrics` - Display exhaustive metrics about the poset +* `POSet::select_greatest` - Filter elements to return only the greatest ones +* `POSet::select_smallest` - Filter elements to return only the smallest ones +* `POSet::show_dot` - Display the POSet in a graphical windows. +* `POSet::sub` - Return an induced sub-poset +* `POSet::write_dot` - Write the POSet as a graphviz digraph. + +### `POSetElement` - View of an object in a poset + +For instance, one common usage is to add a specific attribute for each poset a class belong. + +~~~nitish +class Thing + var in_some_relation: POSetElement[Thing] + var in_other_relation: POSetElement[Thing] +end +var t: Thing +# ... +t.in_some_relation.greaters +~~~ + +Properties: + +* `POSetElement::<` - Is `t != element` and is there an edge from `element` to `t`? +* `POSetElement::<=` - Is there an edge from `element` to `t`? +* `POSetElement::depth` - The length of the shortest path to the root of the poset hierarchy +* `POSetElement::direct_greaters` - Return the set of all elements `t` that have a direct edge from `element` to `t`. +* `POSetElement::direct_smallers` - Return the set of all elements `f` that have an edge from `f` to `element`. +* `POSetElement::greaters` - Return the set of all elements `t` that have an edge from `element` to `t`. +* `POSetElement::smallers` - Return the set of all elements `f` that have an edge from `f` to `element`. + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/posix/README.docdown.md b/lib/posix/README.docdown.md new file mode 100644 index 0000000000..1ae6a6208a --- /dev/null +++ b/lib/posix/README.docdown.md @@ -0,0 +1,11 @@ +# `posix` - [[ini-desc: posix]] + +## Features + +[[uml: posix | format: svg, mentities: posix::ext;posix::posix]] + +[[features: posix | mentities: posix::ext]] + +## Authors + +This project is maintained by [[ini-maintainer: posix]]. diff --git a/lib/posix/README.md b/lib/posix/README.md new file mode 100644 index 0000000000..9b0014046b --- /dev/null +++ b/lib/posix/README.md @@ -0,0 +1,11 @@ +# `posix` - Services conforming to POSIX + +## Features + +![Diagram for `posix`](uml-posix.svg) + +* `ext` - Services not defined in POSIX but provided by most implementations + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/postgresql/README.docdown.md b/lib/postgresql/README.docdown.md new file mode 100644 index 0000000000..44bcc810b7 --- /dev/null +++ b/lib/postgresql/README.docdown.md @@ -0,0 +1,19 @@ +# `postgresql` - [[ini-desc: postgresql]] + +[[toc: postgresql]] + +## Features + +[[uml: postgresql | format: svg, mentities: postgresql::native_postgres;postgresql::postgres]] + +### `postgres` - Services to manipulate a Postgres database + +[[doc: postgresql::postgres | no-synopsis]] + +## Other features + +[[features: postgresql | mentities: postgresql::native_postgres]] + +## Authors + +This project is maintained by [[ini-maintainer: postgresql]]. diff --git a/lib/postgresql/README.md b/lib/postgresql/README.md new file mode 100644 index 0000000000..aa3c0ca428 --- /dev/null +++ b/lib/postgresql/README.md @@ -0,0 +1,57 @@ +# `postgresql` - PostgreSQL connector for Nit + +* [Features](#Features) +* [`postgres` - Services to manipulate a Postgres database](#`postgres`---Services-to-manipulate-a-Postgres-database) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `postgresql`](uml-postgresql.svg) + +### `postgres` - Services to manipulate a Postgres database + +For more information, refer to the documentation of http://www.postgresql.org/docs/manuals/ + +### Usage example + +~~~ +class Animal + var name: String + var kind: String + var age: Int +end + +var animals = new Array[Animal] +var dog = new Animal("Lassy", "dog", 10) +var cat = new Animal("Garfield", "cat", 3) +var turtle = new Animal("George", "turtle", 123) + +animals.add(dog) +animals.add(cat) +animals.add(turtle) + +var db_suffix = "NIT_TESTING_ID".environ +var db = new Postgres.open("dbname=postgres") + +assert db_is_open: not db.is_closed +assert create_table: db.create_table("IF NOT EXISTS animals_{db_suffix} (aname TEXT PRIMARY KEY, kind TEXT NOT NULL, age INT NOT NULL)") else print db.error + +for animal in animals do + assert insert: db.insert("INTO animals_{db_suffix} VALUES('{animal.name}', '{animal.kind}', {animal.age})") else print db.error +end + +var result = db.raw_execute("SELECT * FROM animals_{db_suffix}") +assert result.is_ok +assert drop_table: db.execute("DROP TABLE animals_{db_suffix}") +db.finish +assert db_is_closed: db.is_closed +~~~ + +## Other features + +* `native_postgres` - A native wrapper ove the postgres c api + +## Authors + +This project is maintained by **Guilherme Mansur **. diff --git a/lib/privileges/README.docdown.md b/lib/privileges/README.docdown.md new file mode 100644 index 0000000000..ca4914a7cd --- /dev/null +++ b/lib/privileges/README.docdown.md @@ -0,0 +1,15 @@ +# `privileges` - [[ini-desc: privileges]] + +[[doc: privileges::privileges]] + +Example from `privileges::drop_privileges`: + +[[code: privileges::drop_privileges]] + +## Features + +[[features: privileges | mentities: privileges::UserGroup;privileges::OptionUserAndGroup]] + +## Authors + +This project is maintained by [[ini-maintainer: privileges]]. diff --git a/lib/privileges/README.md b/lib/privileges/README.md new file mode 100644 index 0000000000..ffb1539831 --- /dev/null +++ b/lib/privileges/README.md @@ -0,0 +1,48 @@ +# `privileges` - Process privileges management utilities + +Used mainly by daemons and such to aquire resources as su and +then drop back to a restricted user. + +Example from `privileges::drop_privileges`: + +~~~ +# Example using the privileges module to drop privileges from root +module drop_privileges is example + +import privileges + +# basic command line options +var opts = new OptionContext +var opt_ug = new OptionUserAndGroup.for_dropping_privileges +opt_ug.mandatory = true +opts.add_option(opt_ug) + +# parse and check command line options +opts.parse(args) +if not opts.errors.is_empty then + print opts.errors.join("\n") + print "Usage: drop_privileges [options]" + opts.usage + exit 1 +end + +# original user +print "before {sys.uid}:{sys.gid}" + +# make the switch +var user_group = opt_ug.value +assert user_group != null +user_group.drop_privileges + +# final user +print "after {sys.uid}:{sys.egid}" +~~~ + +## Features + +* `OptionUserAndGroup` - Option to ask for a username and group +* `UserGroup` - Class to manage user groups + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/progression/README.docdown.md b/lib/progression/README.docdown.md new file mode 100644 index 0000000000..80fa223afd --- /dev/null +++ b/lib/progression/README.docdown.md @@ -0,0 +1,9 @@ +# `progression` - [[ini-desc: progression]] + +## Features + +[[features: progression | mentities: progression::Trackable;progression::ProgressionListener]] + +## Authors + +This project is maintained by [[ini-maintainer: progression]]. diff --git a/lib/progression/README.md b/lib/progression/README.md new file mode 100644 index 0000000000..6c73e83343 --- /dev/null +++ b/lib/progression/README.md @@ -0,0 +1,10 @@ +# `progression` - Event-based interface to track the progression of an operation + +## Features + +* `ProgressionListener` - Listens to the progression of a possibly long-running operation. +* `Trackable` - An operation that is trackable using a `ProgressionListener`. + +## Authors + +This project is maintained by **Jean-Christophe Beaupré **. diff --git a/lib/prompt/README.docdown.md b/lib/prompt/README.docdown.md new file mode 100644 index 0000000000..66840046b1 --- /dev/null +++ b/lib/prompt/README.docdown.md @@ -0,0 +1,17 @@ +# `prompt` - [[ini-desc: prompt]] + +[[toc: prompt]] + +## Features + +### `Sys::prompt` - Display `prompt` in the console and wait for a response + +[[doc: prompt::prompt::Sys::prompt | no-synopsis]] + +### `Sys::prompt_add_history` - Add `line` to the shell history + +[[doc: prompt::prompt::Sys::prompt_add_history | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: prompt]]. diff --git a/lib/prompt/README.md b/lib/prompt/README.md new file mode 100644 index 0000000000..e71710bbe8 --- /dev/null +++ b/lib/prompt/README.md @@ -0,0 +1,22 @@ +# `prompt` - Basic services to display a prompt + +* [Features](#Features) +* [`Sys::prompt` - Display `prompt` in the console and wait for a response](#`Sys::prompt`---Display-`prompt`-in-the-console-and-wait-for-a-response) +* [`Sys::prompt_add_history` - Add `line` to the shell history](#`Sys::prompt_add_history`---Add-`line`-to-the-shell-history) +* [Authors](#Authors) + +## Features + +### `Sys::prompt` - Display `prompt` in the console and wait for a response + +Return the user response, or `null` if EOF. + +If `add_history`, the user response is added to the history. + +### `Sys::prompt_add_history` - Add `line` to the shell history + +The default implementation is a noop, but other packages can refine it. + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/pthreads/README.docdown.md b/lib/pthreads/README.docdown.md new file mode 100644 index 0000000000..237deb4d5a --- /dev/null +++ b/lib/pthreads/README.docdown.md @@ -0,0 +1,31 @@ +# `pthreads` - [[ini-desc: pthreads]] + +[[toc: pthreads]] + +Example from `pthreads::jointask_example`: + +[[code: pthreads::jointask_example]] + +## Features + +[[uml: pthreads | format: svg, mentities: pthreads::concurrent_collections;pthreads::extra;pthreads::pthreads;pthreads::redef_collections;pthreads::threadpool]] + +### `concurrent_collections` - Introduces thread-safe concurrent collections + +[[doc: pthreads::concurrent_collections | no-synopsis]] + +Example from `pthreads::concurrent_array_and_barrier`: + +[[code: pthreads::concurrent_array_and_barrier]] + +### `redef_collections` - Redef _some_ basic collections to be thread-safe + +[[doc: pthreads::redef_collections | no-synopsis]] + +## Other features + +[[features: pthreads | mentities: pthreads::extra;pthreads::threadpool]] + +## Authors + +This project is maintained by [[ini-maintainer: pthreads]]. diff --git a/lib/pthreads/README.md b/lib/pthreads/README.md new file mode 100644 index 0000000000..9377efb08c --- /dev/null +++ b/lib/pthreads/README.md @@ -0,0 +1,160 @@ +# `pthreads` - POSIX Threads support + +* [Features](#Features) +* [`concurrent_collections` - Introduces thread-safe concurrent collections](#`concurrent_collections`---Introduces-thread-safe-concurrent-collections) +* [`redef_collections` - Redef _some_ basic collections to be thread-safe](#`redef_collections`---Redef-_some_-basic-collections-to-be-thread-safe) +* [Other features](#Other-features) +* [Authors](#Authors) + +Example from `pthreads::jointask_example`: + +~~~ +# Simple example of joinable task using threadpool +module jointask_example is example + +import threadpool + +# Task computing a string +class StringTask + super JoinTask + + # Sleeping time + var sec: Int + + # result of `self` execution + var value: String + + # ID for printing + var id: Int + + redef fun main do + nanosleep(sec, 0) + value += " id: {id}" + end +end + +var tp = new ThreadPool +var t0 = new StringTask(10, "First, long task", 0) +var tasks = new Array[StringTask] +for i in 5.times do + tasks.add(new StringTask(1, "Small task", i + 1)) +end +tp.execute(t0) +for t in tasks do tp.execute(t) +for t in tasks do + t.join + print t.value +end +t0.join +print t0.value +~~~ + +## Features + +![Diagram for `pthreads`](uml-pthreads.svg) + +### `concurrent_collections` - Introduces thread-safe concurrent collections + +This module offers new thread-safe collections. If you want to +render basic collections thread-safe and don't mind the overhead cost, +you can use `threads::redef_collections`. + +Concurrent collections: + +- [x] `ConcurrentArray` +- [x] `ConcurrentList` +- [ ] `ConcurrentHashMap` +- [ ] `ConcurrentHashSet` +- [ ] `ConcurrentRef` +- [ ] `ConcurrentQueue` + +Introduced collections specialize their critical methods according to the +current implementation in the standard library. If additional services +are added to the underlying collections by refinement or evolution, they +might need to be covered in the concurrent version. + +Example from `pthreads::concurrent_array_and_barrier`: + +~~~ +# A basic usage example of the modules `pthreads` and `pthreads::cocurrent_collections` +# +# 20 threads share an array and a barrier. They each insert 1000 strings into +# the array and wait at a barrier before finishing. +module concurrent_array_and_barrier is example + +import pthreads::concurrent_collections + +private class MyThread + super Thread + + # This `ConcurrentArray` has its own `Mutex` + var array: ConcurrentArray[String] + + # Use an explicit `Barrier` + var barrier: Barrier + + var id: Int + + redef fun main + do + # Print and add to Array 1000 times + for i in 1000.times do + var str = "thread {id}: {i}" + array.add str + end + + # Wait at the `barrier` + barrier.wait + + return id + end +end + +var n_threads = 20 + +# This `ConcurrentArray` has its own `Mutex` +var array = new ConcurrentArray[String] + +# Use an explicit `Barrier` +var barrier = new Barrier(n_threads) + +# Create all our threads +var threads = new Array[Thread] +for t in n_threads.times do + var thread = new MyThread(array, barrier, t) + threads.add thread + thread.start +end + +# Wait for the threads to complete +for thread in threads do + print "Thread {thread.join or else "null"} is done" +end + +print "{array.length} strings inserted" +~~~ + +### `redef_collections` - Redef _some_ basic collections to be thread-safe + +This modules is intended to be used with scripts or quick prototypes. +It makes thread safe _all_ instances of _some_ collections which +also slightly slow down single threaded use. For more robust software, +it is recommended to use `threads::concurrent_collections`. + +Thread-safe collections: + +- [x] `Array` +- [ ] `List` +- [ ] `HashMap` +- [ ] `HashSet` +- [ ] `Ref` +- [ ] `Queue` + +## Other features + +* `extra` - Offers some POSIX threads services that are not available on all platforms +* `threadpool` - Introduces a minimal ThreadPool implementation using Tasks + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/readline/README.docdown.md b/lib/readline/README.docdown.md new file mode 100644 index 0000000000..959ac14a1f --- /dev/null +++ b/lib/readline/README.docdown.md @@ -0,0 +1,9 @@ +# `readline` - [[ini-desc: readline]] + +## Features + +[[features: readline | mentities: readline::readline::Sys::readline;readline::readline::Sys::add_history]] + +## Authors + +This project is maintained by [[ini-maintainer: readline]]. diff --git a/lib/readline/README.md b/lib/readline/README.md new file mode 100644 index 0000000000..0cdeb861cf --- /dev/null +++ b/lib/readline/README.md @@ -0,0 +1,10 @@ +# `readline` - GNU readline library wrapper + +## Features + +* `Sys::add_history` - Adds the data String to the history no matter what it contains +* `Sys::readline` - Use the GNU Library readline function + +## Authors + +This project is maintained by **Frédéric Vachon **. diff --git a/lib/realtime/README.docdown.md b/lib/realtime/README.docdown.md new file mode 100644 index 0000000000..28c6f53f17 --- /dev/null +++ b/lib/realtime/README.docdown.md @@ -0,0 +1,19 @@ +# `realtime` - [[ini-desc: realtime]] + +[[toc: realtime]] + +[[doc: realtime::Clock]] + +## Features + +### `Clock` - Keeps track of real time + +[[doc: realtime::Clock | no-synopsis]] + +Properties: + +[[features: realtime::Clock | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: realtime]]. diff --git a/lib/realtime/README.md b/lib/realtime/README.md new file mode 100644 index 0000000000..5f3754a270 --- /dev/null +++ b/lib/realtime/README.md @@ -0,0 +1,47 @@ +# `realtime` - Services to keep time of the wall clock time + +* [Features](#Features) +* [`Clock` - Keeps track of real time](#`Clock`---Keeps-track-of-real-time) +* [Authors](#Authors) + +~~~ +var clock = new Clock + +# sleeping at least 1s +1.0.sleep +assert clock.total >= 1.0 +assert clock.lapse >= 1.0 + +# sleeping at least 5ms +0.005.sleep +assert clock.total >= 1.005 +assert clock.lapse >= 0.005 +~~~ + +## Features + +### `Clock` - Keeps track of real time + +~~~ +var clock = new Clock + +# sleeping at least 1s +1.0.sleep +assert clock.total >= 1.0 +assert clock.lapse >= 1.0 + +# sleeping at least 5ms +0.005.sleep +assert clock.total >= 1.005 +assert clock.lapse >= 0.005 +~~~ + +Properties: + +* `Clock::lapse` - Seconds since the last call to `lapse` +* `Clock::peek_lapse` - Seconds since the last call to `lapse`, without resetting the lapse counter +* `Clock::total` - Seconds since the creation of this instance + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/ropes_debug/README.docdown.md b/lib/ropes_debug/README.docdown.md new file mode 100644 index 0000000000..b2d3dbb6e5 --- /dev/null +++ b/lib/ropes_debug/README.docdown.md @@ -0,0 +1,9 @@ +# `ropes_debug` - [[ini-desc: ropes_debug]] + +## Features + +[[features: ropes_debug | mentities: ropes_debug::ropes_debug::Text::to_dot]] + +## Authors + +This project is maintained by [[ini-maintainer: ropes_debug]]. diff --git a/lib/ropes_debug/README.md b/lib/ropes_debug/README.md new file mode 100644 index 0000000000..80a311fe77 --- /dev/null +++ b/lib/ropes_debug/README.md @@ -0,0 +1,9 @@ +# `ropes_debug` - Exposes methods for debugging ropes when needed + +## Features + +* `Text::to_dot` - Returns the graphviz-formatted content of `self` + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/rubix/README.docdown.md b/lib/rubix/README.docdown.md new file mode 100644 index 0000000000..27bec4ba84 --- /dev/null +++ b/lib/rubix/README.docdown.md @@ -0,0 +1,19 @@ +# `rubix` - [[ini-desc: rubix]] + +[[toc: rubix]] + +[[doc: rubix::rubix]] + +## Features + +### `RubixCube` - In-memory representation of a Rubix Cube + +[[doc: rubix::RubixCube | no-synopsis]] + +Properties: + +[[features: rubix::RubixCube | min-visibility: public, no-redef]] + +## Authors + +This project is maintained by [[ini-maintainer: rubix]]. diff --git a/lib/rubix/README.md b/lib/rubix/README.md new file mode 100644 index 0000000000..d5b851a096 --- /dev/null +++ b/lib/rubix/README.md @@ -0,0 +1,87 @@ +# `rubix` - Rubix-cube modelization library + +* [Features](#Features) +* [`RubixCube` - In-memory representation of a Rubix Cube](#`RubixCube`---In-memory-representation-of-a-Rubix-Cube) +* [Authors](#Authors) + +As for now the library supports basic representation of a Rubix-cube +The library is built for speed, most operations cost no allocations to perform. +This does however mean that the library is NOT thread-safe and should be handled +with the appropriate mutual-exclusion mechanisms to avoid memory corruption +or unintended side-effects on a single cube. + +The library supports the singmaster notation as a way to perform operations +on a Rubix cube. + +No solver is (yet) provided along with the library. + +## Features + +### `RubixCube` - In-memory representation of a Rubix Cube + +Faces are represented in memory as if they were a flattened cube like: + +~~~raw + B B B + B B B + B B B + U U U + U U U + U U U +L L L F F F R R R +L L L F F F R R R +L L L F F F R R R + D D D + D D D + D D D +~~~ + +All the commands detailed in the class respect the Singmaster notation + +Properties: + +* `RubixCube::cclock_B` - B' command +* `RubixCube::cclock_D` - D' command +* `RubixCube::cclock_E` - E' command +* `RubixCube::cclock_F` - F' command +* `RubixCube::cclock_L` - L' command +* `RubixCube::cclock_M` - M' command +* `RubixCube::cclock_R` - R' command +* `RubixCube::cclock_S` - S' command +* `RubixCube::cclock_U` - U' command +* `RubixCube::cclock_b` - b' command +* `RubixCube::cclock_d` - d' command +* `RubixCube::cclock_f` - f' command +* `RubixCube::cclock_l` - l' command +* `RubixCube::cclock_r` - r' command +* `RubixCube::cclock_u` - u' command +* `RubixCube::ccube_X_rotation` - X' command +* `RubixCube::ccube_Y_rotation` - Y' command +* `RubixCube::ccube_Z_rotation` - Z' command +* `RubixCube::clock_B` - B command +* `RubixCube::clock_D` - D command +* `RubixCube::clock_E` - E command +* `RubixCube::clock_F` - F command +* `RubixCube::clock_L` - L command +* `RubixCube::clock_M` - M command +* `RubixCube::clock_R` - R command +* `RubixCube::clock_S` - S command +* `RubixCube::clock_U` - U command +* `RubixCube::clock_b` - b command +* `RubixCube::clock_d` - d command +* `RubixCube::clock_f` - f command +* `RubixCube::clock_l` - l command +* `RubixCube::clock_r` - r command +* `RubixCube::clock_u` - u command +* `RubixCube::cube_X_rotation` - X command +* `RubixCube::cube_Y_rotation` - Y command +* `RubixCube::cube_Z_rotation` - Z command +* `RubixCube::do_cmd` - Applies a command `cmd` to `self`, returns the number of operations performed during the command +* `RubixCube::is_solved` - Is `self` a solved Rubix Cube ? +* `RubixCube::reset` - Reset the Rubix Cube to a solved position +* `RubixCube::scrambled` - Build a new Rubix Cube with a scrambled layout +* `RubixCube::solved` - Build a new Rubix Cube with a solved layout + +## Authors + +This project is maintained by **Lucas Bajolet**. diff --git a/lib/sax/README.docdown.md b/lib/sax/README.docdown.md new file mode 100644 index 0000000000..1bf4d94a21 --- /dev/null +++ b/lib/sax/README.docdown.md @@ -0,0 +1,21 @@ +# `sax` - [[ini-desc: sax]] + +[[toc: sax]] + +[[doc: sax::sax]] + +## Features + +[[uml: sax | format: svg, mentities: sax>;sax>ext>;sax>helpers>]] + +[[features: sax | mentities: sax::attributes;sax::content_handler;sax::dtd_handler;sax::entity_resolver;sax::error_handler;sax::input_source;sax::sax_locator;sax::sax_parse_exception;sax::xml_filter;sax::xml_reader]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: sax]] + +## Authors + +This project is maintained by [[ini-maintainer: sax]]. diff --git a/lib/sax/README.md b/lib/sax/README.md new file mode 100644 index 0000000000..0ee0669ced --- /dev/null +++ b/lib/sax/README.md @@ -0,0 +1,229 @@ +# `sax` - Core SAX APIs + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +This is a (partial) port of the original SAX API. See +[http://www.saxproject.org](http://www.saxproject.org) for more information +about SAX. + +SAX2 Standard Feature Flags: + +One of the essential characteristics of SAX2 is that it added +feature flags which can be used to examine and perhaps modify +parser modes, in particular modes such as validation. +Since features are identified by (absolute) URIs, anyone +can define such features. + +For default values not specified by SAX2, +each `XMLReader` implementation specifies its default, +or may choose not to expose the feature flag. +Unless otherwise specified here, +implementations may support changing current values +of these standard feature flags, but not while parsing. + +Currently defined standard feature URIs have the prefix +`http://xml.org/sax/features/` before an identifier such as +`validation`. Support for the default values of the +`namespaces` and `namespace-prefixes` +properties is required. Turn features on or off using +`feature=`. Those standard identifiers are: + +`external-general-entities`: + +* Access: read/write +* Default: unspecified +* Description: Reports whether this parser processes external general + entities; always `true` if validating. + +`external-parameter-entities`: + +* Access: read/write +* Default: unspecified +* Description: Reports whether this parser processes external parameter + entities; always `true` if validating. + +`is-standalone`: + +* Access: read-only while parsing, none while not parsing +* Default: not applicable +* Description: May be examined only during a parse, after the `start_document` + callback has been completed; read-only. The value is `true` if the document + specified `standalone="yes"` in its XML declaration, and otherwise is `false`. + +`lexical-handler/parameter-entities`: + +* Access: read/write +* Default: unspecified +* Description: `true` indicates that the LexicalHandler will report the + beginning and end of parameter entities. + +`namespaces`: + +* Access: read/write +* Default: `true` +* Description: `true` indicates namespace URIs and unprefixed local names + for element and attribute names will be available. + +`namespace-prefixes`: + +* Access: read/write +* Default: `false` +* Description: `true` indicates XML 1.0 names (with prefixes) and attributes + (including `xmlns*` attributes) will be available. + +`resolve-dtd-uris`: + +* Access: read/write +* Default: `true` +* Description: `true` indicates that system IDs in declarations will be + absolutized (relative to their base URIs) before reporting. (That is the + default behavior for all SAX2 XML parsers.) A value of "false" indicates those + IDs will not be absolutized; parsers will provide the base URI from + `SAXLocator.system_id`. This applies to system IDs passed in + `DTDHandler.notation_decl`, DTDHandler.unparsed_entity_decl`, and`DeclHandler.external_entity_decl`. It does not apply to`EntityResolver.resolve_entity`, which is not used to report declarations, or to`LexicalHandler.start_dtd`, which already provides the non-absolutized URI. + +`string-interning`: + +* Access: read-only +* Default: `false` +* Description: (Java-specific. Not supported in Nit.) + +`unicode-normalization-checking`: + +* Access: read/write +* Default: `false` +* Description: Controls whether the parser reports Unicode normalization + errors as described in section 2.13 and Appendix B of the XML 1.1 + Recommendation. If `true`, Unicode normalization errors are reported using + the `ErrorHandler.error` callback. Such errors are not fatal in themselves + (though, obviously, other Unicode-related encoding errors may be). + +`use-attributes2`: + +* Access: read-only +* Default: not applicable +* Description: Returns `true` if the `Attributes` objects passed by this + parser in `ContentHandler.start_element` implement the + `sax::ext::Attributes2` interface. That interface exposes additional + DTD-related information, such as whether the attribute was specified in the + source text rather than defaulted. + +TODO: interface not yet available in Nit. + +`use-locator2`: + +* Access: read-only +* Default: not applicable +* Description: Returns `true` if the `SAXLocator` objects passed by this + parser in `ContentHandler.document_locator=` implement the + `sax::ext::SAXLocator2` interface. That interface exposes additional + entity information, such as the character encoding and XML version used. + +TODO: interface not yet available in Nit. + +`use-entity-resolver2`: + +* Access: read/write +* Default: true +* Description: Returns `true` if, when `entity_resolver` is given an object + implementing the `sax::ext::EntityResolver2` interface, those new methods + will be used. Returns `false` to indicate that those methods will not be used. + +`validation`: + +* Access: read/write +* Default: unspecified +* Description: controls whether the parser is reporting all validity errors; + if true, all external entities will be read. + +`xmlns-uris`: + +* Access: read/write +* Default: `false` +* Description: Controls whether, when the `namespace-prefixes` feature is set, + the parser treats namespace declaration attributes as being in the + `http://www.w3.org/2000/xmlns/` namespace. By default, SAX2 conforms to the + original "Namespaces in XML" Recommendation, which explicitly states that such + attributes are not in any namespace. Setting this optional flag to `true` + makes the SAX2 events conform to a later backwards-incompatible revision of + that recommendation, placing those attributes in a namespace. + +`xml-1.1`: + +* Access: read-only +* Default: not applicable +* Description: Returns `true` if the parser supports both XML 1.1 and XML 1.0. + Returns "false" if the parser supports only XML 1.0. + +SAX2 Standard Handler and Property IDs: + +For parser interface characteristics that are described as objects, a +separate namespace is defined. The objects in this namespace are again +identified by URI, and the standard property URIs have the prefix +`http://xml.org/sax/properties/` before an identifier such as +`lexical-handler` or `dom-node`. All of these standard properties are +optional; `XMLReader` implementations need not support them. Manage those +properties using `property=`. Those identifiers are: + +`declaration-handler`: + +Used to see most DTD declarations except those treated as lexical (“document +element name is...”) or which are mandatory for all SAX parsers +(`DTDHandler`). The object must implement `sax::ext::DeclHandler`. + +`document-xml-version`: + +May be examined only during a parse, after the `start_document` callback +has been completed; read-only. This property is a literal string describing +the actual XML version of the document, such as `"1.0"` or `"1.1"`. + +`dom-node`: + +For “DOM Walker” style parsers, which ignore their `parser.parse` parameters, +this is used to specify the DOM (sub)tree being walked by the parser. The +object must implement the `xml.dom.Node` interface. + +TODO: interface not yet available in Nit. + +`lexical-handler`: + +Used to see some syntax events that are essential in some applications: +comments, `CDATA` delimeters, selected general entity inclusions, and the +start and end of the DTD (and declaration of document element name). +The object must implement `sax::ext::LexicalHandler`. + +`xml-string`: + +Readable only during a parser callback, this exposes a **TBS** chunk of +characters responsible for the current event. + +Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org). + +## Features + +![Diagram for `sax`](uml-sax.svg) + +* `attributes` - Interface for a list of XML attributes. +* `content_handler` - Receives notification of the logical content of a document. +* `dtd_handler` - Receives notification of basic DTD-related events. +* `entity_resolver` - Basic interface for resolving entities. +* `error_handler` - Basic interface for SAX error handlers. +* `input_source` - A single input source for an XML entity. +* `sax_locator` - Interface for associating a SAX event with a document location. +* `sax_parse_exception` - Encapsulates an XML parse error or warning. +* `xml_filter` - Interface for an XML filter. +* `xml_reader` - Interface for reading an XML document using callbacks. + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Jean-Christophe Beaupré **. diff --git a/lib/saxophonit/README.docdown.md b/lib/saxophonit/README.docdown.md new file mode 100644 index 0000000000..b8bf85cce4 --- /dev/null +++ b/lib/saxophonit/README.docdown.md @@ -0,0 +1,19 @@ +# `saxophonit` - [[ini-desc: saxophonit]] + +[[toc: saxophonit]] + +## Features + +[[uml: saxophonit | format: svg, mentities: saxophonit::lexer;saxophonit::reader_model;saxophonit::saxophonit;saxophonit::testing]] + +[[features: saxophonit | mentities: saxophonit::lexer;saxophonit::reader_model;saxophonit::testing]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: saxophonit]] + +## Authors + +This project is maintained by [[ini-maintainer: saxophonit]]. diff --git a/lib/saxophonit/README.md b/lib/saxophonit/README.md new file mode 100644 index 0000000000..d088935ba6 --- /dev/null +++ b/lib/saxophonit/README.md @@ -0,0 +1,25 @@ +# `saxophonit` - A SAX 2 parser in Nit + +* [Features](#Features) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +## Features + +![Diagram for `saxophonit`](uml-saxophonit.svg) + +* `lexer` - SAXophoNit’s lexer +* `reader_model` - Reader’s model. +* `testing` - Various utilities to help testing SAXophoNit (and SAX parsers in general). + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Jean-Christophe Beaupré **. diff --git a/lib/scene2d/README.docdown.md b/lib/scene2d/README.docdown.md new file mode 100644 index 0000000000..a1f06e7123 --- /dev/null +++ b/lib/scene2d/README.docdown.md @@ -0,0 +1,33 @@ +# `scene2d` - [[ini-desc: scene2d]] + +[[toc: scene2d]] + +[[doc: scene2d::scene2d]] + +## Features + +[[uml: scene2d | format: svg, mentities: scene2d::LiveObject;scene2d::Sprite;scene2d::LiveGroup;scene2d::Scene;scene2d::View]] + +### `Sprite` - The basic atomic living and moving object. + +[[doc: scene2d::Sprite | no-synopsis]] + +Properties: + +[[features: scene2d::Sprite | min-visibility: public, no-redef]] + +### `View` - Abstract view do draw sprites + +[[doc: scene2d::View | no-synopsis]] + +Properties: + +[[features: scene2d::View | min-visibility: public, no-redef]] + +## Other features + +[[features: scene2d | mentities: scene2d::LiveObject;scene2d::LiveGroup;scene2d::Scene]] + +## Authors + +This project is maintained by [[ini-maintainer: scene2d]]. diff --git a/lib/scene2d/README.md b/lib/scene2d/README.md new file mode 100644 index 0000000000..60fac91364 --- /dev/null +++ b/lib/scene2d/README.md @@ -0,0 +1,47 @@ +# `scene2d` - Framework for 2D management of game elements + +* [Features](#Features) +* [`Sprite` - The basic atomic living and moving object.](#`Sprite`---The-basic-atomic-living-and-moving-object.) +* [`View` - Abstract view do draw sprites](#`View`---Abstract-view-do-draw-sprites) +* [Other features](#Other-features) +* [Authors](#Authors) + +TODO: collision framework (with quad tree?) + +## Features + +![Diagram for `scene2d`](uml-scene2d.svg) + +### `Sprite` - The basic atomic living and moving object. + +A sprite has a position and a velocity + +Properties: + +* `Sprite::angle_to` - Return the angle to target an other sprite +* `Sprite::bottom` - Y coordinate of bottom. +* `Sprite::left` - X coordinate of left side. +* `Sprite::overlaps` - Is self overlaps (or contains) an other sprite +* `Sprite::right` - X coordinate of right side. +* `Sprite::set_velocity` - Update of vx and vy toward a given angle and magnitude +* `Sprite::top` - Y coordinate of top. +* `Sprite::velocity_angle` - Return the current angle of velocity + +### `View` - Abstract view do draw sprites + +Concrete views are specific for each back-end. +View can also be used to implements camera and other fun things. + +Properties: + +* `View::draw_sprite` - Draw a specific sprite on the view + +## Other features + +* `LiveGroup` - Organizational class to manage groups of sprites and other live objects. +* `LiveObject` - The root class of the living objects (sprites, group of sprites, etc.) +* `Scene` - A state in the game logic + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/sdl2/README.docdown.md b/lib/sdl2/README.docdown.md new file mode 100644 index 0000000000..f520c90536 --- /dev/null +++ b/lib/sdl2/README.docdown.md @@ -0,0 +1,27 @@ +# `sdl2` - [[ini-desc: sdl2]] + +[[toc: sdl2]] + +## Features + +[[uml: sdl2 | format: svg, mentities: sdl2::all;sdl2::events;sdl2::image;sdl2::mixer;sdl2::sdl2;sdl2::sdl2_base;sdl2::syswm]] + +### `image` - Services of the SDL_image 2.0 library + +[[doc: sdl2::image | no-synopsis]] + +### `mixer` - SDL2 mixer with sample/sounds and music + +[[doc: sdl2::mixer | no-synopsis]] + +Example from `sdl2::minimal`: + +[[code: sdl2::minimal]] + +## Other features + +[[features: sdl2 | mentities: sdl2::all;sdl2::events;sdl2::sdl2_base;sdl2::syswm]] + +## Authors + +This project is maintained by [[ini-maintainer: sdl2]]. diff --git a/lib/sdl2/README.md b/lib/sdl2/README.md new file mode 100644 index 0000000000..1cd0717356 --- /dev/null +++ b/lib/sdl2/README.md @@ -0,0 +1,140 @@ +# `sdl2` - This is a low-level wrapper of the SDL 2.0 library (as `sdl2`) and SDL_image 2.0 (as `sdl2::image`) + +* [Features](#Features) +* [`image` - Services of the SDL_image 2.0 library](#`image`---Services-of-the-SDL_image-2.0-library) +* [`mixer` - SDL2 mixer with sample/sounds and music](#`mixer`---SDL2-mixer-with-sample/sounds-and-music) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `sdl2`](uml-sdl2.svg) + +### `image` - Services of the SDL_image 2.0 library + +Offers `SDLSurface::load` which supports more image formats than `sdl2::sdl2` +alone: JPG, PNG, TIF, GIT, ICO and much more. + +### `mixer` - SDL2 mixer with sample/sounds and music + +C API documentation: https://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer.html + +Example from `sdl2::minimal`: + +~~~ +# An example to test and demonstrate the `sdl2` lib with `image` and `events` +module minimal is example + +import sdl2::all + +# Check for an error, then print and clear it +# +# Some errors are not fatal, so we ignore them at this level. +fun check_error(loc: String) +do + var error = sys.sdl.error.to_s + if not error.is_empty then + print "at {loc}: {error}" + sys.sdl.clear_error + end +end + +# Init `sdl2`, including video and events +sys.sdl.initialize((new SDLInitFlags).video) +check_error "init" + +# Init `sdl2::image` +sdl.img.initialize((new SDLImgInitFlags).png) +check_error "img_init" + +# Create a window +var window = new SDLWindow("Window title!".to_cstring, 800, 600, (new SDLWindowFlags).opengl) +check_error "window" + +# Create a render, the suffested one +var renderer = new SDLRenderer(window, -1, (new SDLRendererFlags).accelerated) +check_error "renderer" + +# Load an image +var surface = new SDLSurface.load("assets/fighter.png".to_cstring) +check_error "surface" +assert not surface.address_is_null + +# Alternative code to load a BMP image without `sdl2::image` +# +# var surface = new SDLSurface.load_bmp("assets/fighter.bmp".to_cstring) + +# Set the window icon +window.icon = surface +check_error "icon" + +# Get a texture out of that surface +var texture = new SDLTexture.from_surface(renderer, surface) +check_error "texture" + +# Allocate memory for reusable objects +var event = new SDLEventBuffer.malloc +var src = new SDLRect.nil +var dst = new SDLRect(0, 0, 128, 128) + +# Set the colors we will be using +var white = new SDLColor(255, 255, 255, 255) +var green = new SDLColor( 0, 255, 0, 255) +var spacy = new SDLColor( 25, 25, 50, 255) + +loop + # Loop over events until we get a quit event + while event.poll_event do + var higher_event = event.to_event + if higher_event isa SDLQuitEvent then + break label out + else if higher_event isa SDLMouseButtonDownEvent then + # Update `dst` to be centered on the latest click + dst.x = higher_event.x - dst.w/2 + dst.y = higher_event.y - dst.h/2 + end + end + + # Clear the screen with a spacy color + renderer.draw_color = spacy + renderer.clear + + # Draw the target box for the following `copy` + renderer.draw_color = green + renderer.draw_rect dst + + # Copy a texture to the screen + renderer.draw_color = white + renderer.copy(texture, src, dst) + + # Copy the back buffer to the screen + renderer.present + + check_error "present" + + 33.delay +end label out + +# Free all resources +event.free +src.free +dst.free + +texture.free +surface.free + +window.destroy +sdl.img.quit +sys.sdl.quit +~~~ + +## Other features + +* `all` - Unites the main `sdl2` module and its sister library `sdl2::image` +* `events` - SDL 2 events and related services +* `sdl2_base` - Basic SDL 2 features +* `syswm` - Window manager related SDL 2 services + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/sendmail/README.docdown.md b/lib/sendmail/README.docdown.md new file mode 100644 index 0000000000..e750951392 --- /dev/null +++ b/lib/sendmail/README.docdown.md @@ -0,0 +1,11 @@ +# `sendmail` - [[ini-desc: sendmail]] + +[[doc: sendmail::sendmail]] + +## Features + +[[features: sendmail | mentities: sendmail::Mail]] + +## Authors + +This project is maintained by [[ini-maintainer: sendmail]]. diff --git a/lib/sendmail/README.md b/lib/sendmail/README.md new file mode 100644 index 0000000000..d061a45f6e --- /dev/null +++ b/lib/sendmail/README.md @@ -0,0 +1,19 @@ +# `sendmail` - Send emails using the `sendmail` program + +Usage example: + +~~~~ +if sendmail_is_available then + var mail = new Mail("from@example.com", "Title", "Content") + mail.to.add "to@example.org" + mail.send +else print "please install sendmail" +~~~~ + +## Features + +* `Mail` - An email to be sent using `sendmail` + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/serialization/README.docdown.md b/lib/serialization/README.docdown.md new file mode 100644 index 0000000000..2698282da6 --- /dev/null +++ b/lib/serialization/README.docdown.md @@ -0,0 +1,23 @@ +# `serialization` - [[ini-desc: serialization]] + +[[toc: serialization]] + +## Features + +[[uml: serialization | format: svg, mentities: serialization::caching;serialization::engine_tools;serialization::inspect;serialization::safe;serialization::serialization;serialization::serialization_core]] + +### `serialization_core` - Abstract services to serialize Nit objects to different formats + +[[doc: serialization::serialization_core | no-synopsis]] + +Example from `serialization::custom_serialization`: + +[[code: serialization::custom_serialization]] + +## Other features + +[[features: serialization | mentities: serialization::caching;serialization::engine_tools;serialization::inspect;serialization::safe]] + +## Authors + +This project is maintained by [[ini-maintainer: serialization]]. diff --git a/lib/serialization/README.md b/lib/serialization/README.md new file mode 100644 index 0000000000..a6ce23f076 --- /dev/null +++ b/lib/serialization/README.md @@ -0,0 +1,195 @@ +# `serialization` - Abstract serialization services + +* [Features](#Features) +* [`serialization_core` - Abstract services to serialize Nit objects to different formats](#`serialization_core`---Abstract-services-to-serialize-Nit-objects-to-different-formats) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `serialization`](uml-serialization.svg) + +### `serialization_core` - Abstract services to serialize Nit objects to different formats + +This module declares the `serialize` annotation to mark Nit classes as serializable. +For an introduction to this service, refer to the documentation of the `serialization` group. +This documentation provides more technical information on interesting entitie of this module. + +Interesting entities for end users of serializable classes: + +* Serialize an instance subclass of `Serializable` with either + `Serializer::serializable` and `Serializable::serialize`. +* Deserialize an object using `Deserializer::deserialize`. + The object type must the be checked with an `assert` or otherwise. + +Interesting entities to create custom serializable classes: + +* Subclass `Serializable` to declare a class as serializable and to customize + the serialization and deserialization behavior. +* Redefine `Serializable::core_serialize_to` to customize the serialization + of the receiver class. +* Redefine `Deserializer::deserialize_class` to customize the deserialization + of a specific class by name. + +Interesting entities for serialization format: + +* Subclass `Serializer` and `Deserializer` with custom serices. +* In `Serializer`, `serialize` and `serialize_reference` must be redefined. +* In `Deserializer`; `deserialize`, `deserialize_attribute and`notify_of_creation` must be redefined. + +Example from `serialization::custom_serialization`: + +~~~ +# Example of an ad hoc serializer that is tailored to transform business specific objects into customized representation. +# +# In the following, we expose 3 business classes, `E`, `A` and `B`, and a specific business serializer `RestrictedSerializer`. +# The principle is that the custom serialization logic in enclosed into the `RestrictedSerializer` and that the +# standard serializer is unchanged. +# +# The additional behaviors exposed are: +# +# * replace a full business object (see `E::id`): +# instead of serializing an attribute, the custom serializer uses a different representation. +# * inject a phantom attribute (see `E::phantom`): +# when serializing, the custom serializer injects new attributes. +# * hide a normally serialized attribute (see `E::semi_private`): +# when serializing, the custom serializer hides some specific attributes. +# +# The advantage of the approach is that it is done programmatically so can be adapted to real complex use cases. +# Basically, this is half-way between the full automatic serialization and the full manual serialisation. +module custom_serialization is example + +import serialization +import json::serialization_write + +# The root class of the business objects. +# This factorizes most services and domain knowledge used by the `RestrictedSerializer` +# +# In real enterprise-level code, the various specific behaviors can be specified in more semantic classifiers. +abstract class E + serialize + + # The semantic business identifier. + # + # With the `RestrictedSerializer`, references to `E` objects will be replaced with `id`-based information. + # This avoid to duplicate or enlarge the information cross-call wise. + # + # A future API/REST call can then request the _missing_ object from its identifier. + var id: String + + # A phantom attribute to be serialized by the custom `RestrictedSerializer`. + # + # This can be used to inject constant or computed information that make little sense to have as a genuine attribute in + # the Nit model. + fun phantom: String do return "So Much Fun" + + # An attribute not to be serialized by the custom `RestrictedSerializer`. + # e.g. we want it on the DB but not in API/REST JSON messages + # + # Note that the annotation `noserialize` hides the attribute for all serializers. + # To hide the attribute only in the `RestrictedSerializer`, it will have to actively ignore it. + var semi_private = "secret" + + # Test method that serializes `self` and prints with the standard JsonSerializer + fun ser_json + do + var w = new StringWriter + var js = new JsonSerializer(w) + js.plain_json = true + js.serialize(self) + print w + end + + # Test method that serializes `self` and prints with the custom RestrictedJsonSerializer. + fun ser_json2 + do + var w = new StringWriter + var js = new RestrictedJsonSerializer(w) + js.plain_json = true + js.serialize(self) + print w + end +end + +# Extends Serializer and adds specific business behaviors when dealing with business objects. +# +# As with standard Nit, additional level of customization can be achieved by adding more double-dispatching :) +# We can thus choose to locate the specific behavior in the serializer, or the serializees. +class RestrictedSerializer + super Serializer + + # This method is called to generate the attributes of a serialized representation + redef fun serialize_core(value) + do + super + + if value isa E then + # Inject additional special domain-specific information + serialize_attribute("more-data", value.phantom) + end + end + + # This method is called when trying to serialize a specific attribute + redef fun serialize_attribute(name, value) + do + var recv = current_object + if recv isa E then + # do not serialize `E::semi_private` + if name == "semi_private" then return + end + + if value isa E then + # Do not serialize references to `E`. + # Just use a domain-specific value that make sense in the business logic. + serialize_attribute(name, "ID:" + value.id) + return + end + + super + end +end + +# Extends JsonSerializer and adds specific business behaviors when dealing with business objects. +class RestrictedJsonSerializer + super JsonSerializer + super RestrictedSerializer +end + +# A business object, with an integer information +class A + super E + serialize + + # A business information + var i: Int +end + +# A business object associated with an `A`. +class B + super E + serialize + + # A business association + var a: A +end + +# The business data to serialize +var a = new A("a", 1) +var b = new B("b", a) + +a.ser_json +a.ser_json2 +b.ser_json +b.ser_json2 +~~~ + +## Other features + +* `caching` - Services for caching serialization engines +* `engine_tools` - Advanced services for serialization engines +* `inspect` - Refine `Serializable::inspect` to show more useful information +* `safe` - Services for safer deserialization engines + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/sexp/README.docdown.md b/lib/sexp/README.docdown.md new file mode 100644 index 0000000000..d582aa12c8 --- /dev/null +++ b/lib/sexp/README.docdown.md @@ -0,0 +1,11 @@ +# `sexp` - [[ini-desc: sexp]] + +## Features + +[[uml: sexp | format: svg, mentities: sexp::SExpEntity;sexp::SExp;sexp::SExpDQString;sexp::SExpFloat;sexp::SExpId;sexp::SExpError;sexp::SExpProcessor]] + +[[features: sexp | mentities: sexp::SExpEntity;sexp::SExp;sexp::SExpDQString;sexp::SExpFloat;sexp::SExpId;sexp::SExpError;sexp::SExpProcessor]] + +## Authors + +This project is maintained by [[ini-maintainer: sexp]]. diff --git a/lib/sexp/README.md b/lib/sexp/README.md new file mode 100644 index 0000000000..f6025d77dd --- /dev/null +++ b/lib/sexp/README.md @@ -0,0 +1,17 @@ +# `sexp` - S-Expression parsing facilities + +## Features + +![Diagram for `sexp`](uml-sexp.svg) + +* `SExp` - A full S-Expression, delimited by `(` and `)` +* `SExpDQString` - A Double-quoted String +* `SExpEntity` - Any S-Expression entity +* `SExpError` - An error parsing S-Expressions +* `SExpFloat` - A float-value +* `SExpId` - Any Identifier, non string and non-float +* `SExpProcessor` - S-Expression processor + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/sha1/README.docdown.md b/lib/sha1/README.docdown.md new file mode 100644 index 0000000000..8e26e66a29 --- /dev/null +++ b/lib/sha1/README.docdown.md @@ -0,0 +1,21 @@ +# `sha1` - [[ini-desc: sha1]] + +[[toc: sha1]] + +## Features + +### `Text::sha1` - Computes the SHA1 of the receiver + +[[doc: sha1::sha1::Text::sha1 | no-synopsis]] + +### `Text::sha1_hexdigest` - Computes the SHA1 of the receiver. + +[[doc: sha1::sha1::Text::sha1_hexdigest | no-synopsis]] + +### `Text::is_sha1_digest` - Is `self` a SHA-1 hexdigest? + +[[doc: sha1::sha1::Text::is_sha1_digest | no-synopsis]] + +## Authors + +This project is maintained by [[ini-maintainer: sha1]]. diff --git a/lib/sha1/README.md b/lib/sha1/README.md new file mode 100644 index 0000000000..6d08349039 --- /dev/null +++ b/lib/sha1/README.md @@ -0,0 +1,39 @@ +# `sha1` - Provides methods to compute the SHA1 hash of a String + +* [Features](#Features) +* [`Text::sha1` - Computes the SHA1 of the receiver](#`Text::sha1`---Computes-the-SHA1-of-the-receiver) +* [`Text::sha1_hexdigest` - Computes the SHA1 of the receiver.](#`Text::sha1_hexdigest`---Computes-the-SHA1-of-the-receiver.) +* [`Text::is_sha1_digest` - Is `self` a SHA-1 hexdigest?](#`Text::is_sha1_digest`---Is-`self`-a-SHA-1-hexdigest?) +* [Authors](#Authors) + +## Features + +### `Text::sha1` - Computes the SHA1 of the receiver + +Returns a digest of 20 bytes as a CString, +note that all the characters are not necessarily ASCII. +If you want the hex string version of the digest, use +sha1_hexdigest. + + import base64 + assert "The quick brown fox jumps over the lazy dog".sha1 == [0x2F, 0xD4, 0xE1, 0xC6, 0x7A, 0x2D, 0x28, 0xFC, 0xED, 0x84, 0x9E, 0xE1, 0xBB, 0x76, 0xE7, 0x39, 0x1B, 0x93, 0xEB, 0x12] + +### `Text::sha1_hexdigest` - Computes the SHA1 of the receiver. + +Returns a 40 char String containing the Hexadecimal +Digest in its Char form. + + assert "The quick brown fox jumps over the lazy dog".sha1_hexdigest == "2FD4E1C67A2D28FCED849EE1BB76E7391B93EB12" + +### `Text::is_sha1_digest` - Is `self` a SHA-1 hexdigest? + +~~~nit +assert "2FD4E1C67A2D28FCED849EE1BB76E7391B93EB12".is_sha1_digest +assert not "Not a digest".is_sha1_digest +assert not "2FD4E1C67A2D28FCED849EE1B76E7391B93EB12".is_sha1_digest +assert not "2FD4E1C67A2D28FCED849EE1UB76E7391B93EB12".is_sha1_digest +~~~ + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/signals/README.docdown.md b/lib/signals/README.docdown.md new file mode 100644 index 0000000000..d3492af1d9 --- /dev/null +++ b/lib/signals/README.docdown.md @@ -0,0 +1,11 @@ +# `signals` - [[ini-desc: signals]] + +[[doc: signals::signals]] + +## Features + +[[features: signals | mentities: signals::SignalHandler]] + +## Authors + +This project is maintained by [[ini-maintainer: signals]]. diff --git a/lib/signals/README.md b/lib/signals/README.md new file mode 100644 index 0000000000..14801389ca --- /dev/null +++ b/lib/signals/README.md @@ -0,0 +1,51 @@ +# `signals` - ANSI C signal handling + +Common usage imply 5 steps: + +1. Implement the `SignalHandler` interface +2. `redef receive_signal_unsafe` to handle `sigsegv` +3. `redef receive_signal` to handle other signals safely + 4, Notify what signals to handle with `handle_signal` +4. If using the safe handler method, routinely call `check_signals` + +Usage example: + +~~~~ +class MyReceiver + super SignalHandler + + redef fun receive_signal(signal) + do + print "received safely {signal}" + if signal == sigalarm then print "Alarm!" + end + redef fun receive_signal_unsafe( signal ) do print "received unsafely {signal}" +end + +var r = new MyReceiver + +# Handle `sigsegv` signal unsafely (the only way for this one) +r.handle_signal(sigsegv, false) + +# Handle `sigint` and `sigalarm` safely +r.handle_signal(sigint, true) +r.handle_signal(sigalarm, true) + +# Ask system to receive a `sigalarm` signal in 1 second +set_alarm(1) + +loop + # Check signals and callback `receive_signal` + var hit = check_signals + + if hit then break +end +~~~~ + +## Features + +* `SignalHandler` - Receives the callback from system when a given signal arise + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/socket/README.docdown.md b/lib/socket/README.docdown.md new file mode 100644 index 0000000000..ecb1ba7565 --- /dev/null +++ b/lib/socket/README.docdown.md @@ -0,0 +1,11 @@ +# `socket` - [[ini-desc: socket]] + +## Features + +[[uml: socket | format: svg, mentities: socket::socket;socket::socket_c]] + +[[features: socket | mentities: socket::socket_c]] + +## Authors + +This project is maintained by [[ini-maintainer: socket]]. diff --git a/lib/socket/README.md b/lib/socket/README.md new file mode 100644 index 0000000000..0b7dd7db27 --- /dev/null +++ b/lib/socket/README.md @@ -0,0 +1,11 @@ +# `socket` - Socket services + +## Features + +![Diagram for `socket`](uml-socket.svg) + +* `socket_c` - Low-level socket functionalities + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/sqlite3/README.docdown.md b/lib/sqlite3/README.docdown.md new file mode 100644 index 0000000000..e978292adf --- /dev/null +++ b/lib/sqlite3/README.docdown.md @@ -0,0 +1,13 @@ +# `sqlite3` - [[ini-desc: sqlite3]] + +[[doc: sqlite3::sqlite3]] + +## Features + +[[uml: sqlite3 | format: svg, mentities: sqlite3::native_sqlite3;sqlite3::sqlite3]] + +[[features: sqlite3 | mentities: sqlite3::native_sqlite3]] + +## Authors + +This project is maintained by [[ini-maintainer: sqlite3]]. diff --git a/lib/sqlite3/README.md b/lib/sqlite3/README.md new file mode 100644 index 0000000000..03bfe7fc97 --- /dev/null +++ b/lib/sqlite3/README.md @@ -0,0 +1,13 @@ +# `sqlite3` - Services to manipulate a Sqlite3 database + +For more information, refer to the documentation of http://www.sqlite.org/docs.html + +## Features + +![Diagram for `sqlite3`](uml-sqlite3.svg) + +* `native_sqlite3` - Low-level Sqlite3 features + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/standard/README.docdown.md b/lib/standard/README.docdown.md new file mode 100644 index 0000000000..e124a48ca9 --- /dev/null +++ b/lib/standard/README.docdown.md @@ -0,0 +1,5 @@ +# `standard` - [[ini-desc: standard]] + +## Authors + +This project is maintained by [[ini-maintainer: standard]]. diff --git a/lib/standard/README.md b/lib/standard/README.md new file mode 100644 index 0000000000..03421c1d5e --- /dev/null +++ b/lib/standard/README.md @@ -0,0 +1,5 @@ +# `standard` - Old module implicitly imported by the old compiler + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/symbol/README.docdown.md b/lib/symbol/README.docdown.md new file mode 100644 index 0000000000..ea4919ea1d --- /dev/null +++ b/lib/symbol/README.docdown.md @@ -0,0 +1,9 @@ +# `symbol` - [[ini-desc: symbol]] + +## Features + +[[features: symbol | mentities: symbol::Symbol]] + +## Authors + +This project is maintained by [[ini-maintainer: symbol]]. diff --git a/lib/symbol/README.md b/lib/symbol/README.md new file mode 100644 index 0000000000..420463b928 --- /dev/null +++ b/lib/symbol/README.md @@ -0,0 +1,9 @@ +# `symbol` - Library for simple interning of strings + +## Features + +* `Symbol` - A symbol is a unique immutable string + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/template/README.docdown.md b/lib/template/README.docdown.md new file mode 100644 index 0000000000..5abfc512fe --- /dev/null +++ b/lib/template/README.docdown.md @@ -0,0 +1,27 @@ +# `template` - [[ini-desc: template]] + +[[toc: template]] + +[[doc: template::template]] + +Example from `template::tmpl_composer`: + +[[code: template::tmpl_composer]] + +## Features + +[[uml: template | format: svg, mentities: template::macro;template::template]] + +### `macro` - String templating using macros. + +[[doc: template::macro | no-synopsis]] + +## Running the tests + +Run the nitunit automated tests with the following command: + +[[testing: template]] + +## Authors + +This project is maintained by [[ini-maintainer: template]]. diff --git a/lib/template/README.md b/lib/template/README.md new file mode 100644 index 0000000000..05e23f065f --- /dev/null +++ b/lib/template/README.md @@ -0,0 +1,110 @@ +# `template` - Basic template system + +* [Features](#Features) +* [`macro` - String templating using macros.](#`macro`---String-templating-using-macros.) +* [Running the tests](#Running-the-tests) +* [Authors](#Authors) + +The recommended usage of this framework is to define specific subclasses of +Template to provide structural elements on the final document + +Example from `template::tmpl_composer`: + +~~~ +module tmpl_composer is example + +import template + +### Here, definition of the specific templates + +# The root template for composers +class TmplComposers + super Template + + # Short list of composers + var composers = new Array[TmplComposer] + + # Detailled list of composers + var composer_details = new Array[TmplComposerDetail] + + # Add a composer in both lists + fun add_composer(firstname, lastname: String, birth, death: Int) + do + composers.add(new TmplComposer(lastname)) + composer_details.add(new TmplComposerDetail(firstname, lastname, birth, death)) + end + + redef fun rendering do + add """ +COMPOSERS +========= +""" + add_all composers + add """ + +DETAILS +======= +""" + add_all composer_details + end +end + +# A composer in the short list of composers +class TmplComposer + super Template + + # Short name + var name: String + + redef fun rendering do add "- {name}\n" +end + +# A composer in the detailled list of composers +class TmplComposerDetail + super Template + + var firstname: String + var lastname: String + var birth: Int + var death: Int + + redef fun rendering do add """ + +COMPOSER: {{{firstname}}} {{{lastname}}} +BIRTH...: {{{birth}}} +DEATH...: {{{death}}} +""" + +end + +### Here a simple usage of the templates + +var f = new TmplComposers +f.add_composer("Johann Sebastian", "Bach", 1685, 1750) +f.add_composer("George Frideric", "Handel", 1685, 1759) +f.add_composer("Wolfgang Amadeus", "Mozart", 1756, 1791) +f.write_to(stdout) +~~~ + +## Features + +![Diagram for `template`](uml-template.svg) + +### `macro` - String templating using macros. + +There is plenty of macro/templating tools in the worl, +yet another one. + +See `TemplateString` for more details. + +## Running the tests + +Run the nitunit automated tests with the following command: + +~~~bash +nitunit . +~~~ + +## Authors + +This project is maintained by **Jean Privat **. diff --git a/lib/text_stat/README.docdown.md b/lib/text_stat/README.docdown.md new file mode 100644 index 0000000000..a545f9001c --- /dev/null +++ b/lib/text_stat/README.docdown.md @@ -0,0 +1,7 @@ +# `text_stat` - [[ini-desc: text_stat]] + +[[doc: text_stat::text_stat]] + +## Authors + +This project is maintained by [[ini-maintainer: text_stat]]. diff --git a/lib/text_stat/README.md b/lib/text_stat/README.md new file mode 100644 index 0000000000..469d734540 --- /dev/null +++ b/lib/text_stat/README.md @@ -0,0 +1,10 @@ +# `text_stat` - Injects stat-calculating functionalities to Text and its variants + +Every allocation is counted for each available type of Text in Core + +Cached operations are monitored and statistics of their use are printed +at the end of the execution of a program + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/trees/README.docdown.md b/lib/trees/README.docdown.md new file mode 100644 index 0000000000..db2280eaf2 --- /dev/null +++ b/lib/trees/README.docdown.md @@ -0,0 +1,27 @@ +# `trees` - [[ini-desc: trees]] + +[[toc: trees]] + +## Features + +[[uml: trees | format: svg, mentities: trees::abstract_tree;trees::bintree;trees::bktree;trees::rbtree;trees::trees;trees::trie]] + +### `bktree` - Implementation of BKTree + +[[doc: trees::bktree | no-synopsis]] + +### `rbtree` - A red–black tree is a data structure which is a type of self-balancing binary search tree. + +[[doc: trees::rbtree | no-synopsis]] + +### `trie` - A trie (or prefix tree) is a datastructure used to perform prefix searches. + +[[doc: trees::trie | no-synopsis]] + +## Other features + +[[features: trees | mentities: trees::abstract_tree;trees::bintree]] + +## Authors + +This project is maintained by [[ini-maintainer: trees]]. diff --git a/lib/trees/README.md b/lib/trees/README.md new file mode 100644 index 0000000000..2677705c8a --- /dev/null +++ b/lib/trees/README.md @@ -0,0 +1,95 @@ +# `trees` - General module for tree data structures + +* [Features](#Features) +* [`bktree` - Implementation of BKTree](#`bktree`---Implementation-of-BKTree) +* [`rbtree` - A red–black tree is a data structure which is a type of self-balancing binary search tree.](#`rbtree`---A-red–black-tree-is-a-data-structure-which-is-a-type-of-self-balancing-binary-search-tree.) +* [`trie` - A trie (or prefix tree) is a datastructure used to perform prefix searches.](#`trie`---A-trie-(or-prefix-tree)-is-a-datastructure-used-to-perform-prefix-searches.) +* [Other features](#Other-features) +* [Authors](#Authors) + +## Features + +![Diagram for `trees`](uml-trees.svg) + +### `bktree` - Implementation of BKTree + +As proposed by W. A. Burkhard and R. M. Keller in +"Some approaches to best-match file searching" the BKTree data structure +is usefull to speed-up spell checking based on the Levenshtein distance between +words. + +With a BKTree, the complexity to find mispelled words in a dictionnary is *O(log n)* +instead of *O(n)* with a dummy list. + +Example: + +~~~ +# Create a new BKTree +var tree = new BKTree + +# Index some words in the dictionnary for spell checking +tree.add("book") +tree.add("books") +tree.add("cake") +tree.add("boo") +tree.add("cape") +tree.add("boon") +tree.add("cook") +tree.add("cart") + +# Search suggestions in the BKTree +assert tree.search("caqe").join(", ") == "\{1: cake\}, \{1: cape\}" +~~~ + +See . + +### `rbtree` - A red–black tree is a data structure which is a type of self-balancing binary search tree. + +Balance is preserved by painting each node of the tree with one of two colors +(typically called 'red' and 'black') in a way that satisfies certain properties, +which collectively constrain how unbalanced the tree can become in the worst case. +When the tree is modified, the new tree is subsequently rearranged and repainted +to restore the coloring properties. +The properties are designed in such a way that this rearranging and recoloring +can be performed efficiently. + +The balancing of the tree is not perfect but it is good enough to allow it +to guarantee searching in O(log n) time, where n is the total number of elements in the tree. +The insertion and deletion operations, along with the tree rearrangement and recoloring, +are also performed in O(log n) time. + +### `trie` - A trie (or prefix tree) is a datastructure used to perform prefix searches. + +The trie uses an arborescent datastructure to perform searches on a prefix. +With this version of the trie, you can link data to nodes so the trie can +be used as a kind of Map by prefix. + +~~~ +# Associate some integers to Map keys +var trie = new Trie[Int] +trie["foo"] = 1 +trie["fooo"] = 2 +trie["foooo"] = 3 +trie["bar"] = 4 +trie["baz"] = 5 + +# Get stored values by key +print trie.has_key("foo") +print trie["foo"] == 1 + +# Get stored values by prefix +assert trie.has_prefix("fo") +assert not trie.has_prefix("z") +assert trie.find_by_prefix("foo") == [1, 2, 3] +assert trie.find_by_prefix("bar") == [4] +assert trie.find_by_prefix("z").is_empty +~~~ + +## Other features + +* `abstract_tree` - Introduce tree structures abstraction +* `bintree` - Binary Tree data-structure + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/vsm/README.docdown.md b/lib/vsm/README.docdown.md new file mode 100644 index 0000000000..7e64cdd23e --- /dev/null +++ b/lib/vsm/README.docdown.md @@ -0,0 +1,17 @@ +# `vsm` - [[ini-desc: vsm]] + +[[doc: vsm::vsm]] + +Example from `vsm::example_vsm`: + +[[code: vsm::example_vsm]] + +## Features + +[[uml: vsm | format: svg, mentities: vsm::bm25;vsm::vsm]] + +[[features: vsm | mentities: vsm::bm25]] + +## Authors + +This project is maintained by [[ini-maintainer: vsm]]. diff --git a/lib/vsm/README.md b/lib/vsm/README.md new file mode 100644 index 0000000000..59630f4d2d --- /dev/null +++ b/lib/vsm/README.md @@ -0,0 +1,74 @@ +# `vsm` - Vector Space Modelization for Nit + +Vector Space Model (VSM) is an algebraic model for representing text documents +(and any objects, in general) as vectors of identifiers, such as, for example, +index terms. + +It is used in information filtering, information retrieval, indexing and +relevancy rankings. + +Example from `vsm::example_vsm`: + +~~~ +# Example using a `FileIndex` +# +# This example shows of to index files from the system and retrieve them +# with text queries. +module example_vsm is example + +import vsm +import config + +redef class Config + + # --whitelist-exts + var opt_white_exts = new OptionArray("Allowed file extensions (default is [])", + "-w", "--whitelist-exts") + + # --blacklist-exts + var opt_black_exts = new OptionArray("Allowed file extensions (default is [])", + "-b", "--blacklist-exts") + + redef init do + opts.add_option(opt_white_exts, opt_black_exts) + end +end + +var config = new Config +config.tool_description = "usage: example_vsm " +config.parse_options(args) + +if args.length < 1 then + config.usage + exit 1 +end + +var index = new FileIndex +index.whitelist_exts = config.opt_white_exts.value +index.blacklist_exts = config.opt_black_exts.value + +print "Building index..." +index.index_files(args, true) +print "Indexed {index.documents.length} documents" + +loop + print "\nEnter query:" + printn "> " + var input = sys.stdin.read_line + var matches = index.match_string(input) + printn "" + for match in matches do + print match + end +end +~~~ + +## Features + +![Diagram for `vsm`](uml-vsm.svg) + +* `bm25` + +## Authors + +This project is maintained by **Alexandre Terrasa **. diff --git a/lib/websocket/README.docdown.md b/lib/websocket/README.docdown.md new file mode 100644 index 0000000000..1f79abaed5 --- /dev/null +++ b/lib/websocket/README.docdown.md @@ -0,0 +1,29 @@ +# `websocket` - [[ini-desc: websocket]] + +[[toc: websocket]] + +## Features + +### `WebsocketServer` - Websocket compatible server + +[[doc: websocket::WebsocketServer | no-synopsis]] + +Properties: + +[[features: websocket::WebsocketServer | min-visibility: public, no-redef]] + +### `WebsocketConnection` - Connection to a websocket client + +[[doc: websocket::WebsocketConnection | no-synopsis]] + +Properties: + +[[features: websocket::WebsocketConnection | min-visibility: public, no-redef]] + +Example from `websocket::websocket_server`: + +[[code: websocket::websocket_server]] + +## Authors + +This project is maintained by [[ini-maintainer: websocket]]. diff --git a/lib/websocket/README.md b/lib/websocket/README.md new file mode 100644 index 0000000000..1d369a47c6 --- /dev/null +++ b/lib/websocket/README.md @@ -0,0 +1,67 @@ +# `websocket` - Adds support for a websocket connection in Nit + +* [Features](#Features) +* [`WebsocketServer` - Websocket compatible server](#`WebsocketServer`---Websocket-compatible-server) +* [`WebsocketConnection` - Connection to a websocket client](#`WebsocketConnection`---Connection-to-a-websocket-client) +* [Authors](#Authors) + +## Features + +### `WebsocketServer` - Websocket compatible server + +Produces Websocket client-server connections + +Properties: + +* `WebsocketServer::accept` - Accepts an incoming connection +* `WebsocketServer::close` - Close the server and the socket below it +* `WebsocketServer::with_infos` - Creates a new Websocket server listening on given port + +### `WebsocketConnection` - Connection to a websocket client + +Can be used to communicate with a client + +Properties: + +* `WebsocketConnection::can_read` - Is there some data available to be read ? +* `WebsocketConnection::connected` - Checks if a connection to a client is available + +Example from `websocket::websocket_server`: + +~~~ +# Sample module for a minimal chat server using Websockets on port 8088 +module websocket_server is example + +import websocket + +var sock = new WebsocketServer.with_infos(8088, 1) + +var msg: String + +if sock.listener.closed then + print sys.errno.strerror +end + +var cli: WebsocketConnection + +while not sock.closed do + cli = sock.accept + while cli.connected do + if sys.stdin.poll_in then + msg = gets + printn "Sending message : {msg}" + if msg == "disconnect" then cli.close + cli.write(msg) + end + if cli.can_read(10) then + msg = "" + while cli.can_read(0) do msg += cli.read(100) + if msg != "" then print msg + end + end +end +~~~ + +## Authors + +This project is maintained by **Lucas Bajolet **. diff --git a/lib/x11/README.docdown.md b/lib/x11/README.docdown.md new file mode 100644 index 0000000000..fdd443f120 --- /dev/null +++ b/lib/x11/README.docdown.md @@ -0,0 +1,5 @@ +# `x11` - [[ini-desc: x11]] + +## Authors + +This project is maintained by [[ini-maintainer: x11]]. diff --git a/lib/x11/README.md b/lib/x11/README.md new file mode 100644 index 0000000000..0f66acd840 --- /dev/null +++ b/lib/x11/README.md @@ -0,0 +1,5 @@ +# `x11` - Services from the X11 library + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/lib/xdg_basedir/README.docdown.md b/lib/xdg_basedir/README.docdown.md new file mode 100644 index 0000000000..e41c82dd1b --- /dev/null +++ b/lib/xdg_basedir/README.docdown.md @@ -0,0 +1,35 @@ +# `xdg_basedir` - [[ini-desc: xdg_basedir]] + +[[toc: xdg_basedir]] + +[[doc: xdg_basedir::xdg_basedir]] + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +[[parents: xdg_basedir]] + +### Run `show_basedir` + +Compile `show_basedir` with the following command: + +[[main-compile: xdg_basedir::show_basedir]] + +## Features + +[[uml: xdg_basedir | format: svg, mentities: xdg_basedir::show_basedir;xdg_basedir::xdg_basedir]] + +[[features: xdg_basedir | mentities: xdg_basedir::show_basedir]] + +Then run it with: + +[[main-run: xdg_basedir::show_basedir]] + +## Authors + +This project is maintained by [[ini-maintainer: xdg_basedir]]. diff --git a/lib/xdg_basedir/README.md b/lib/xdg_basedir/README.md new file mode 100644 index 0000000000..e901a626b8 --- /dev/null +++ b/lib/xdg_basedir/README.md @@ -0,0 +1,47 @@ +# `xdg_basedir` - Services for using the XDG Base Directory specification + +* [Getting Started](#Getting-Started) +* [Dependencies](#Dependencies) +* [Run `show_basedir`](#Run-`show_basedir`) +* [Features](#Features) +* [Authors](#Authors) + +This is a low-level module, it is meant to be wrapped by higher level services. + +For more information, refer to the documentation of the `libxdg-basedir` +project or the official specification at: +http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html + +## Getting Started + +These instructions will get you a copy of the project up and running on your local machine. + +### Dependencies + +This project requires the following packages: + +* `core` - Nit common library of core classes and methods + +### Run `show_basedir` + +Compile `show_basedir` with the following command: + +~~~bash +nitc ./show_basedir.nit +~~~ + +## Features + +![Diagram for `xdg_basedir`](uml-xdg_basedir.svg) + +* `show_basedir` - Prints the local base directories as per the XDG Base Directory specification + +Then run it with: + +~~~bash +./show_basedir +~~~ + +## Authors + +This project is maintained by **Alexis Laferrière **. diff --git a/uml-a_star.svg b/uml-a_star.svg new file mode 100644 index 0000000000..230ffeed0f --- /dev/null +++ b/uml-a_star.svg @@ -0,0 +1,142 @@ + + + + + + +G + + +a_star::Node + + +Node + ++ + N: Node + ++ + find_closest(max_cost: Int, context: PathContext, cond: nullable TargetCondition[N]): nullable N ++ + path_to(dest: N, max_cost: Int, context: PathContext): nullable AStarPath[N] ++ + path_to_alts(destination: nullable N, max_cost: Int, context: PathContext, alt_targets: nullable TargetCondition[N]): nullable AStarPath[N] + + +a_star::Link + + +Link + ++ + N: Node ++ + L: Link + + +a_star::Graph + + +Graph[N: Node, L: Link] + ++ + add_link(link: L: Link): L ++ + add_node(node: N: Node): N + + +a_star::AStarPath + + +AStarPath[N: nullable Object] + ++ + at_end_of_path(): Bool ++ + peek_step(): N ++ + step(): N + + +a_star::PathContext + + +<<abstract>> +PathContext + ++ + N: Node ++ + L: Link + ++ + +cost +(link: L): Int ++ + +heuristic_cost +(a: N, b: N): Int ++ + +is_blocked +(link: L): Bool ++ + +worst_heuristic_cost +(): Int + + +a_star::ConstantPathContext + + +ConstantPathContext + + +a_star::ConstantPathContext->a_star::PathContext + + + + +a_star::WeightedPathContext + + +WeightedPathContext + + +a_star::WeightedPathContext->a_star::PathContext + + + + +a_star::WeightedLink + + +WeightedLink + + +a_star::WeightedLink->a_star::Link + + + + +a_star::TargetCondition + + +<<abstract>> +TargetCondition[N: Node] + ++ + +accept +(node: N: Node): Bool ++ + +heuristic_cost +(node: N: Node, link: Link): Int + + + diff --git a/uml-ai.svg b/uml-ai.svg new file mode 100644 index 0000000000..302bdb98c7 --- /dev/null +++ b/uml-ai.svg @@ -0,0 +1,51 @@ + + + + + + +G + + +ai::ai + + + +ai + + +ai::backtrack + + + +backtrack ++ +BacktrackNode ++ +BacktrackProblem ++ +BacktrackSolver + + +ai::ai->ai::backtrack + + + + +ai::search + + + +search ++ +SearchNode ++ +SearchProblem ++ +SearchSolver + + + diff --git a/uml-android.svg b/uml-android.svg new file mode 100644 index 0000000000..1e1e59425c --- /dev/null +++ b/uml-android.svg @@ -0,0 +1,188 @@ + + + + + + +G + + +android&gt; + +android ++ +activities ++ +android ++ +assets ++ +assets_and_resources ++ +audio ++ +aware ++ +cardboard ++ +dalvik ++ +data_store ++ +game ++ +gamepad ++ +http_request ++ +input_events ++ +key_event ++ +landscape ++ +load_image ++ +log ++ +native_app_glue ++ +nit_activity ++ +platform ++ +portrait ++ +sensors ++ +toast ++ +vibration ++ +wifi + + +android&gt;bundle&gt; + +bundle ++ +bundle + + +android&gt;->android&gt;bundle&gt; + + + + +android&gt;shared_preferences&gt; + +shared_preferences ++ +shared_preferences ++ +shared_preferences_api10 ++ +shared_preferences_api11 + + +android&gt;->android&gt;shared_preferences&gt; + + + + +android&gt;ui&gt; + +ui ++ +native_ui ++ +ui + + +android&gt;->android&gt;ui&gt; + + + + +android&gt;bundle&gt;->android&gt; + + + + +android&gt;intent&gt; + +intent ++ +intent ++ +intent_api10 ++ +intent_api11 ++ +intent_api12 ++ +intent_api14 ++ +intent_api15 ++ +intent_api16 ++ +intent_api17 ++ +intent_api18 ++ +intent_api19 + + +android&gt;intent&gt;->android&gt; + + + + +android&gt;intent&gt;->android&gt;bundle&gt; + + + + +android&gt;notification&gt; + +notification ++ +native_notification ++ +notification + + +android&gt;notification&gt;->android&gt; + + + + +android&gt;service&gt; + +service ++ +at_boot ++ +service + + +android&gt;service&gt;->android&gt; + + + + +android&gt;shared_preferences&gt;->android&gt; + + + + +android&gt;ui&gt;->android&gt; + + + + + diff --git a/uml-app.svg b/uml-app.svg new file mode 100644 index 0000000000..a720b5b1cc --- /dev/null +++ b/uml-app.svg @@ -0,0 +1,168 @@ + + + + + + +G + + +app::app + + + +app + + +app::app_base + + + +app_base ++ +App ++ +AppComponent ++ +Sys + + +app::app->app::app_base + + + + +app::assets + + + +assets ++ +Asset ++ +TextAsset + + +app::app->app::assets + + + + +app::audio + + + +audio ++ +Music ++ +PlayableAudio ++ +Sound ++ +Sys + + +app::audio->app::app_base + + + + +app::data_store + + + +data_store ++ +App ++ +DataStore + + +app::data_store->app::app_base + + + + +app::http_request + + + +http_request ++ +App ++ +AsyncHttpRequest ++ +HttpRequestResult ++ +SimpleAsyncHttpRequest ++ +Text + + +app::http_request->app::app_base + + + + +app::ui + + + +ui ++ +App ++ +AppComponent ++ +AppEvent ++ +AppObserver ++ +Button ++ +ButtonPressEvent ++ +CheckBox ++ +CompositeControl ++ +Control ++ +HorizontalLayout ++ +Label ++ +Layout ++ +ListLayout ++ +Sys ++ +Text ++ +TextInput ++ +TextView ++ +ToggleEvent ++ +VerticalLayout ++ +View ++ +ViewEvent ++ +Window + + +app::ui->app::app_base + + + + + diff --git a/uml-bucketed_game.svg b/uml-bucketed_game.svg new file mode 100644 index 0000000000..fa80e1a828 --- /dev/null +++ b/uml-bucketed_game.svg @@ -0,0 +1,135 @@ + + + + + + +G + + +bucketed_game::Turnable + + +<<abstract>> +Turnable[G: Game] + ++ + +do_turn +(turn: GameTurn[G]) + + +bucketed_game::Bucketable + + +<<abstract>> +Bucketable[G: Game] + ++ + cancel_act() + + +bucketed_game::Bucketable->bucketed_game::Turnable + + + + +bucketed_game::Buckets + + +Buckets[G: Game] + ++ + BUCKET: HashSet[Bucketable[G]] + ++ + add_at(e: Bucketable[G], at_tick: Int) ++ + stats(): String + + +bucketed_game::Buckets->bucketed_game::Turnable + + + + +bucketed_game::GameEvent + + +<<interface>> +GameEvent + ++ + +apply +(game: ThinGame) + + +bucketed_game::FirstTurnEvent + + +FirstTurnEvent + + +bucketed_game::FirstTurnEvent->bucketed_game::GameEvent + + + + +bucketed_game::ThinGame + + +ThinGame + + +bucketed_game::ThinGameTurn + + +ThinGameTurn[G: ThinGame] + + +bucketed_game::GameTurn + + +GameTurn[G: Game] + ++ + act_in(e: Bucketable[G], t: Int) ++ + act_next(e: Bucketable[G]) ++ + add_event(event: GameEvent) ++ + init(game: G: Game) + + +bucketed_game::GameTurn->bucketed_game::ThinGameTurn + + + + +bucketed_game::Game + + +Game + ++ + G: Game + ++ + do_post_turn(turn: GameTurn[G]) ++ + do_pre_turn(turn: GameTurn[G]) ++ + do_turn(): GameTurn[G] + + +bucketed_game::Game->bucketed_game::ThinGame + + + + + diff --git a/uml-c.svg b/uml-c.svg new file mode 100644 index 0000000000..11461702fe --- /dev/null +++ b/uml-c.svg @@ -0,0 +1,185 @@ + + + + + + +G + + +c::CArray + + +<<abstract>> +CArray[E: nullable Object] + ++ + NATIVE: NativeCArray + ++ + []=(index: Int, val: E: nullable Object) ++ + destroy() ++ + init(length: Int) + + +c::NativeCArray + + +<<extern>> +NativeCArray + ++ + E: nullable Object + ++ + ++ +(offset: Int): SELF ++ + +[] +(index: Int): E ++ + +[]= +(index: Int, val: E) + + +c::CIntArray + + +CIntArray + ++ + from(array: SequenceRead[Int]): CIntArray ++ + init(size: Int) + + +c::CIntArray->c::CArray + + + + +c::NativeCIntArray + + +<<extern>> +NativeCIntArray + ++ + new(size: Int): NativeCIntArray + + +c::NativeCIntArray->c::NativeCArray + + + + +c::CUInt16Array + + +CUInt16Array + ++ + from(array: SequenceRead[Int]): CUInt16Array ++ + init(size: Int) + + +c::CUInt16Array->c::CArray + + + + +c::NativeCUInt16Array + + +<<extern>> +NativeCUInt16Array + ++ + new(size: Int): NativeCUInt16Array + + +c::NativeCUInt16Array->c::NativeCArray + + + + +c::CByteArray + + +CByteArray + ++ + from(array: SequenceRead[Byte]): CByteArray ++ + init(size: Int) ++ + move(dst_offset: Int, src_offset: Int, n: Int) ++ + to_java_nio_buffer(): Java_nio_ByteBuffer + + +c::CByteArray->c::CArray + + + + +c::NativeCByteArray + + +<<extern>> +NativeCByteArray + ++ + move(dst_offset: Int, src_offset: Int, n: Int) ++ + new(size: Int): NativeCByteArray + + +c::NativeCByteArray->c::NativeCArray + + + + +c::CCStringArray + + +CCStringArray + ++ + from(array: SequenceRead[CString]): CCStringArray ++ + init(size: Int) + + +c::CCStringArray->c::CArray + + + + +c::NativeCStringArray + + +<<extern>> +NativeCStringArray + ++ + destroy() ++ + new(size: Int): NativeCStringArray + + +c::NativeCStringArray->c::NativeCArray + + + + + diff --git a/uml-cocoa.svg b/uml-cocoa.svg new file mode 100644 index 0000000000..08cf8e0f0d --- /dev/null +++ b/uml-cocoa.svg @@ -0,0 +1,62 @@ + + + + + + +G + + +cocoa::app_kit + + + +app_kit ++ +NSAlert + + +cocoa::foundation + + + +foundation ++ +CString ++ +NSData ++ +NSError ++ +NSIndexPath ++ +NSObject ++ +NSString ++ +NSUserDefaults ++ +Text + + +cocoa::app_kit->cocoa::foundation + + + + +cocoa::cocoa + + + +cocoa + + +cocoa::cocoa->cocoa::app_kit + + + + + diff --git a/uml-core.svg b/uml-core.svg new file mode 100644 index 0000000000..b542eb3756 --- /dev/null +++ b/uml-core.svg @@ -0,0 +1,144 @@ + + + + + + +G + + +core&gt; + +core ++ +bitset ++ +bytes ++ +core ++ +environ ++ +error ++ +exec ++ +file ++ +fixed_ints ++ +gc ++ +kernel ++ +math ++ +numeric ++ +protocol ++ +queue ++ +re ++ +stream ++ +time + + +core&gt;codecs&gt; + +codecs ++ +codec_base ++ +codecs ++ +iso8859_1 ++ +utf8 + + +core&gt;->core&gt;codecs&gt; + + + + +core&gt;collection&gt; + +collection ++ +abstract_collection ++ +array ++ +circular_array ++ +collection ++ +hash_collection ++ +list ++ +range ++ +sorter ++ +union_find + + +core&gt;->core&gt;collection&gt; + + + + +core&gt;text&gt; + +text ++ +abstract_text ++ +fixed_ints_text ++ +flat ++ +native ++ +ropes ++ +string_search ++ +test_abstract_text ++ +text + + +core&gt;->core&gt;text&gt; + + + + +core&gt;codecs&gt;->core&gt; + + + + +core&gt;codecs&gt;->core&gt;text&gt; + + + + +core&gt;collection&gt;->core&gt; + + + + +core&gt;text&gt;->core&gt; + + + + + diff --git a/uml-crapto.svg b/uml-crapto.svg new file mode 100644 index 0000000000..ab9c6fc06c --- /dev/null +++ b/uml-crapto.svg @@ -0,0 +1,52 @@ + + + + + + +G + + +crapto::crapto + + + +crapto + + +crapto::xor + + + +xor ++ +RepeatingKeyXorCipher ++ +SingleByteXorCipher + + +crapto::crapto->crapto::xor + + + + +crapto::english_utils + + + +english_utils ++ +Sys ++ +Text + + +crapto::xor->crapto::english_utils + + + + + diff --git a/uml-crypto.svg b/uml-crypto.svg new file mode 100644 index 0000000000..ddfc6eebfd --- /dev/null +++ b/uml-crypto.svg @@ -0,0 +1,76 @@ + + + + + + +G + + +crypto::basic_ciphers + + + +basic_ciphers ++ +Bytes ++ +Char ++ +Int ++ +Text + + +crypto::bytes + + + +bytes ++ +Bytes + + +crypto::crypto + + + +crypto + + +crypto::crypto->crypto::basic_ciphers + + + + +crypto::crypto->crypto::bytes + + + + +crypto::xor_ciphers + + + +xor_ciphers ++ +Bytes ++ +CString ++ +Cipher ++ +RepeatingKeyXorCipher ++ +SingleByteXorCipher + + +crypto::crypto->crypto::xor_ciphers + + + + + diff --git a/uml-csv.svg b/uml-csv.svg new file mode 100644 index 0000000000..3c9ff1fc62 --- /dev/null +++ b/uml-csv.svg @@ -0,0 +1,70 @@ + + + + + + +G + + +csv::CsvStream + + +<<abstract>> +CsvStream + + +csv::CsvDocument + + +CsvDocument + ++ + add_record(objs: Object) ++ + load_from(stream: Reader, has_header: nullable Bool, skip_empty: nullable Bool) + + +csv::CsvDocument->csv::CsvStream + + + + +csv::CsvWriter + + +CsvWriter + ++ + write_elements(els: Object) ++ + write_line(line: Array[Object]) ++ + write_lines(lines: Array[Array[Object]]) + + +csv::CsvWriter->csv::CsvStream + + + + +csv::CsvReader + + +CsvReader + ++ + from_string(s: String) ++ + read_all(has_header: nullable Bool): CsvDocument + + +csv::CsvReader->csv::CsvStream + + + + + diff --git a/uml-curl.svg b/uml-curl.svg new file mode 100644 index 0000000000..45ee2593e9 --- /dev/null +++ b/uml-curl.svg @@ -0,0 +1,80 @@ + + + + + + +G + + +curl::curl + + + +curl ++ +Curl ++ +CurlCallbacks ++ +CurlFileResponseSuccess ++ +CurlHTTPRequest ++ +CurlMail ++ +CurlRequest ++ +CurlResponse ++ +CurlResponseFailed ++ +CurlResponseSuccess ++ +CurlResponseSuccessIntern ++ +HeaderMap ++ +Sys + + +curl::native_curl + + + +native_curl ++ +CString ++ +CURLCode ++ +CURLInfoChars ++ +CURLInfoDouble ++ +CURLInfoLong ++ +CURLInfoSList ++ +CURLOption ++ +CURLSList ++ +CURLStatusCode ++ +Collection ++ +NativeCurl ++ +NativeCurlCallbacks + + +curl::curl->curl::native_curl + + + + + diff --git a/uml-dom.svg b/uml-dom.svg new file mode 100644 index 0000000000..42663b0eff --- /dev/null +++ b/uml-dom.svg @@ -0,0 +1,90 @@ + + + + + + +G + + +dom::dom + + + +dom ++ +XMLAttrTag ++ +XMLEntity ++ +XMLStartTag + + +dom::parser + + + +parser ++ +Text ++ +XMLProcessor + + +dom::dom->dom::parser + + + + +dom::xml_entities + + + +xml_entities ++ +BadXMLAttribute ++ +CDATA ++ +PCDATA ++ +XMLAttrTag ++ +XMLAttribute ++ +XMLCommentTag ++ +XMLDoctypeTag ++ +XMLDocument ++ +XMLEndTag ++ +XMLEntity ++ +XMLError ++ +XMLOnelinerTag ++ +XMLProcessingInstructionTag ++ +XMLPrologTag ++ +XMLSpecialTag ++ +XMLStartTag ++ +XMLStringAttr ++ +XMLTag + + +dom::parser->dom::xml_entities + + + + + diff --git a/uml-dot.svg b/uml-dot.svg new file mode 100644 index 0000000000..068d372773 --- /dev/null +++ b/uml-dot.svg @@ -0,0 +1,98 @@ + + + + + + +G + + +dot::DotElement + + +<<abstract>> +DotElement + ++ + [](key: String): Object ++ + []=(key: String, value: Object) ++ + escape_id(): String ++ + to_dot(): Text + + +dot::AttributeMap + + +AttributeMap + ++ + to_dot(separator: String): Text + + +dot::DotGraph + + +DotGraph + ++ + add(element: DotElement) ++ + add_edge(from: DotElement, to: DotElement): DotEdge ++ + add_node(id: String): DotNode ++ + show() ++ + to_svg(): Text + + +dot::DotGraph->dot::DotElement + + + + +dot::DotNode + + +DotNode + + +dot::DotNode->dot::DotElement + + + + +dot::DotEdge + + +DotEdge + + +dot::DotEdge->dot::DotElement + + + + +dot::DotCluster + + +DotCluster + + +dot::DotCluster->dot::DotGraph + + + + +dot::DotCluster->dot::DotNode + + + + + diff --git a/uml-gamnit.svg b/uml-gamnit.svg new file mode 100644 index 0000000000..3bcb92e21f --- /dev/null +++ b/uml-gamnit.svg @@ -0,0 +1,190 @@ + + + + + + +G + + +gamnit&gt; + +gamnit ++ +android19 ++ +bmfont ++ +camera_control ++ +camera_control_android ++ +camera_control_linux ++ +cameras ++ +cameras_cache ++ +display ++ +display_android ++ +display_ios ++ +display_linux ++ +dynamic_resolution ++ +egl ++ +font ++ +gamnit ++ +gamnit_android ++ +gamnit_ios ++ +gamnit_linux ++ +input_ios ++ +keys ++ +landscape ++ +limit_fps ++ +portrait ++ +programs ++ +texture_atlas_parser ++ +textures ++ +tileset + + +gamnit&gt;flat&gt; + +flat ++ +flat ++ +flat_core + + +gamnit&gt;->gamnit&gt;flat&gt; + + + + +gamnit&gt;depth&gt; + +depth ++ +cardboard ++ +depth ++ +depth_core ++ +model_dimensions ++ +more_lights ++ +more_materials ++ +more_meshes ++ +more_models ++ +particles ++ +selection ++ +shadow ++ +stereoscopic_view ++ +vr + + +gamnit&gt;depth&gt;->gamnit&gt;flat&gt; + + + + +gamnit&gt;model_parsers&gt; + +model_parsers ++ +model_parser_base ++ +mtl ++ +obj + + +gamnit&gt;depth&gt;->gamnit&gt;model_parsers&gt; + + + + +gamnit&gt;flat&gt;->gamnit&gt; + + + + +gamnit&gt;network&gt; + +network ++ +client ++ +common ++ +network ++ +server + + +gamnit&gt;virtual_gamepad&gt; + +virtual_gamepad ++ +virtual_gamepad ++ +virtual_gamepad_spritesheet + + +gamnit&gt;virtual_gamepad&gt;->gamnit&gt; + + + + +gamnit&gt;virtual_gamepad&gt;->gamnit&gt;flat&gt; + + + + +gamnit&gt;virtual_gamepad&gt;art&gt; + +art + + +gamnit&gt;virtual_gamepad&gt;assets&gt; + +assets + + +gamnit&gt;virtual_gamepad&gt;assets&gt;images&gt; + +images + + + diff --git a/uml-geometry.svg b/uml-geometry.svg new file mode 100644 index 0000000000..9bb67e69d6 --- /dev/null +++ b/uml-geometry.svg @@ -0,0 +1,141 @@ + + + + + + +G + + +geometry::angles + + + +angles ++ +Float ++ +Point + + +geometry::points_and_lines + + + +points_and_lines ++ +Deserializer ++ +ILine ++ +ILine3d ++ +IPoint ++ +IPoint3d ++ +Line ++ +Line3d ++ +Point ++ +Point3d + + +geometry::angles->geometry::points_and_lines + + + + +geometry::boxes + + + +boxes ++ +Box ++ +Box3d ++ +Boxed ++ +Boxed3d ++ +BoxedArray ++ +BoxedCollection ++ +ILine ++ +ILine3d ++ +IPoint ++ +IPoint3d + + +geometry::boxes->geometry::points_and_lines + + + + +geometry::geometry + + + +geometry + + +geometry::geometry->geometry::angles + + + + +geometry::geometry->geometry::boxes + + + + +geometry::polygon + + + +polygon ++ +APolygon ++ +ConvexPolygon ++ +Polygon ++ +Sys + + +geometry::polygon->geometry::points_and_lines + + + + +geometry::quadtree + + + +quadtree ++ +DQuadTree ++ +QuadTree ++ +SQuadTree + + +geometry::quadtree->geometry::boxes + + + + + diff --git a/uml-github.svg b/uml-github.svg new file mode 100644 index 0000000000..90a40192ce --- /dev/null +++ b/uml-github.svg @@ -0,0 +1,243 @@ + + + + + + +G + + +github::api + + + +api ++ +Branch ++ +Comment ++ +Commit ++ +CommitComment ++ +ContributorStats ++ +Deserializer ++ +GitCommit ++ +GitUser ++ +GithubAPI ++ +GithubDeserializer ++ +GithubEntity ++ +GithubFile ++ +ISODate ++ +Issue ++ +IssueComment ++ +IssueEvent ++ +Label ++ +Milestone ++ +PullRef ++ +PullRequest ++ +RenameAction ++ +Repo ++ +ReviewComment ++ +User + + +github::github_curl + + + +github_curl ++ +GithubCurl ++ +GithubError ++ +Sys + + +github::api->github::github_curl + + + + +github::cache + + + +cache ++ +GithubAPI + + +github::cache->github::api + + + + +github::events + + + +events ++ +CommitCommentEvent ++ +CreateEvent ++ +DeleteEvent ++ +DeploymentEvent ++ +DeploymentStatusEvent ++ +Deserializer ++ +ForkEvent ++ +GithubDeserializer ++ +GithubEvent ++ +IssueCommentEvent ++ +IssuesEvent ++ +MemberEvent ++ +PullRequestEvent ++ +PullRequestReviewCommentEvent ++ +PushEvent ++ +StatusEvent + + +github::events->github::api + + + + +github::github + + + +github + + +github::github->github::cache + + + + +github::hooks + + + +hooks ++ +HookListener + + +github::hooks->github::events + + + + +github::loader + + + +loader ++ +Branch ++ +BranchRepo ++ +Commit ++ +CommitRepo ++ +Deserializer ++ +GithubWallet ++ +Issue ++ +IssueComment ++ +IssueCommentRepo ++ +IssueEvent ++ +IssueEventRepo ++ +IssueRepo ++ +Loader ++ +LoaderConfig ++ +LoaderJob ++ +LoaderJobRepo ++ +PullRequestRepo ++ +Repo ++ +RepoEntity ++ +RepoRepo ++ +Sys + + +github::loader->github::events + + + + +github::wallet + + + +wallet ++ +GithubWallet + + +github::loader->github::wallet + + + + +github::wallet->github::github + + + + + diff --git a/uml-gmp.svg b/uml-gmp.svg new file mode 100644 index 0000000000..5a61996b4a --- /dev/null +++ b/uml-gmp.svg @@ -0,0 +1,50 @@ + + + + + + +G + + +gmp::gmp + + + +gmp ++ +BigInt ++ +Float ++ +Int ++ +Numeric ++ +Ratio ++ +Text + + +gmp::native_gmp + + + +native_gmp ++ +NativeMPQ ++ +NativeMPZ ++ +UInt64 + + +gmp::gmp->gmp::native_gmp + + + + + diff --git a/uml-graph.svg b/uml-graph.svg new file mode 100644 index 0000000000..c5c7533b19 --- /dev/null +++ b/uml-graph.svg @@ -0,0 +1,44 @@ + + + + + + +G + + +graph::digraph + + + +digraph ++ +ArcsIterator ++ +Digraph ++ +HashDigraph ++ +MutableDigraph + + +graph::pagerank + + + +pagerank ++ +Digraph ++ +PRMap + + +graph::pagerank->graph::digraph + + + + + diff --git a/uml-gtk.svg b/uml-gtk.svg new file mode 100644 index 0000000000..8f7adaa400 --- /dev/null +++ b/uml-gtk.svg @@ -0,0 +1,52 @@ + + + + + + +G + + +gtk&gt; + +gtk ++ +gtk ++ +v3_10 ++ +v3_6 ++ +v3_8 + + +gtk&gt;v3_4&gt; + +v3_4 ++ +gdk ++ +gdk_enums ++ +gtk_assistant ++ +gtk_core ++ +gtk_dialogs ++ +gtk_enums ++ +gtk_widgets_ext ++ +v3_4 + + +gtk&gt;->gtk&gt;v3_4&gt; + + + + + diff --git a/uml-html.svg b/uml-html.svg new file mode 100644 index 0000000000..55b2119139 --- /dev/null +++ b/uml-html.svg @@ -0,0 +1,59 @@ + + + + + + +G + + +html::bootstrap + + + +bootstrap ++ +BSAlert ++ +BSBadge ++ +BSBreadCrumbs ++ +BSComponent ++ +BSIcon ++ +BSLabel ++ +BSPageHeader ++ +BSPanel ++ +HTMLList ++ +Header ++ +Link ++ +ListItem ++ +OrderedList ++ +UnorderedList + + +html::html + + + +html ++ +HTMLPage ++ +HTMLTag + + + diff --git a/uml-ios.svg b/uml-ios.svg new file mode 100644 index 0000000000..9900477e74 --- /dev/null +++ b/uml-ios.svg @@ -0,0 +1,48 @@ + + + + + + +G + + +ios&gt; + +ios ++ +app ++ +assets ++ +audio ++ +data_store ++ +glkit ++ +http_request ++ +ios ++ +platform + + +ios&gt;ui&gt; + +ui ++ +ui ++ +uikit + + +ios&gt;ui&gt;->ios&gt; + + + + + diff --git a/uml-java.svg b/uml-java.svg new file mode 100644 index 0000000000..f3c63ec732 --- /dev/null +++ b/uml-java.svg @@ -0,0 +1,106 @@ + + + + + + +G + + +java::collections + + + +collections ++ +AbstractJavaArray ++ +JavaArray ++ +JavaBoolArray ++ +JavaByteArray ++ +JavaCharArray ++ +JavaDoubleArray ++ +JavaFloatArray ++ +JavaIntArray ++ +JavaLongArray ++ +JavaShortArray + + +java::ffi_support + + + +ffi_support ++ +CString ++ +JavaException ++ +JavaObject ++ +JavaString ++ +JavaThrowable ++ +Java_nio_Buffer ++ +Java_nio_ByteBuffer ++ +JniEnv ++ +Sys ++ +Text + + +java::collections->java::ffi_support + + + + +java::io + + + +io ++ +NativeFile ++ +NativeFileDescriptor ++ +NativeFileInputStream ++ +NativeFileOutputStream ++ +NativeInputStream + + +java::io->java::ffi_support + + + + +java::java + + + +java + + +java::java->java::collections + + + + + diff --git a/uml-json.svg b/uml-json.svg new file mode 100644 index 0000000000..3bff5b9eb8 --- /dev/null +++ b/uml-json.svg @@ -0,0 +1,154 @@ + + + + + + +G + + +json::dynamic + + + +dynamic ++ +JsonKeyError ++ +JsonValue ++ +Text + + +json::static + + + +static ++ +Char ++ +FlatText ++ +JSONStringParser ++ +JsonArray ++ +JsonMapRead ++ +JsonObject ++ +JsonSequenceRead ++ +Text + + +json::dynamic->json::static + + + + +json::error + + + +error ++ +Deserializer ++ +JsonParseError + + +json::json + + + +json + + +json::serialization_read + + + +serialization_read ++ +JsonDeserializer ++ +Map ++ +SimpleCollection ++ +Sys ++ +Text + + +json::json->json::serialization_read + + + + +json::serialization_write + + + +serialization_write ++ +Bool ++ +Byte ++ +CString ++ +Char ++ +Collection ++ +Float ++ +Int ++ +JsonSerializer ++ +Map ++ +Serializable ++ +SimpleCollection ++ +Text + + +json::json->json::serialization_write + + + + +json::serialization_read->json::static + + + + +json::static->json::error + + + + +json::store + + + +store ++ +JsonStore + + +json::store->json::json + + + + + diff --git a/uml-libevent.svg b/uml-libevent.svg new file mode 100644 index 0000000000..a03812fd62 --- /dev/null +++ b/uml-libevent.svg @@ -0,0 +1,178 @@ + + + + + + +G + + +libevent::NativeEventBase + + +<<extern>> +NativeEventBase + ++ + dispatch() ++ + is_valid(): Bool ++ + loopexit() ++ + new(): NativeEventBase ++ + reinit(): Bool + + +libevent::NativeEvent + + +<<extern>> +NativeEvent + ++ + add() ++ + del() + + +libevent::NativeEvSignal + + +<<extern>> +NativeEvSignal + ++ + new(base: NativeEventBase, signal: Int, handler: EventCallback): NativeEvSignal + + +libevent::NativeEvSignal->libevent::NativeEvent + + + + +libevent::EventCallback + + +<<interface>> +EventCallback + ++ + callback(events: Int) + + +libevent::Connection + + +Connection + ++ + event_callback(events: Int): Bool ++ + force_close() ++ + read_callback(content: String) ++ + write_callback() ++ + write_file(path: String) + + +libevent::NativeBufferEvent + + +<<extern>> +NativeBufferEvent + ++ + enable(operation: Int) ++ + input_buffer(): InputNativeEvBuffer ++ + output_buffer(): OutputNativeEvBuffer ++ + read_buffer(buf: NativeEvBuffer): Int ++ + setcb(conn: Connection) ++ + socket(base: NativeEventBase, fd: Int, options: Int): NativeBufferEvent ++ + write(line: CString, length: Int): Int ++ + write_buffer(buf: NativeEvBuffer): Int ++ + write_byte(value: Int): Int + + +libevent::NativeEvBuffer + + +<<extern>> +NativeEvBuffer + ++ + length(): Int ++ + remove(buffer: CString, len: Int) + + +libevent::InputNativeEvBuffer + + +<<extern>> +InputNativeEvBuffer + ++ + drain(length: Int) + + +libevent::InputNativeEvBuffer->libevent::NativeEvBuffer + + + + +libevent::OutputNativeEvBuffer + + +<<extern>> +OutputNativeEvBuffer + ++ + add_file(fd: Int, offset: Int, length: Int): Bool + + +libevent::OutputNativeEvBuffer->libevent::NativeEvBuffer + + + + +libevent::ConnectionListener + + +<<extern>> +ConnectionListener + ++ + base(): NativeEventBase ++ + error_callback() + + +libevent::ConnectionFactory + + +ConnectionFactory + ++ + accept_connection(listener: ConnectionListener, fd: Int, addrin: Pointer, socklen: Int) ++ + bind_to(address: String, port: Int): nullable ConnectionListener ++ + spawn_connection(buffer_event: NativeBufferEvent, address: String): Connection + + + diff --git a/uml-linux.svg b/uml-linux.svg new file mode 100644 index 0000000000..ef77f076f0 --- /dev/null +++ b/uml-linux.svg @@ -0,0 +1,108 @@ + + + + + + +G + + +linux::audio + + + +audio ++ +Music ++ +PlayableAudio ++ +Sound + + +linux::linux + + + +linux ++ +App ++ +Sys ++ +TextAsset + + +linux::audio->linux::linux + + + + +linux::data_store + + + +data_store ++ +DataStore + + +linux::http_request + + + +http_request ++ +App ++ +Text + + +linux::ui + + + +ui ++ +App ++ +BackButton ++ +Button ++ +CheckBox ++ +CompositeControl ++ +Control ++ +HorizontalLayout ++ +Label ++ +Layout ++ +ListLayout ++ +Sys ++ +Text ++ +TextInput ++ +VerticalLayout ++ +View ++ +Window + + +linux::ui->linux::data_store + + + + + diff --git a/uml-logic.svg b/uml-logic.svg new file mode 100644 index 0000000000..690f935f92 --- /dev/null +++ b/uml-logic.svg @@ -0,0 +1,50 @@ + + + + + + +G + + +logic::lexpr + + + +lexpr ++ +CNF ++ +LAnd ++ +LExpr ++ +LFalse ++ +LNot ++ +LOr ++ +LTrue ++ +LVar ++ +Sys + + +logic::logic + + + +logic + + +logic::logic->logic::lexpr + + + + + diff --git a/uml-markdown.svg b/uml-markdown.svg new file mode 100644 index 0000000000..9fa581c9f1 --- /dev/null +++ b/uml-markdown.svg @@ -0,0 +1,197 @@ + + + + + + +G + + +markdown::decorators + + + +decorators ++ +InlineDecorator ++ +MdDecorator + + +markdown::markdown + + + +markdown ++ +Block ++ +BlockCode ++ +BlockFence ++ +BlockHeadline ++ +BlockList ++ +BlockListItem ++ +BlockNone ++ +BlockOrderedList ++ +BlockParagraph ++ +BlockQuote ++ +BlockRuler ++ +BlockUnorderedList ++ +BlockXML ++ +Decorator ++ +HTMLDecorator ++ +HeadLine ++ +Line ++ +LineBlockquote ++ +LineCode ++ +LineEmpty ++ +LineFence ++ +LineHR ++ +LineHeadline ++ +LineHeadline1 ++ +LineHeadline2 ++ +LineList ++ +LineOList ++ +LineOther ++ +LineUList ++ +LineXML ++ +LinkRef ++ +MDBlock ++ +MDLine ++ +MDLocation ++ +MarkdownProcessor ++ +String ++ +Text ++ +Token ++ +TokenCode ++ +TokenCodeDouble ++ +TokenCodeSingle ++ +TokenEm ++ +TokenEmStar ++ +TokenEmUnderscore ++ +TokenEntity ++ +TokenEscape ++ +TokenHTML ++ +TokenImage ++ +TokenLink ++ +TokenLinkOrImage ++ +TokenNone ++ +TokenStrike ++ +TokenStrong ++ +TokenStrongStar ++ +TokenStrongUnderscore + + +markdown::decorators->markdown::markdown + + + + +markdown::man + + + +man ++ +ManDecorator + + +markdown::man->markdown::markdown + + + + +markdown::nitmd + + + +nitmd ++ +Sys + + +markdown::nitmd->markdown::decorators + + + + +markdown::nitmd->markdown::man + + + + +markdown::wikilinks + + + +wikilinks ++ +Decorator ++ +MarkdownProcessor ++ +TokenWikiLink + + +markdown::wikilinks->markdown::markdown + + + + + diff --git a/uml-matrix.svg b/uml-matrix.svg new file mode 100644 index 0000000000..9df6155a04 --- /dev/null +++ b/uml-matrix.svg @@ -0,0 +1,40 @@ + + + + + + +G + + +matrix::matrix + + + +matrix ++ +Matrix ++ +MatrixCoordinate + + +matrix::projection + + + +projection ++ +Matrix ++ +Sys + + +matrix::projection->matrix::matrix + + + + + diff --git a/uml-mnit.svg b/uml-mnit.svg new file mode 100644 index 0000000000..3e525b29b5 --- /dev/null +++ b/uml-mnit.svg @@ -0,0 +1,173 @@ + + + + + + +G + + +mnit::InputEvent + + +<<interface>> +InputEvent + + +mnit::PointerEvent + + +<<interface>> +PointerEvent + ++ + depressed(): Bool ++ + +x +(): Float ++ + +y +(): Float + + +mnit::PointerEvent->mnit::InputEvent + + + + +mnit::MotionEvent + + +<<interface>> +MotionEvent + ++ + +down_pointer +(): nullable PointerEvent ++ + +just_went_down +(): Bool + + +mnit::MotionEvent->mnit::InputEvent + + + + +mnit::TouchEvent + + +<<interface>> +TouchEvent + ++ + +pressure +(): Float + + +mnit::TouchEvent->mnit::PointerEvent + + + + +mnit::KeyEvent + + +<<interface>> +KeyEvent + ++ + +code +(): Int ++ + +is_arrow_down +(): Bool ++ + +is_arrow_left +(): Bool ++ + +is_arrow_right +(): Bool ++ + +is_arrow_up +(): Bool ++ + is_up(): Bool ++ + +to_c +(): nullable Char + + +mnit::KeyEvent->mnit::InputEvent + + + + +mnit::MobileKeyEvent + + +<<interface>> +MobileKeyEvent + ++ + +is_back_key +(): Bool ++ + +is_home_key +(): Bool ++ + +is_menu_key +(): Bool ++ + +is_search_key +(): Bool + + +mnit::MobileKeyEvent->mnit::KeyEvent + + + + +mnit::SensorEvent + + +<<interface>> +SensorEvent + + +mnit::SensorEvent->mnit::InputEvent + + + + +mnit::QuitEvent + + +<<interface>> +QuitEvent + + +mnit::QuitEvent->mnit::InputEvent + + + + + diff --git a/uml-mongodb.svg b/uml-mongodb.svg new file mode 100644 index 0000000000..b3aa985ff8 --- /dev/null +++ b/uml-mongodb.svg @@ -0,0 +1,82 @@ + + + + + + +G + + +mongodb::mongodb + + + +mongodb ++ +JsonObject ++ +MongoClient ++ +MongoCollection ++ +MongoCursor ++ +MongoDb ++ +MongoError ++ +MongoObjectId + + +mongodb::native_mongodb + + + +native_mongodb ++ +BSONError ++ +BSONObjectId ++ +NativeBSON ++ +NativeCStringArray ++ +NativeMongoClient ++ +NativeMongoCollection ++ +NativeMongoCursor ++ +NativeMongoDb ++ +Sys + + +mongodb::mongodb->mongodb::native_mongodb + + + + +mongodb::queries + + + +queries ++ +MongoGroup ++ +MongoMatch ++ +MongoPipeline + + +mongodb::queries->mongodb::mongodb + + + + + diff --git a/uml-msgpack.svg b/uml-msgpack.svg new file mode 100644 index 0000000000..e905043ac3 --- /dev/null +++ b/uml-msgpack.svg @@ -0,0 +1,166 @@ + + + + + + +G + + +msgpack::ext + + + +ext ++ +Deserializer ++ +MsgPackExt + + +msgpack::msgpack + + + +msgpack + + +msgpack::serialization_read + + + +serialization_read ++ +Bytes ++ +Map ++ +MsgPackDeserializer ++ +Reader ++ +SimpleCollection + + +msgpack::msgpack->msgpack::serialization_read + + + + +msgpack::serialization_write + + + +serialization_write ++ +AttributeCounter ++ +Bool ++ +Byte ++ +Bytes ++ +CString ++ +Char ++ +Float ++ +Int ++ +Map ++ +MsgPackExt ++ +MsgPackSerializer ++ +Serializable ++ +SimpleCollection ++ +Text ++ +Writer + + +msgpack::msgpack->msgpack::serialization_write + + + + +msgpack::msgpack_to_json + + + +msgpack_to_json ++ +Sys + + +msgpack::read + + + +read ++ +Reader + + +msgpack::msgpack_to_json->msgpack::read + + + + +msgpack::read->msgpack::ext + + + + +msgpack::serialization_common + + + +serialization_common ++ +MsgPackEngine + + +msgpack::serialization_read->msgpack::read + + + + +msgpack::serialization_read->msgpack::serialization_common + + + + +msgpack::serialization_write->msgpack::ext + + + + +msgpack::serialization_write->msgpack::serialization_common + + + + +msgpack::write + + + +write ++ +Writer + + +msgpack::serialization_write->msgpack::write + + + + + diff --git a/uml-neo4j.svg b/uml-neo4j.svg new file mode 100644 index 0000000000..b04cf0723e --- /dev/null +++ b/uml-neo4j.svg @@ -0,0 +1,40 @@ + + + + + + +G + + +neo4j&gt; + +neo4j ++ +curl_json ++ +error ++ +neo4j + + +neo4j&gt;graph&gt; + +graph ++ +graph ++ +json_graph_store ++ +sequential_id + + +neo4j&gt;graph&gt;->neo4j&gt; + + + + + diff --git a/uml-nlp.svg b/uml-nlp.svg new file mode 100644 index 0000000000..cc3107de76 --- /dev/null +++ b/uml-nlp.svg @@ -0,0 +1,50 @@ + + + + + + +G + + +nlp::nlp + + + +nlp ++ +NLPFileIndex ++ +NLPIndex + + +nlp::stanford + + + +stanford ++ +NLPClient ++ +NLPDocument ++ +NLPJavaProcessor ++ +NLPProcessor ++ +NLPSentence ++ +NLPServer ++ +NLPToken + + +nlp::nlp->nlp::stanford + + + + + diff --git a/uml-opts.svg b/uml-opts.svg new file mode 100644 index 0000000000..24a96f4516 --- /dev/null +++ b/uml-opts.svg @@ -0,0 +1,184 @@ + + + + + + +G + + +opts::Option + + +<<abstract>> +Option + ++ + VALUE: nullable Object + ++ + add_aliases(names: String) ++ + init(help: String, default: VALUE, names: nullable Array[String]) ++ + init_opt(help: String, default: VALUE, names: nullable Array[String]) ++ + pretty(off: Int): String ++ + pretty_default(): String +# + read_param(opts: OptionContext, it: Iterator[String]) + + +opts::OptionText + + +OptionText + ++ + init(text: String) + + +opts::OptionText->opts::Option + + + + +opts::OptionBool + + +OptionBool + ++ + init(help: String, names: String) + + +opts::OptionBool->opts::Option + + + + +opts::OptionCount + + +OptionCount + ++ + init(help: String, names: String) + + +opts::OptionCount->opts::Option + + + + +opts::OptionParameter + + +<<abstract>> +OptionParameter + +# + +convert +(str: String): VALUE + + +opts::OptionParameter->opts::Option + + + + +opts::OptionString + + +OptionString + ++ + init(help: String, names: String) + + +opts::OptionString->opts::OptionParameter + + + + +opts::OptionEnum + + +OptionEnum + ++ + init(values: Array[String], help: String, default: Int, names: String) ++ + value_name(): String + + +opts::OptionEnum->opts::OptionParameter + + + + +opts::OptionInt + + +OptionInt + ++ + init(help: String, default: Int, names: String) + + +opts::OptionInt->opts::OptionParameter + + + + +opts::OptionFloat + + +OptionFloat + ++ + init(help: String, default: Float, names: String) + + +opts::OptionFloat->opts::OptionParameter + + + + +opts::OptionArray + + +OptionArray + ++ + init(help: String, names: String) + + +opts::OptionArray->opts::OptionParameter + + + + +opts::OptionContext + + +OptionContext + ++ + add_option(opts: Option) ++ + errors(): Array[String] ++ + parse(argv: nullable Collection[String]) +# + parse_intern(it: Iterator[String]) ++ + usage() + + + diff --git a/uml-posix.svg b/uml-posix.svg new file mode 100644 index 0000000000..6c66b45a8a --- /dev/null +++ b/uml-posix.svg @@ -0,0 +1,40 @@ + + + + + + +G + + +posix::ext + + + +ext ++ +Passwd + + +posix::posix + + + +posix ++ +Group ++ +Passwd ++ +Sys + + +posix::ext->posix::posix + + + + + diff --git a/uml-postgresql.svg b/uml-postgresql.svg new file mode 100644 index 0000000000..04f6179655 --- /dev/null +++ b/uml-postgresql.svg @@ -0,0 +1,44 @@ + + + + + + +G + + +postgresql::native_postgres + + + +native_postgres ++ +ConnStatusType ++ +ExecStatusType ++ +NativePGResult ++ +NativePostgres + + +postgresql::postgres + + + +postgres ++ +PGResult ++ +Postgres + + +postgresql::postgres->postgresql::native_postgres + + + + + diff --git a/uml-pthreads.svg b/uml-pthreads.svg new file mode 100644 index 0000000000..84b341c267 --- /dev/null +++ b/uml-pthreads.svg @@ -0,0 +1,118 @@ + + + + + + +G + + +pthreads::concurrent_collections + + + +concurrent_collections ++ +Array ++ +BlockingQueue ++ +Collection ++ +ConcurrentArray ++ +ConcurrentCollection ++ +ConcurrentList ++ +ConcurrentSequence ++ +ConcurrentSequenceRead ++ +List ++ +ReverseBlockingQueue ++ +Sequence ++ +SequenceRead + + +pthreads::pthreads + + + +pthreads ++ +AtomicInt ++ +Barrier ++ +MainThread ++ +Mutex ++ +PthreadCond ++ +Sys ++ +Thread + + +pthreads::concurrent_collections->pthreads::pthreads + + + + +pthreads::extra + + + +extra ++ +Sys ++ +Thread + + +pthreads::extra->pthreads::pthreads + + + + +pthreads::redef_collections + + + +redef_collections ++ +Array + + +pthreads::redef_collections->pthreads::pthreads + + + + +pthreads::threadpool + + + +threadpool ++ +JoinTask ++ +Task ++ +ThreadPool + + +pthreads::threadpool->pthreads::concurrent_collections + + + + + diff --git a/uml-sax.svg b/uml-sax.svg new file mode 100644 index 0000000000..38897c562f --- /dev/null +++ b/uml-sax.svg @@ -0,0 +1,80 @@ + + + + + + +G + + +sax&gt; + +sax ++ +attributes ++ +content_handler ++ +dtd_handler ++ +entity_resolver ++ +error_handler ++ +input_source ++ +sax ++ +sax_locator ++ +sax_parse_exception ++ +xml_filter ++ +xml_reader + + +sax&gt;ext&gt; + +ext ++ +decl_handler ++ +ext ++ +lexical_handler + + +sax&gt;ext&gt;->sax&gt; + + + + +sax&gt;helpers&gt; + +helpers ++ +attributes_impl ++ +helpers ++ +namespace_support ++ +sax_locator_impl ++ +test_attributes_impl ++ +test_namespace_support ++ +xml_filter_impl + + +sax&gt;helpers&gt;->sax&gt; + + + + + diff --git a/uml-saxophonit.svg b/uml-saxophonit.svg new file mode 100644 index 0000000000..a07804cb84 --- /dev/null +++ b/uml-saxophonit.svg @@ -0,0 +1,61 @@ + + + + + + +G + + +saxophonit::lexer + + + +lexer ++ +XophonLexer + + +saxophonit::reader_model + + + +reader_model ++ +XophonReaderModel + + +saxophonit::lexer->saxophonit::reader_model + + + + +saxophonit::saxophonit + + + +saxophonit ++ +XophonReader + + +saxophonit::saxophonit->saxophonit::lexer + + + + +saxophonit::testing + + + +testing ++ +SAXEventLogger ++ +SAXTestSuite + + + diff --git a/uml-scene2d.svg b/uml-scene2d.svg new file mode 100644 index 0000000000..c3840f8866 --- /dev/null +++ b/uml-scene2d.svg @@ -0,0 +1,92 @@ + + + + + + +G + + +scene2d::LiveObject + + +<<abstract>> +LiveObject + ++ + +draw +(view: View) ++ + update() + + +scene2d::Sprite + + +Sprite + ++ + angle_to(target: Sprite): Float ++ + bottom(): Int ++ + left(): Int ++ + overlaps(other: Sprite): Bool ++ + right(): Int ++ + set_velocity(angle: Float, maginude: Int) ++ + top(): Int ++ + velocity_angle(): Float + + +scene2d::Sprite->scene2d::LiveObject + + + + +scene2d::LiveGroup + + +LiveGroup[E: LiveObject] + ++ + gc() + + +scene2d::LiveGroup->scene2d::LiveObject + + + + +scene2d::Scene + + +Scene + + +scene2d::Scene->scene2d::LiveObject + + + + +scene2d::View + + +<<interface>> +View + ++ + +draw_sprite +(s: Sprite) + + + diff --git a/uml-sdl2.svg b/uml-sdl2.svg new file mode 100644 index 0000000000..2ade56327c --- /dev/null +++ b/uml-sdl2.svg @@ -0,0 +1,181 @@ + + + + + + +G + + +sdl2::all + + + +all + + +sdl2::image + + + +image ++ +IMG ++ +SDL ++ +SDLImgInitFlags ++ +SDLSurface + + +sdl2::all->sdl2::image + + + + +sdl2::events + + + +events ++ +SDLEvent ++ +SDLEventBuffer ++ +SDLKeyboardDownEvent ++ +SDLKeyboardEvent ++ +SDLKeyboardUpEvent ++ +SDLKeysym ++ +SDLMouseButtonDownEvent ++ +SDLMouseButtonEvent ++ +SDLMouseButtonUpEvent ++ +SDLMouseEvent ++ +SDLMouseMotionEvent ++ +SDLMouseWheelEvent ++ +SDLQuitEvent ++ +SDLWindowEvent + + +sdl2::sdl2_base + + + +sdl2_base ++ +Int ++ +SDL ++ +SDLColor ++ +SDLInitFlags ++ +SDLMessageBoxFlags ++ +SDLPoint ++ +SDLRect ++ +SDLRenderer ++ +SDLRendererFlags ++ +SDLRendererInfo ++ +SDLSurface ++ +SDLTexture ++ +SDLWindow ++ +SDLWindowFlags ++ +SDL_PixelFormat ++ +Sys + + +sdl2::events->sdl2::sdl2_base + + + + +sdl2::sdl2 + + + +sdl2 + + +sdl2::image->sdl2::sdl2 + + + + +sdl2::mixer + + + +mixer ++ +Mix ++ +MixChunk ++ +MixFormat ++ +MixInitFlags ++ +MixMusic ++ +Sys + + +sdl2::mixer->sdl2::sdl2_base + + + + +sdl2::sdl2->sdl2::events + + + + +sdl2::syswm + + + +syswm ++ +SDLSysWMInfo ++ +SDLWindow + + +sdl2::sdl2->sdl2::syswm + + + + +sdl2::syswm->sdl2::sdl2_base + + + + + diff --git a/uml-serialization.svg b/uml-serialization.svg new file mode 100644 index 0000000000..a29339f89a --- /dev/null +++ b/uml-serialization.svg @@ -0,0 +1,170 @@ + + + + + + +G + + +serialization::caching + + + +caching ++ +AsyncCache ++ +CachingDeserializer ++ +CachingSerializer ++ +DeserializerCache ++ +DuplexCache ++ +SerializerCache + + +serialization::engine_tools + + + +engine_tools ++ +Object ++ +StrictHashMap ++ +String ++ +Text + + +serialization::caching->serialization::engine_tools + + + + +serialization::serialization_core + + + +serialization_core ++ +AttributeError ++ +AttributeMissingError ++ +AttributeTypeError ++ +Bool ++ +Byte ++ +CString ++ +Char ++ +Couple ++ +Deserializer ++ +DirectSerializable ++ +Error ++ +Float ++ +Int ++ +Map ++ +MinHeap ++ +Ref ++ +Serializable ++ +Serializer ++ +SimpleCollection ++ +Text + + +serialization::engine_tools->serialization::serialization_core + + + + +serialization::inspect + + + +inspect ++ +Bool ++ +Byte ++ +CString ++ +Char ++ +Collection ++ +Float ++ +Int ++ +Map ++ +Serializable ++ +SimpleCollection ++ +Sys ++ +Text + + +serialization::inspect->serialization::caching + + + + +serialization::safe + + + +safe ++ +Deserializer ++ +SafeDeserializer ++ +Sys + + +serialization::serialization + + + +serialization + + +serialization::safe->serialization::serialization + + + + +serialization::serialization->serialization::inspect + + + + + diff --git a/uml-sexp.svg b/uml-sexp.svg new file mode 100644 index 0000000000..029a7c7933 --- /dev/null +++ b/uml-sexp.svg @@ -0,0 +1,87 @@ + + + + + + +G + + +sexp::SExpEntity + + +<<abstract>> +SExpEntity + + +sexp::SExp + + +SExp + ++ + pretty_to_s(): String + + +sexp::SExp->sexp::SExpEntity + + + + +sexp::SExpDQString + + +SExpDQString + + +sexp::SExpDQString->sexp::SExpEntity + + + + +sexp::SExpFloat + + +SExpFloat + + +sexp::SExpFloat->sexp::SExpEntity + + + + +sexp::SExpId + + +SExpId + + +sexp::SExpId->sexp::SExpEntity + + + + +sexp::SExpError + + +SExpError + + +sexp::SExpError->sexp::SExpEntity + + + + +sexp::SExpProcessor + + +SExpProcessor + ++ + parse_entity(): SExpEntity + + + diff --git a/uml-socket.svg b/uml-socket.svg new file mode 100644 index 0000000000..44bf7d7420 --- /dev/null +++ b/uml-socket.svg @@ -0,0 +1,82 @@ + + + + + + +G + + +socket::socket + + + +socket ++ +IOError ++ +Socket ++ +SocketAddress ++ +SocketObserver ++ +SocketSet ++ +TCPServer ++ +TCPSocket ++ +TCPStream ++ +UDPSocket + + +socket::socket_c + + + +socket_c ++ +HErrno ++ +NativeSocket ++ +NativeSocketAddrIn ++ +NativeSocketAddressFamilies ++ +NativeSocketHostent ++ +NativeSocketObserver ++ +NativeSocketOptLevels ++ +NativeSocketOptNames ++ +NativeSocketPollValues ++ +NativeSocketProtocolFamilies ++ +NativeSocketSet ++ +NativeSocketTypes ++ +NativeTimeval ++ +PollFD ++ +SocketAcceptResult ++ +Sys + + +socket::socket->socket::socket_c + + + + + diff --git a/uml-sqlite3.svg b/uml-sqlite3.svg new file mode 100644 index 0000000000..c5ca7a694b --- /dev/null +++ b/uml-sqlite3.svg @@ -0,0 +1,64 @@ + + + + + + +G + + +sqlite3::native_sqlite3 + + + +native_sqlite3 ++ +DataType ++ +NativeSqlite3 ++ +NativeStatement ++ +Sqlite3Code ++ +Sys + + +sqlite3::sqlite3 + + + +sqlite3 ++ +Blob ++ +Float ++ +Int ++ +Sqlite3DB ++ +Sqlite3Data ++ +Statement ++ +StatementEntry ++ +StatementIterator ++ +StatementRow ++ +String ++ +Text + + +sqlite3::sqlite3->sqlite3::native_sqlite3 + + + + + diff --git a/uml-template.svg b/uml-template.svg new file mode 100644 index 0000000000..b5c6e83010 --- /dev/null +++ b/uml-template.svg @@ -0,0 +1,38 @@ + + + + + + +G + + +template::macro + + + +macro ++ +String ++ +TemplateString + + +template::template + + + +template ++ +Template + + +template::macro->template::template + + + + + diff --git a/uml-trees.svg b/uml-trees.svg new file mode 100644 index 0000000000..5b80cdc2f9 --- /dev/null +++ b/uml-trees.svg @@ -0,0 +1,98 @@ + + + + + + +G + + +trees::abstract_tree + + + +abstract_tree ++ +TreeMap ++ +TreeNode + + +trees::bintree + + + +bintree ++ +BinTreeMap ++ +BinTreeNode + + +trees::bintree->trees::abstract_tree + + + + +trees::bktree + + + +bktree ++ +BKMatch ++ +BKTree + + +trees::bktree->trees::abstract_tree + + + + +trees::rbtree + + + +rbtree ++ +RBTreeMap ++ +RBTreeNode + + +trees::rbtree->trees::bintree + + + + +trees::trees + + + +trees + + +trees::trees->trees::rbtree + + + + +trees::trie + + + +trie ++ +Trie + + +trees::trie->trees::trees + + + + + diff --git a/uml-vsm.svg b/uml-vsm.svg new file mode 100644 index 0000000000..1a4c2838a4 --- /dev/null +++ b/uml-vsm.svg @@ -0,0 +1,48 @@ + + + + + + +G + + +vsm::bm25 + + + +bm25 ++ +VSMIndex + + +vsm::vsm + + + +vsm ++ +Document ++ +FileIndex ++ +IndexMatch ++ +IndexMatchSorter ++ +StringIndex ++ +VSMIndex ++ +Vector + + +vsm::bm25->vsm::vsm + + + + + diff --git a/uml-xdg_basedir.svg b/uml-xdg_basedir.svg new file mode 100644 index 0000000000..9eae00e022 --- /dev/null +++ b/uml-xdg_basedir.svg @@ -0,0 +1,38 @@ + + + + + + +G + + +xdg_basedir::show_basedir + + + +show_basedir ++ +Sys + + +xdg_basedir::xdg_basedir + + + +xdg_basedir ++ +Sys ++ +XdgBasedir + + +xdg_basedir::show_basedir->xdg_basedir::xdg_basedir + + + + +