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

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.

Object

Object - The root of the class hierarchy.

Each other class implicitly specializes Object, therefore the services of Object are inherited by every other class and are usable on each value, including primitive types like integers (Int), strings (String) and arrays (Array).

Note that Object, not Object, is the root of the type hierarchy since the special value null is not considered as an instance of Object.

Equality

== - Have self and other the same value?

assert 1 + 1 == 2
assert not 1 == "1"
assert 1.to_s == "1"

The exact meaning of same value is left to the subclasses. Implicitly, the default implementation, is is_same_instance.

The laws of == are the following:

  • reflexivity a.is_same_instance(b) implies a == b
  • symmetry: (a == b) == (b == a)
  • transitivity: (a == b) and (b == c) implies (a == c)

== might not be constant on some objects overtime because of their evolution.

var a = [1]
var b = [1]
var c = [1,2]
assert a == b and not a == c
a.add 2
assert not a == b and a == c

Lastly, == is highly linked with hash and a specific redefinition of == should usually be associated with a specific redefinition of hash.

ENSURE result implies self.hash == other.hash

!= - Have self and other different values?

!= is equivalent with not ==.

hash - The hash code of the object.

The hash code is used in many data-structures and algorithms to identify objects that might be equal. Therefore, the precise semantic of hash is highly linked with the semantic of == and the only law of hash is that a == b implies a.hash == b.hash.

assert (1+1).hash == 2.hash
assert 1.to_s.hash == "1".hash

hash (like ==) might not be constant on some objects over time because of their evolution.

var a = [1]
var b = [1]
var c = [1,2]
assert a.hash == b.hash
a.add 2
assert a.hash == c.hash

A specific redefinition of == should usually be associated with a specific redefinition of hash. Note that, unfortunately, a correct definition of hash that is lawful with == is sometime tricky and a cause of bugs.

Without redefinition, hash is based on the object_id of the instance.

is_same_instance - Return true if self and other are the same instance (i.e. same identity).

var a = new Buffer
var b = a
var c = new Buffer
assert a.is_same_instance(b)
assert not a.is_same_instance(c)
assert a == c

Obviously, the identity of an object is preserved even if the object is mutated.

var x = [1]
var y = x
x.add 2
assert x.is_same_instance(y)

Unless specific code, you should use == instead of is_same_instance because most of the time is it the semantic (and user-defined) comparison that make sense.

Moreover, relying on is_same_instance on objects you do not control might have unexpected effects when libraries reuse objects or intern them.

object_id - An internal hash code for the object based on its identity.

Unless specific code, you should not use this method but use hash instead.

As its name hints it, the internal hash code, is used internally to provide a hash value. It is also used by the inspect method to loosely identify objects and helps debugging.

var a = "Hello"
var b = a
assert a.object_id == b.object_id

The specific details of the internal hash code it let to the specific engine. The rules are the following:

  • The object_id MUST be invariant for the whole life of the object.
  • Two living instances of the same classes SHOULD NOT share the same object_id.
  • Two instances of different classes MIGHT share the same object_id.
  • The object_id of a garbage-collected instance MIGHT be reused by new instances.
  • The object_id of an object MIGHT be non constant across different executions.

For instance, the nitc compiler uses the address of the object in memory as its object_id.

TODO rename in something like internal_hash_code

Debuging

output - Display self on stdout (debug only).

This method MUST not be used by programs, it is here for debugging only and can be removed without any notice.

TODO: rename to avoid blocking a good identifier like output.

output_class_name - Display class name on stdout (debug only).

This method MUST not be used by programs, it is here for debugging only and can be removed without any notice.

TODO: rename to avoid blocking a good identifier like output.

is_same_type - Return true if self and other have the same dynamic type.

assert 1.is_same_type(2)
assert "Hello".is_same_type("World")
assert not "Hello".is_same_type(2)

The method returns false if the dynamic type of other is a subtype of the dynamic type of self (or the other way around).

Unless specific code, you should not use this method because it is inconsistent with the fact that a subclass can be used in lieu of a superclass.

Sys

Sys - The main class of the program.

