diff --git a/README b/README deleted file mode 100644 index 5fcaf41b5..000000000 --- a/README +++ /dev/null @@ -1,230 +0,0 @@ -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 - 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) - - 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".GetDefinition() is "List". - - -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. diff --git a/README.md b/README.md new file mode 100644 index 000000000..d22493ffc --- /dev/null +++ b/README.md @@ -0,0 +1,193 @@ +# Overview of the NRefactory library + +### Introductory documentation +[Documentation on CodeProject](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, NRefactory Nuget). +- Sourcecode is available on [GitHub respository](https://github.com/icsharpcode/NRefactory, github repository of NRefactory). + +#### How to compile: +1. [Get Mono.Cecil](https://github.com/jbevain/cecil, 'git clone git://github.com/jbevain/cecil.git') +or [Download Cecil](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](https://github.com/mono/ikvm-fork, 'download 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?** +**A:** +- 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) +- 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.GetDefinition()` is `List`. + + +**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: + +```csharp + 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: +```csharp +compilation.FindType(KnownTypeCode.Int32) +``` +To get an ITypeReference, use: +```csharp +KnownTypeReference.Int32 +``` +It is also possible to use a System.Type for retrieving a type: +```csharp +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.