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 groups 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... ... core...->core

Children

package ai

ai

Simple library for basic artificial intelligence algorithms
package android

android

Android platform support and APIs
package app

app

app.nit, a framework for portable applications
package base64

base64

Offers the base 64 encoding and decoding algorithms
package bcm2835

bcm2835

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

binary

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

bitmap

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

c

Structures and services for compatibility with the C language
package cartesian

cartesian

Memory-efficient Cartesian products on heterogeneous collections.
package cocoa

cocoa

Cocoa API, the development layer of OS X
package combinations

combinations

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

console

Defines some ANSI Terminal Control Escape Sequences.
package cpp

cpp

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

crapto

Cryptographic attacks and utilities.
package crypto

crypto

Mix of all things cryptography-related
package csv

csv

CSV document handling.
package curl

curl

Data transfer powered by the native curl library
package curses

curses

Curses for Nit
package date

date

Services to manipulate Date, Time and DateTime
package deriving

deriving

Automatic derivable implementations of standard basic methods.
package dot

dot

Dot rendering library
package emscripten

emscripten

Platform for the emscripten framework
package event_queue

event_queue

Register, update and discard events in a timeline.
package for_abuse

for_abuse

Service management through the for control structure.
package gamnit

gamnit

Portable game and multimedia framework for Nit
package gettext

gettext

Internationalization of Strings using gettext library
package glesv2

glesv2

OpenGL graphics rendering library for embedded systems, version 2.0
package gmp

gmp

Multi precision integer and rational number using gmp lib
package graph

graph

package gtk

gtk

GTK+ widgets and services
package hash_debug

hash_debug

Inject behavior analysis to hash-collections (HashMap, HashSet, etc.)
package html

html

HTML output facilities
package ini

ini

Handle ini config files.
package ios

ios

iOS support for app.nit
package jvm

jvm

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

libevent

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

logic

First-order logic data structure and algorithm.
package markdown2

markdown2

package matrix

matrix

Services for matrices of Float values
package md5

md5

Native MD5 digest implementation as Text::md5
package meta

meta

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

mnit

package msgpack

msgpack

MessagePack, an efficient binary serialization format
package nitcorn

nitcorn

Lightweight framework for Web applications development
package niti_runtime

niti_runtime

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

opts

Management of options on the command line
package ordered_tree

ordered_tree

Manipulation and presentation of ordered trees.
package perfect_hashing

perfect_hashing

Perfect hashing and perfect numbering
package pipeline

pipeline

Pipelined filters and operations on iterators.
package posix

posix

Services conforming to POSIX
package progression

progression

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

prompt

Basic services to display a prompt
package pthreads

pthreads

POSIX Threads support
package realtime

realtime

Services to keep time of the wall clock time
package ropes_debug

ropes_debug

Exposes methods for debugging ropes when needed.
package sax

sax

Core SAX APIs.
package scene2d

scene2d

Framework for 2D management of game elements
package sdl2

sdl2

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

sha1

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

signals

ANSI C signal handling
package socket

socket

Socket services
package sqlite3

sqlite3

Services to manipulate a Sqlite3 database
package standard

standard

Old module implicitly imported by the old compiler.
package symbol

symbol

Library for simple interning of strings
package template

template

Basic template system
package trees

trees

General module for tree data structures
package x11

x11

Services from the X11 library
package xdg_basedir

xdg_basedir

Services for using the XDG Base Directory specification

Descendants

package a_star

a_star

A* pathfinding in graphs
package actors

actors

Nit Actor Model
package array_debug

array_debug

Exposes functions to help profile or debug Arrays.
package bucketed_game

bucketed_game

Game framework with an emphasis on efficient event coordination
package config

config

Configuration options for nit tools and apps
package counter

counter

Simple numerical statistical analysis and presentation
package dom

dom

Easy XML DOM parser
package egl

egl

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

fca

Formal Concept Analysis
package gen_nit

gen_nit

Support to generate and otherwise manipulate Nit code
package geometry

geometry

Basic geometry data structures and services.
package github

github

Nit wrapper for Github API
package java

java

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

json

read and write JSON formatted text
package linux

linux

Implementation of app.nit for the Linux platform
package markdown

markdown

A markdown parser for Nit.
package mongodb

mongodb

MongoDB Nit Driver.
package more_collections

more_collections

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

mpd

Music Player Daemon client library
package mpi

mpi

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

neo4j

Neo4j connector through its JSON REST API using curl.
package nitcc_runtime

nitcc_runtime

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

nlp

Nit wrapper for Stanford CoreNLP
package noise

noise

Noise generators PerlinNoise and InterpolatedNoise
package parser_base

parser_base

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

performance_analysis

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

popcorn

Popcorn
package poset

poset

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

privileges

Process privileges management utilities
package readline

readline

GNU readline library wrapper
package rubix

rubix

Rubix-cube modelization library
package saxophonit

saxophonit

A SAX 2 parser in Nit.
package sendmail

sendmail

Send emails using the sendmail program
package serialization

serialization

Abstract serialization services
package sexp

sexp

S-Expression parsing facilities
package text_stat

text_stat

Injects stat-calculating functionalities to Text and its variants
package vsm

vsm

Vector Space Model
package websocket

websocket

Adds support for a websocket connection in Nit