Sys is a singleton class, its only instance is accessible from everywhere with sys.

Because of this, methods that should be accessible from everywhere, like print or exit, are defined in Sys. Moreover, unless there is an ambiguity with self, the receiver of a call to these methods is implicitly sys. Basically it means that the two following instructions are equivalent.

print "Hello World"
sys.print "Hello World"

Methods Implicitly Defined in Sys

Sys is the class where are defined top-level methods, i.e. those defined outside of any class like in a procedural language. Basically it means that

redef class Sys
   fun foo do print "hello"
end

is equivalent with

fun foo print "hello"

As a corollary, in a top-level method, self (the current receiver) is always sys.

Program Execution

main - The main method of a program.

In a module, the instructions defined outside any classes or methods (usually called the main of the module) is an implicit definition of this main method. Basically it means that the following program

print "Hello World"

is equivalent with

redef class Sys
   redef fun main do
      print "Hello World"
   end
end

run - The entry point for the execution of the whole program.

When a program starts, the following implicit sequence of instructions is executed

sys = new Sys
sys.run

Whereas the job of the run method is just to execute main.

The only reason of the existence of run is to allow modules to refine it and inject specific work before or after the main part.

Other

  • Bool - Native Booleans.
  • Byte - Native bytes.
  • Char - Native characters.
  • Cloneable - Something that can be cloned
  • Comparable - The ancestor of class where objects are in a total order.
  • Discrete - Discrete total orders.
  • Float - Native floating point numbers.
  • Int - Native integer numbers.
  • Numeric - A numeric value supporting mathematical operations
  • Object - The root of the class hierarchy.
  • Pointer - Pointer classes are used to manipulate extern C structures.
  • Sys - The main class of the program.
  • Task - Task with a main method to be implemented by subclasses

Core Collections

collection - This module define several collection classes.

String and Text manipulation

text - All the classes and methods related to the manipulation of text entities

All subgroups and modules

module bitset

core :: bitset

Services to handle BitSet
module bytes

core :: bytes

Services for byte streams and arrays
group codecs

core > codecs

Group module for all codec-related manipulations
group collection

core > collection

This module define several collection classes.
module core

core :: core

Standard classes and methods used by default by Nit programs and libraries.
module environ

core :: environ

Access to the environment variables of the process
module error

core :: error

Standard error-management infrastructure.
module exec

core :: exec

Invocation and management of operating system sub-processes.
module file

core :: file

File manipulations (create, read, write, etc.)
module fixed_ints

core :: fixed_ints

Basic integers of fixed-precision
module gc

core :: gc

Access to the Nit internal garbage collection mechanism
module kernel

core :: kernel

Most basic classes and methods.
module math

core :: math

Mathematical operations
module numeric

core :: numeric

Advanced services for Numeric types
module protocol

core :: protocol

module queue

core :: queue

Queuing data structures and wrappers
module re

core :: re

Regular expression support for all services based on Pattern
module stream

core :: stream

Input and output streams of characters
group text

core > text

All the classes and methods related to the manipulation of text entities
module time

core :: time

Management of time and dates
package_diagram core\> core core\>text\> text core\>->core\>text\> core\>collection\> collection core\>->core\>collection\> core\>codecs\> codecs core\>->core\>codecs\> core core core\>text\>->core core\>collection\>->core core\>codecs\>->core\>text\> core\>codecs\>->core ...core ... ...core->core core\>... ... core\>...->core\>

Parents

group codecs

core > codecs

Group module for all codec-related manipulations
group collection

core > collection

This module define several collection classes.
group text

core > text

All the classes and methods related to the manipulation of text entities

Children

group ai

ai

Simple library for basic artificial intelligence algorithms
group android

android

Android platform support and APIs
group app

app

app.nit, a framework for portable applications
group base64

base64

Offers the base 64 encoding and decoding algorithms
group bcm2835

bcm2835

Services to control the bcm2835 chipset used in the Raspberry Pi
group binary

binary

Read and write binary data with any Reader and Writer
group bitmap

bitmap

The Bitmap class represents a 24-bit bitmap image. An instance can be constructed
group c

