Skip to content

Contexts

Jump to bottom
kevin-montrose edited this page Jan 15, 2020 · 3 revisions
Clone this wiki locally

Contexts

Introduction

In addition to Options and IBoundConfiguration for controlling "high level" behavior during reading and writing, Cesil provides read and write specific contextual information at certain points during operation. Cesil also allows an arbitrary object to be attached at these points.

ReadContext

ReadContext is a readonly struct which exposes the following members:

  • Options - the current Options.
  • Mode - a ReadContextMode, one of:
    • ReadContextMode.ReadingColumn - when a particular column is being read.
    • ReadContextMode.ReadingRow - when a row is being read, but a particular column hasn't been decided on yet.
    • ReadContextMode.ConvertingColumn - when a particular column is being converted to a concrete type during dynamic deserialization.
    • ReadContextMode.ConvertingRow - when a particular row is being converted to a concrete type during dynamic deserialization.
  • RowNumber - the 0-based index of the current row being read.
  • HasColumn - true if Column is set, false if Column will throw
    • This is a convenience property for checking if Mode is one of ReadContextMode.ReadingColumn or ReadContextMode.ConvertingColumn
  • Column - returns the ColumnIdentifier for the current column, if available. Throws if not available.
    • Column will only be available if Mode is one of ReadContextMode.ReadingColumn or ReadContextMode.ConvertingColumn
  • Context - an object? provided when the IReader<TRow> or IAsyncReader<TRow> was created

ReadContexts are made available to all:

WriteContext

WriteContext is a readonly struct which exposes the following members:

  • Options - the current Options.
  • Mode - a WriteContextMode, one of:
    • WriteContextMode.DiscoveringColumns - when a dynamic writer is determining the columns in row.
    • WriteContextMode.DiscoveringCells - when a dynamic writer discovering cells in a row.
    • WriteContextMode.WritingColumn - when a writer of any kind is writing a single column.
  • HasRowNumber - true if RowNumber is set, false if RowNumber will throw.
    • This is a convenience property for checking if Mode is one of WriteContextMode.WritingColumn or WriteContextMode.DiscoveringCells.
  • RowNumber - returns the 0-based index of the row being written, if available. Throws if not available.
    • RowNumber will only be available if Mode is one of WriteContextMode.WritingColumn or WriteContextMode.DiscoveringCells.
  • Context - an object? provided when the IWriter<TRow> or IAsyncWriter<TRow> was created.

WriteContexts are made available to all:

Custom Contexts

As a convenience, Cesil allows an arbitrary object to be attached to all ReadContexts and WriteContexts. To do so, use the context parameter on any CreateXXX(...) method on IBoundConfiguration<TRow>.

Cesil treats any custom context as an opaque value, no attempt is made to synchronize access or manage lifetimes. If your context object requires special care when used, you will need to ensure proper care manually - this may require a custom ITypeDescriber or a wrapper around the context object.