NRefactory/README

Overview of the NRefactory library:

Introductory documentation:
	 http://www.codeproject.com/Articles/408663/Using-NRefactory-for-analyzing-Csharp-code

How to download:
	- Binaries are provided as a NuGet package (http://nuget.org/packages/ICSharpCode.NRefactory)
	- Sourcecode is available on GitHub (https://github.com/icsharpcode/NRefactory)

How to compile:
	1. Get Mono.Cecil 0.9.6
		Get Cecil from https://github.com/jbevain/cecil ('git clone git://github.com/jbevain/cecil.git')
		or download Cecil from https://github.com/jbevain/cecil/ and unzip it into a directory named "cecil"
		next to the directory containing NRefactory.
	2. If you need the IKVM binding get it from https://github.com/mono/ikvm-fork and put it next to the NRefactory directory
		like Mono.Cecil - name it "ikvm".
	3. Open NRefactory.sln in your favorite .NET IDE and compile.

Features:
	- C# Parser
	- Abstract Syntax Tree with pattern-matching support
	- Semantic Analysis for C# (supports C# 5.0)
	- Code Completion for C#
	- Pretty Printer for C#
	- Lots of C# refactorings
	
Non-Features:
	- VB support is not implemented yet.
	- NRefactory cannot generate IL code -- it's a compiler frontend, not a full compiler

Dependencies:
	.NET 4.0
	Mono.Cecil 0.9.5
	NRefactory contains a modified copy of mcs (Mono's C# compiler) for the C# parser.


Namespace overview:

ICSharpCode.NRefactory assembly
	ICSharpCode.NRefactory.Editor:
		Interfaces that abstract from the text editor control used.
		Maybe future AvalonEdit versions will directly implement these interfaces, but you could also write adapters for other editors.
	
	ICSharpCode.NRefactory.TypeSystem:
		Contains a language-independent representation of the .NET type system.
		The type system is divided into two portions: unresolved and resolved type systems.
	
	ICSharpCode.NRefactory.TypeSystem.Implementation:
		Contains default implementations for the type system interfaces.
	
	ICSharpCode.NRefactory.Semantics:
		Contains classes (ResolveResults) used to represent the semantics of a language element.
		ResolveResults can have child results, thus forming semantic trees.
	
	ICSharpCode.NRefactory.Documentation:
		Classes for working with .xml documentation files.
		See "doc/XML Documentation.html" for details.
	
	ICSharpCode.NRefactory.PatternMatching:
		Provides classes for pattern matching over the C# and VB ASTs.
		See "doc/Pattern Matching.html" for details.
	
	ICSharpCode.NRefactory.Util:
		Various helper classes.


ICSharpCode.NRefactory.CSharp assembly
	ICSharpCode.NRefactory.CSharp:
		Abstract Syntax Tree for C#
	
	ICSharpCode.NRefactory.CSharp.Completion:
		Code completion (IntelliSense) for C#
	
	ICSharpCode.NRefactory.CSharp.Resolver:
		Semantic analysis for C# (resolving the meaning of expressions)
	
	ICSharpCode.NRefactory.CSharp.Analysis:
		Semantic analysis for C# (additional analysis functionality)
	
	ICSharpCode.NRefactory.CSharp.TypeSystem:
		Contains type system implementations specific to C#.
	
	ICSharpCode.NRefactory.CSharp.Refactoring:
		Infrastructure for refactorings; and several built-in refactorings.

ICSharpCode.NRefactory.VB assembly
	ICSharpCode.NRefactory.VB:
		Abstract Syntax Tree for VB

ICSharpCode.NRefactory.Xml assembly
	ICSharpCode.NRefactory.Xml:
		Error-tolerant XML parser. Supports incremental parsing.
		When tags don't match correctly, the parser uses a heuristic to guess the parse tree.
		The heuristic tries to minimize the edit distance from the erroneous document to
		the fixed document, and it also considers the indentation.



Null-Object pattern:
	The NRefactory library makes extensive use of the null object pattern.
	As a result, NullReferenceExceptions should be very rare when working with this library.
	In the type system, both ITypeReference and IType use SpecialType.UnknownType to represent
	unknown types.
	Unless the XML documentation says otherwise, no method or property returning a ITypeReference
	or IType will return null.
	
	Note that the null object pattern is not used for ITypeDefinition:
	IProjectContent.GetClass() returns null when a type is not found. Take care to abort your
	operation or substitute UnknownType instead of passing the null to code expecting an IType.
	
	The pattern also extends to the C# resolver, which always produces a ResolveResult, even in
	error cases. Use ResolveResult.IsError to detect resolver errors.
	Also note that many resolver errors still have a meaningful type attached, this allows code
	completion to work in the presence of minor semantic errors.
	
	The C# AST makes use of special null nodes when accessing the getter of an AST property and no
	child node with that role exists. Check the IsNull property to test whether a node is a null node.
	Null nodes are not considered to be part of the AST (e.g. they don't have a parent).

FAQ:
Q:  What is the difference between NRefactory and Roslyn?
	- NRefactory is ready and stable, Roslyn is only a CTP at this point of time.
	- NRefactory does not have VB support.
	- NRefactory cannot compile code to IL; it's not a full compiler, just a frontend.
	- NRefactory C# AST is mutable and supports pattern matching; Roslyn is immutable and does not have built-in pattern matching.

Q:	What is the difference between types and type definitions?

A:	Basically, a type (IType) is any type in the .NET type system:
		- an array (ArrayType)
		- a pointer (PointerType)
		- a managed reference (ByReferenceType)
		- a parameterized type (ParameterizedType, e.g. List<int>)
		- a type parameter (ITypeParameter, e.g. T)
		- or a type definition (ITypeDefiniton)
	
	Type definitions are only classes, structs, enums and delegates.
	Every type definition is a type, but not every type is a type definition.
	NRefactory's ITypeDefinition derives from IType, so you can directly use any type definition
	as a type.
	In the other direction, you could try to cast a type to ITypeDefinition, or you can call the
	GetDefinition() method. The GetDefinition() method will also return the underlying
	ITypeDefinition if given a parameterized type, so "List<int>".GetDefinition() is "List<T>".


Q:	What is the difference between types and type references?
	I've seen lots of duplicated classes (ArrayType vs. ArrayTypeReference, etc.)
	
A:	If you've previously used the .NET Reflection API, the concept of type references will be new
	to you.
	
	NRefactory has the concept of the "unresolved type system": every assembly/project is stored
	in unresolved form.
	It is possible to load some source code into a project which contains the type reference
	"int[]" without having to load mscorlib into NRefactory.
	So inside the entities stored for the project, the array type is only referenced using an
	ITypeReference.
	This interface has a single method:
	    interface ITypeReference {
	       IType Resolve(ITypeResolutionContext context);
	    }
	By calling the Resolve()-method, you will get back the actual ArrayType.
	
	Not only type references are split up this way; pretty much every class in the type system
	comes in unresolved and resolved forms.


Q:  What is a compilation (ICompilation)?

A:	A compilation serves as the root object of the resolved type system.
	It consists of a main assembly and multiple referenced assemblies,
	and may also contain additional information like compiler options.


Q:  What's in an ITypeResolveContext?

A:  An ITypeResolveContext is an environment for looking up namespaces and types.
	It consists of the current compilation, the current type definition,
	and language-specific implementations may add additional information (e.g. the list of usings).
	
	Generally, you cannot resolve a type reference without knowing what kind of context is expected.


Q:	How do I get the IType or ITypeReference for a primitive type such as string or int?
	
A:	To get an IType for a primitive type, use:
		compilation.FindType(KnownTypeCode.Int32)
	
	To get an ITypeReference, use:
		KnownTypeReference.Int32
	
	It is also possible to use a System.Type for retrieving a type:
	   compilation.FindType(typeof(int))
	or
	   typeof(int).ToTypeReference().


Q:	Is it thread-safe?

A:	This question is a bit difficult to answer.
	NRefactory was designed to be usable in a multi-threaded IDE.
	But of course, this does not mean that everything is thread-safe.
	
	First off, there's no hidden static state, so any two operations working on independent data
	can be executed concurrently.
	[Actually, sometimes static state is used for caches, but those uses are thread-safe.]
	TODO: what about the C# parser? gmcs is full of static state...
		-> this is being worked on; for the time being, NRefactory uses a global lock during parsing;
		   so it's thread-safe but slow.
	
	Some instance methods may use hidden instance state, so it is not safe to e.g. use an instance
	of the CSharp.Resolver.TypeInference class concurrently.
	Instead, you need to create an instance on every thread.
	
	The type system itself is thread-safe. Both the unresolved and the resolved type systems are
	immutable.
	
	When you add to an IProjectContent, the existing project content isn't modified,
	but a new project content is created instead. All implementations of the type system interfaces
	are either immutable or freezable.
	
	And on the resolved type system side, ICompilation is immutable as well.
	Internally, the resolved type system will resolve elements only on demand, but this is done
	in a thread-safe manner.


Q:	What format do the .ToString() methods use?

A:	They don't use any particular format. They're merely intended as a debugging aid.
	Currently .ToString() usually matches .ReflectionName, but that may change in the future.