c

Structures and services for compatibility with the C language
group cartesian

cartesian

Memory-efficient Cartesian products on heterogeneous collections.
group cocoa

cocoa

Cocoa API, the development layer of OS X
group codecs

core > codecs

Group module for all codec-related manipulations
group collection

core > collection

This module define several collection classes.
group combinations

combinations

Memory-efficient Cartesian products, combinations and permutation on collections.
group console

console

Defines some ANSI Terminal Control Escape Sequences.
group cpp

cpp

Services for compatibility with C++ code and libraries
group crapto

crapto

Cryptographic attacks and utilities.
group crypto

crypto

Mix of all things cryptography-related
group csv

csv

CSV document handling.
group curl

curl

Data transfer powered by the native curl library
group curses

curses

Curses for Nit
group date

date

Services to manipulate Date, Time and DateTime
group deriving

deriving

Automatic derivable implementations of standard basic methods.
group dot

dot

Dot rendering library
group emscripten

emscripten

Platform for the emscripten framework
group event_queue

event_queue

Register, update and discard events in a timeline.
group ext

sax > ext

Interfaces to optional SAX2 handlers.
group for_abuse

for_abuse

Service management through the for control structure.
group functional

functional

Nit functional types and Iterator API
group gamnit

gamnit

Portable game and multimedia framework for Nit
group gettext

gettext

Internationalization of Strings using gettext library
group gmp

gmp

Multi precision integer and rational number using gmp lib
group graph

graph

group hash_debug

hash_debug

Inject behavior analysis to hash-collections (HashMap, HashSet, etc.)
group helpers

sax > helpers

Contains "helper" classes, including support for bootstrapping SAX-based applications.
group html

html

HTML output facilities
group ini

ini

ini - Read and write INI configuration files
group ios

ios

iOS support for app.nit
group jvm

jvm

Java Virtual Machine invocation API and others services from the JNI C API
group libevent

libevent

Low-level wrapper around the libevent library to manage events on file descriptors
group logic

logic

First-order logic data structure and algorithm.
group matrix

matrix

Services for matrices of Float values
group md5

md5

Native MD5 digest implementation as Text::md5
group meta

meta

Simple user-defined meta-level to manipulate types of instances as object.
group mnit

mnit

group msgpack

msgpack

MessagePack, an efficient binary serialization format
group nitcorn

nitcorn

Lightweight framework for Web applications development
group niti_runtime

niti_runtime

Runtime library to loop around the main program for each line in file-name arguments
group opts

opts

Management of options on the command line
group ordered_tree

ordered_tree

Manipulation and presentation of ordered trees.
group perfect_hashing

perfect_hashing

Perfect hashing and perfect numbering
group pipeline

pipeline

Pipelined filters and operations on iterators.
group posix

posix

Services conforming to POSIX
group progression

progression

Event-based interface to track the progression of an operation.
group prompt

prompt

Basic services to display a prompt
group pthreads

pthreads

POSIX Threads support
group realtime

realtime

Services to keep time of the wall clock time
group ropes_debug

ropes_debug

Exposes methods for debugging ropes when needed.
group sax

sax

Core SAX APIs.
group scene2d

scene2d

Framework for 2D management of game elements
group sdl2

sdl2

This is a low-level wrapper of the SDL 2.0 library (as sdl2) and SDL_image 2.0 (as sdl2::image).
group sha1

sha1

Provides methods to compute the SHA1 hash of a String
group signals

signals

ANSI C signal handling
group socket

socket

Socket services
group sqlite3

sqlite3

Services to manipulate a Sqlite3 database
group standard

standard

Old module implicitly imported by the old compiler.
group symbol

symbol

Library for simple interning of strings
group template

template

Basic template system
group text

core > text

All the classes and methods related to the manipulation of text entities
group trees

trees

General module for tree data structures
group v3_4

gtk > v3_4

group x11

x11

Services from the X11 library
group xdg_basedir

xdg_basedir

Services for using the XDG Base Directory specification

Descendants

group a_star

a_star

A* pathfinding in graphs
group actors

actors

