You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-289Lines changed: 3 additions & 289 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,299 +34,13 @@ Install the latest version of Parsley.Net nuget package with command below.
34
34
```
35
35
NuGet\Install-Package Parsley.Net
36
36
```
37
-
### ii. Implementation: Using Parsley.Net
38
-
#### <ins>Step 1<ins>. Initialise and use Parser class.
39
-
`Parser` is an implementation of `IParser` interface that provides sync and async methods for
40
-
- parsing content of a file by specifying the file path
41
-
- parsing an array of delimiter separated strings
42
-
- parsing a stream of delimiter separated strings
43
-
- parsing byte array of delimiter separated strings
37
+
### ii. Developer Guide
38
+
This comprehensive guide provides detailed information on Parsley, covering everything from basic concepts to advanced implementations and troubleshooting guidelines.
44
39
45
-
Please see below.
46
-
```
47
-
public interface IParser
48
-
{
49
-
/// <summary>
50
-
/// Parses a file at the specified filepath into an array of objects of type T.
51
-
/// </summary>
52
-
/// <typeparam name="T"></typeparam>
53
-
/// <param name="filepath"></param>
54
-
/// <returns></returns>
55
-
T[] Parse<T>(string filepath) where T : IFileLine, new();
56
-
57
-
/// <summary>
58
-
/// Parses an array of delimiter seperated strings into an array of objects of type T.
59
-
/// </summary>
60
-
/// <typeparam name="T"></typeparam>
61
-
/// <param name="lines"></param>
62
-
/// <returns></returns>
63
-
T[] Parse<T>(string[] lines) where T : IFileLine, new();
64
-
65
-
/// <summary>
66
-
/// Parses an array of bytes of delimiter separated records into an array of objects of type T.
67
-
/// </summary>
68
-
/// <typeparam name="T"></typeparam>
69
-
/// <param name="bytes"></param>
70
-
/// <returns></returns>
71
-
T[] Parse<T>(byte[] bytes, Encoding encoding = null) where T : IFileLine, new();
72
-
73
-
/// <summary>
74
-
/// Parses a stream of delimiter separated records into an array of objects of type T.
75
-
/// </summary>
76
-
/// <typeparam name="T"></typeparam>
77
-
/// <param name="stream"></param>
78
-
/// <returns></returns>
79
-
T[] Parse<T>(Stream stream, Encoding encoding = null) where T : IFileLine, new();
80
-
81
-
/// <summary>
82
-
/// Asynchronously parses a file at the specified filepath into an array of objects of type T.
83
-
/// </summary>
84
-
/// <typeparam name="T"></typeparam>
85
-
/// <param name="filepath"></param>
86
-
/// <returns></returns>
87
-
Task<T[]> ParseAsync<T>(string filepath) where T : IFileLine, new();
88
-
89
-
/// <summary>
90
-
/// Asynchronously parses an array of delimiter separated strings into an array of objects of type T.
91
-
/// </summary>
92
-
/// <typeparam name="T"></typeparam>
93
-
/// <param name="lines"></param>
94
-
/// <returns></returns>
95
-
Task<T[]> ParseAsync<T>(string[] lines) where T : IFileLine, new();
96
-
97
-
/// <summary>
98
-
/// Asynchronously parses an array of bytes of delimiter separated records into an array of objects of type T.
99
-
/// </summary>
100
-
/// <typeparam name="T"></typeparam>
101
-
/// <param name="bytes"></param>
102
-
/// <returns></returns>
103
-
Task<T[]> ParseAsync<T>(byte[] bytes, Encoding encoding = null) where T : IFileLine, new();
104
-
105
-
/// <summary>
106
-
/// Asynchronously parses a stream of delimiter separated strings into an array of objects of type T.
107
-
/// </summary>
108
-
/// <typeparam name="T"></typeparam>
109
-
/// <param name="stream"></param>
110
-
/// <returns></returns>
111
-
Task<T[]> ParseAsync<T>(Stream stream, Encoding encoding = null) where T : IFileLine, new();
112
-
}
113
-
```
114
-
To initialise `Parser` class you could do it manually or use dependency injection as shown below. The parser class has parameterised constructor that takes the delimiter character to initialise the instance. Default character is ',' (comma) to initialise the parser for a CSV file parsing.
115
-
116
-
Example of Manual Instantiation is
117
-
```
118
-
var parser = new Parser('|');
119
-
```
120
-
Example of IoC is
121
-
```
122
-
var services = new ServiceCollection();
123
-
124
-
services.AddTransient(typeof(IParser), c => new Parser(','));
var parser = serviceProvider.GetService<IParser>();
130
-
```
131
-
#### <ins>Step 2<ins>. Define the `IFileLine` implementation to parse a file record into a strongly typed line class.
132
-
Consider the file below. To parse a row into a C# class, you need to implement `IFileLine` interface. By doing this you create a strongly typed line representation for each row in the file.
133
-
```
134
-
|Mr|Jack Marias|Male|London, UK|
135
-
|Dr|Bony Stringer|Male|New Jersey, US|
136
-
|Mrs|Mary Ward|Female||
137
-
|Mr|Robert Webb|||
138
-
```
139
-
Let us create an employee class which will hold data for each row shown in the file above. The properties in the line class should match to the column index and data type of the fields of the row.
140
-
141
-
We use the column attribute to specify the column index and can optionally specify a default value for the associated column should it be be empty. As a rule of thumb, the number of properties with column attributes should match the number of columns in the row else the parser will throw an exception.
142
-
143
-
IFileLine interface provides
144
-
-`Index` property that holds the index of the parsed line relative to the whole file,
145
-
-`Errors` property which is an array representing any column parsing failures.
146
-
147
-
Please see below.
148
-
```
149
-
public interface IFileLine
150
-
{
151
-
public int Index { get; set; }
152
-
public IList<string> Errors { get; set; }
153
-
}
154
-
```
155
-
156
-
Example. `Employee` class
157
-
```
158
-
public class Employee : IFileLine
159
-
{
160
-
// Custom column properties
161
-
162
-
[Column(0)]
163
-
public string Title { get; set; }
164
-
[Column(1)]
165
-
public string Name { get; set; }
166
-
[Column(2)]
167
-
public EnumGender Sex { get; set; }
168
-
[Column(3, "London, UK")]
169
-
public string Location { get; set; }
170
-
171
-
// IFileLine Members
172
-
public int Index { get; set; }
173
-
public IList<string> Errors { get; set; }
174
-
}
175
-
```
176
-
Once you have created the line class it is as simple as calling one of the parser.Parse() methods below
177
-
178
-
i. By providing the path of the file to parse method.
179
-
```
180
-
var records = new Parser('|').Parse<Employee>("c://employees.txt");
181
-
```
182
-
ii. By providing the list of delimiter separated string values to parse method.
183
-
```
184
-
var lines = new[]
185
-
{
186
-
"|Mr|Jack Marias|Male|London, UK|",
187
-
"|Dr|Bony Stringer|Male|New Jersey, US|",
188
-
};
189
-
190
-
var records = new Parser('|').Parse<Employee>(lines);
191
-
```
192
-
#### <ins>Step 3<ins>. Advanced Parsing of data using nested types in the FileLine class.
193
-
194
-
**Case 1**: Write your own Custom Converter to parse data to a custom type.
195
-
196
-
You could implement advance parsing of data by implementing `TypeConverter` class. Suppose we have to change the Name string property in Employee class above to a `NameType` property shown below.
197
-
```
198
-
public class Employee : IFileLine
199
-
{
200
-
[Column(0)]
201
-
public string Title { get; set; }
202
-
[Column(1)]
203
-
public NameType Name { get; set; }
204
-
[Column(2)]
205
-
public EnumGender Sex { get; set; }
206
-
[Column(3, "London")]
207
-
public string Location { get; set; }
208
-
209
-
// IFileLine Members
210
-
public int Index { get; set; }
211
-
public IList<string> Errors { get; set; }
212
-
}
213
-
214
-
public class NameType
215
-
{
216
-
public string FirstName { get; set; }
217
-
public string Surname { get; set; }
218
-
}
219
-
```
220
-
221
-
In order to parse the string value (name) from delimiter separated record in the file correctly to custom type (NameType), you need to implement custom converter deriving from `TypeConverter` class.
222
-
223
-
Example - `NameConverter` class - converts name string value to NameType instance
224
-
```
225
-
public class NameConverter : TypeConverter
226
-
{
227
-
public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
0 commit comments