Merge pull request #20 from dullin/rename-markdown-files

Rename markdown files extensions to .md from .mdwn

config.ini

@@ -3,7 +3,7 @@ wiki.name=Nitlanguage.org
 wiki.desc=a fun language for serious programming
 ; config
 wiki.out_dir=target/
-wiki.md_ext=mdwn
+wiki.md_ext=md
 wiki.sidebar=right
 wiki.sidebar.blocks[]=search
 wiki.sidebar.blocks[]=download

pages/manual/Makefile

@@ -1,2 +1,2 @@
-nitreference.pdf: *.mdwn
+nitreference.pdf: *.md
 	./makedoc.sh

pages/manual/makedoc.sh

@@ -1,16 +1,16 @@
 echo > blank
 cat \
-	syntax.mdwn blank\
-	basic_type.mdwn blank\
-	structure.mdwn blank\
-	variable.mdwn blank\
-	module.mdwn blank\
-	class.mdwn blank\
-	method.mdwn blank\
-	attribute.mdwn blank\
-	constructor.mdwn blank\
-	genericity.mdwn blank\
-	virtual_type.mdwn\
+	syntax.md blank\
+	basic_type.md blank\
+	structure.md blank\
+	variable.md blank\
+	module.md blank\
+	class.md blank\
+	method.md blank\
+	attribute.md blank\
+	constructor.md blank\
+	genericity.md blank\
+	virtual_type.md\
 	| sed -e '/\[\[!template/d' \
 	-e 's/\[\[\([^|]*\)|\([^]]*\)\]\]/\1 \\goto{\2}/g' \
        	-e 's/\[\[\([^]]*\)\]\]/\1 \\goto{\1}/g' \

pages/nep/automatic_constructors_revamp.md