Nit Actor Model
group agent_simulation

actors > examples > agent_simulation

a "Framework" to make Multi-Agent Simulations in Nit
group array_debug

array_debug

Exposes functions to help profile or debug Arrays.
group bucketed_game

bucketed_game

Game framework with an emphasis on efficient event coordination
group bundle

android > bundle

A mapping class of String to various value types used by the
group config

config

Configuration options for nit tools and apps
group counter

counter

Simple numerical statistical analysis and presentation
group depth

gamnit > depth

gamnit depth, a framework to create portable 3D games in Nit.
group dom

dom

Easy XML DOM parser
group egl

egl

Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system.
group examples

ai > examples

group examples

nlp > examples

group examples

app > examples

group examples

dom > examples

group examples

ios > examples

group examples

vsm > examples

group examples

dot > examples

group fannkuchredux

actors > examples > fannkuchredux

Example implemented from "The computer Language Benchmarks Game" - Fannkuch-Redux
group fca

fca

Formal Concept Analysis
group flat

gamnit > flat

Simple API for 2D games, built around Sprite and App::update
group gen_nit

gen_nit

Support to generate and otherwise manipulate Nit code
group geometry

geometry

Basic geometry data structures and services.
group github

github

Nit wrapper for Github API
group glesv2

glesv2

OpenGL graphics rendering library for embedded systems, version 2.0
group graph

neo4j > graph

Provides an interface for services on a Neo4j graphs.
group gtk

gtk

GTK+ widgets and services
group intent

android > intent

Services allowing to launch activities and start/stop services using
group java

java

Supporting services for the FFI with Java and to access Java libraries
group json

json

read and write JSON formatted text
group linux

linux

Implementation of app.nit for the Linux platform
group logger

logger

A simple logger for Nit
group mandelbrot

actors > examples > mandelbrot

Example implemented from "The computer Language Benchmarks Game" - Mandelbrot
group markdown

markdown

A markdown parser for Nit.
group mongodb

mongodb

MongoDB Nit Driver.
group more_collections

more_collections

Highly specific, but useful, collections-related classes.
group mpd

mpd

Music Player Daemon client library
group mpi

mpi

Implementation of the Message Passing Interface protocol by wrapping OpenMPI
group neo4j

neo4j

Neo4j connector through its JSON REST API using curl.
group network

gamnit > network

Easy client/server logic for games and simple distributed applications
group nitcc_runtime

nitcc_runtime

Runtime library required by parsers and lexers generated by nitcc
group nlp

nlp

Nit wrapper for Stanford CoreNLP
group noise

noise

Noise generators PerlinNoise and InterpolatedNoise
group notification

android > notification

Services to show notification in the Android status bar
group parser_base

parser_base

Simple base for hand-made parsers of all kinds
group performance_analysis

performance_analysis

Services to gather information on the performance of events by categories
group popcorn

popcorn

Popcorn
group poset

poset

Pre order sets and partial order set (ie hierarchies)
group privileges

privileges

Process privileges management utilities
group readline

readline

GNU readline library wrapper
group rubix

rubix

Rubix-cube modelization library
group saxophonit

saxophonit

A SAX 2 parser in Nit.
group sendmail

sendmail

Send emails using the sendmail program
group serialization

serialization

Abstract serialization services
group service

android > service

Android service support for app.nit centered around the class Service
group sexp

sexp

S-Expression parsing facilities
group shared_preferences

android > shared_preferences

Services allowing to save and load datas to internal android device
group simple

actors > examples > simple

A very simple example of the actor model
group src

sdl2 > examples > minimal > src

group src

mpi > examples > src

group src

nitcorn > examples > src

group src

android > examples > src

group text_stat

text_stat

Injects stat-calculating functionalities to Text and its variants
group ui

android > ui

Views and services to use the Android native user interface
group ui

ios > ui

Implementation of app::ui for iOS
group virtual_gamepad

gamnit > virtual_gamepad

Virtual gamepad mapped to keyboard keys for quick and dirty mobile support
group vsm

vsm

Vector Space Model
group websocket

websocket

Adds support for a websocket connection in Nit