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..c0844ee8c --- /dev/null +++ b/README.md @@ -0,0 +1,223 @@ +#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.