@@ -0,0 +1,109 @@
+# Revamp of automatic constructors.
+
+* Status: Dicussion
+* Discussion: [#1800](https://github.com/nitlang/nit/issues/1800)
+* Implementation: todo
+
+## Summary of the previous proposal
+
+The previous proposition comes from #679, more than one year ago.
+It introduced *new-style* constructors where the semantic of the `new` is a specific 3-phase construction.
+
+For instance, with the following class `Foo`
+
+~~~nit
+class Foo
+   var i: Int
+end
+~~~
+
+the `new` semantic of `x = new Foo(1)` means
+
+~~~nit
+x = new Foo.intern # memory allocation and initialization of the default attributes
+x.i = 1 # Collected initializers (mostly attribute setters)
+x.init # Linearized call to anonymous init to finish the construction
+~~~
+
+The benefit of these approach is that the collection of the initializers can be done sanely in multiple inheritance.
+The drawback of the approach is that the whole magic is done in the `new` expression and that these automatic constructions, especially the signature of the `new`, are not exposed like other properties in the doc of the class (if exposed at all).
+
+## Proposal of the revamp
+
+This revamp tries to address these issues while keeping the benefits and being compatible with the existing code.
+The basic idea is to move the implicit sequence of code of the `new` expression into a genuine method of the class.
+Since each class possibly has its own specific sequence of code with its specific signature, these genuine methods will not be redefinition but introduction.
+The proposed name for these methods is `auto` and they will behave like named constructors.
+
+So, in the proposal, the `new Foo` is a shorthand for `new Foo.auto`, so a standard 2-phase construction with the named constructor `auto`, like the following:
+
+~~~nit
+x = new Foo.intern # memory allocation and init of default attributes
+x.auto(1) # call of the named constructor
+~~~
+
+The `auto` constructor is implicitly defined in the class, like if it was defined by the user:
+
+~~~nit
+# The implicit and free, constructor `auto` 
+init auto(i: Int) do
+   self.i = i 
+   self.init # Linearized call to the anonymous init to finish the construction
+end
+~~~
+
+Advantages on the revamp:
+
+* the default `new` has a simpler semantic with less hacks.
+* the *automatic* construction is exposed as an implicit named constructor `auto`, that behave and is documented like other named constructors.
+
+
+## Constructions and annotations
+
+The annotations `autoinit`, `noautoinit` and related keep their effects.
+The change is that instead of changing the *initializers* that are magically invoked with the `new`, they just change how the implicit `auto` named constructor is set up.
+This has the advantage that the effects of these annotations are limited to how the `auto` constructor is defined.
+
+* `noautoinit` on attributes: the setter is not collected in the body of `auto`
+* `autoinit` on methods: the method is collected in the body of `auto`
+* `autoinit` in the class: the `auto` constructor is made with the setters given in argument in order
+
+The last annotation (`autoinit` on classes) has therefore a simpler meaning since
+
+~~~nit
+class Bar
+  autoinit x, y, z
+  # ...
+end
+~~~
+
+Is equivalent to
+
+~~~nit
+class Bar
+   init auto(x: X, y: Y, z: Z) do
+      self.x = x
+      self.y = y
+      self.z = z
+      self.init
+   end
+end
+~~~
+
+## Manual named constructors
+
+Most of the time, manual named constructors require that a primitive constructor is called.
+In the previous proposal, the magic sequence of the `new` is also used when `init` is used as explicit method call inside a constructor.
+With the new proposal, `auto` should be called instead, but because of bootstrapping issues, the existing calls to `init` are interpreted as call to `auto` instead and an advice is issued.
+
+Manual named constructors tries to magically call a constructor if no such a call is present.
+The current way to determine what and how to call it use a complex heuristic to make existing code compatible.
+
+A in-depth review of the heuristic to rationalize the policy is required but is out of scope of the present proposal.
+
+
+## User-defined `auto`
+
+Since `auto` is compatible with standard manual named constructor, what append when the used define himself a constructor `named` auto?
+
+TODO

pages/nep/conditional_import.md

@@ -0,0 +1,105 @@
+# Conditional importation of modules
+
+The problem, independently identified by contributors, is to allow the variation of a module according to a specific platform. Eg sound on linux vs sound on android.
+
+* Status: Implemented
+* Discussion: <https://github.com/nitlang/nit/issues/1579>
+* Implementation: merged <https://github.com/nitlang/nit/pull/1580>
+
+## Goals of the proposal
+
+* use standard module importation and class refinement as the base mechanism
+* do not require additional description of rules (nor configuration file)
+* completely static and locally checkable
+* not specific to platform but generalized to any module
+* do not enforce a specific vendor/package responsibility but allow lib-based, platform-based and third-party based approaches (see below)
+* easy to implement (in the model, in the parser, etc)
+
+## Current Approach
+
+Currently, the solution is to develop parallel hierarchy of modules and make that the final program imports all required combination of bottom modules (eg app.nit).
+The issue with this approach is that the hierarchy of module become complex and error-prone to maintain, the second issue is that complex product line might be unnecessary non-pola to specify for a developer: "why I must import android::audio since my program already imports app::audio and is compiled with -m android?"
+
+## Specification
+
+* there is conditional importation rules: e.g. if all the modules m1, m2 are imported then automatically import m3
+* conditional importation rules can be declared (but not applied) by any modules
+* conditional importation rules are applied on clients that satisfy the conditions
+
+The following syntax is just a syntactic base for discussion.
+
+~~~
+module foo
+import bar is conditional baz
+~~~
+
+It declares a rule 'foo & baz -> bar'.
+It means that in a client module of both foo and baz (direct or indirect client), the client also imports (implicitly and automatically) the module  bar.
+
+~~~
+module a_client
+import foo
+import baz
+~~~
+
+Conditional importations are never imported directly by the module that declares them but are deferred to the clients.
+It means that a module who declares conditional importations is statically analysed (and possibly compiled) without taking in account the conditional importations nor the associated conditions.
+It also means that clients are statically analyzed (and possibly compiled) after having applied all the conditional importations of its imported modules.
+
+## Use  cases
+
+The proposal is compatible with various use cases
+
+### Library-side variations
+
+A library vendor can adapt it to different platform, for instance to provide specific implementations or API extensions.
+
+For instance, a vendor can provide library/library.nit and library/library_android.nit with the following content:
+
+~~~
+# A library with a generic API and portable implementation
+module library
+import library_android is conditional android
+~~~
+
+~~~
+# Additional services and specific implementation of library on android
+module library_android
+import library # because we refine it
+import android # because we rely on Android service and api to provide the additional things
+~~~
+
+### Platform-side variations
+
+In a symmetrical way, a platform vendor can choose to provide extensions and specific implementation to common libraries that will be automatically used on the platform.
+It could be used to redefine method with a functional (or a more efficient) implementation.
+
+~~~
+# general platform module to compile for android
+module android is platform
+import android_jvm is conditional jvm
+~~~
+
+~~~
+# special implementation to access the jvm on Android
+module android_jvm
+import android_base
+import jvm
+~~~
+
+### Third-party-side variations
+
+A last use case is when two libraries could be extended if used together but none of these provide a conditional importation of the other. In these case, a third-party vendor can provide a auto-glue library made of conditional importations.
+
+~~~
+# glue to partially implements libraries of app.nit for the emscripten platform
+module appjs
+import appjs_sound is conditional emscripten, app::sound
+import appjs_storage is conditional emscripten, app::storage
+~~~
+
+## Issues
+
+* What syntax
+* What about the visibility of the automatic imported modules
+* What about linearization rules of the automatic imported modules

pages/nep/index.md

@@ -0,0 +1,5 @@
+# Nit Enhancement Proposals
+
+* [[conditional_import]]
+* [[package_metadata]]
+* [[automatic_constructors_revamp]]