ChartFileDataSource

ClassChartGuruChartGuru

public abstract class ChartFileDataSource : ChartDataSource

Common base for data sources that parse a text payload (CSV, JSON, a Google Sheets export, an HTTP body) into a ChartTabularData and publish it as a typed ChartDataFrame. Subclasses provide the raw text (ChartFileDataSource.LoadText() or ChartFileDataSource.LoadTextAsync(CancellationToken)) and a parser (ChartFileDataSource.ParseToTabular(string)). The base owns the refresh model: synchronous ChartFileDataSource.Refresh(), single-flight latest-request-wins ChartFileDataSource.RefreshAsync(CancellationToken) with parsing on a worker thread, and publishing on the Unity thread. Hosts map the published columns with their definition's layers.

Fields

_dateFormat

protected string _dateFormat

Returns

System.String

_dateCulture

protected string _dateCulture

Returns

System.String

_numberCulture

protected string _numberCulture

Returns

System.String

_maxRows

protected int _maxRows

Returns

System.Int32

_applyOnEnable

protected bool _applyOnEnable

Returns

System.Boolean

_snapshot

protected ChartTabularData _snapshot

The most recently parsed dataset. null until the first refresh.

Returns

ChartGuru.ChartTabularData

Methods

LoadText()

protected abstract string LoadText()

Subclasses override to obtain the raw text payload synchronously. Return an empty string to signal "no data".

Returns

System.String

LoadTextAsync(CancellationToken)

protected virtual Task<string> LoadTextAsync(CancellationToken ct)

Async variant. The default implementation snapshots the source text on the Unity thread because a source may read a TextAsset. Subclasses with a true async pipeline should override.

Parameters

Name	Type
ct	System.Threading.CancellationToken

Returns

System.Threading.Tasks.Task{System.String}

ParseToTabular(string)

protected abstract ChartTabularData ParseToTabular(string rawText)

Convert raw text to a ChartTabularData. Implemented per source (CSV vs JSON).

Parameters

Name	Type
rawText	System.String

Returns

ChartGuru.ChartTabularData

LoadPayloadAsync(CancellationToken)

protected virtual Task<ChartFileDataSource.ChartTextPayload> LoadPayloadAsync(CancellationToken ct)

Loads one immutable response payload. Network sources can attach response metadata here.

Parameters

Name	Type
ct	System.Threading.CancellationToken

Returns

System.Threading.Tasks.Task{ChartGuru.ChartFileDataSource.ChartTextPayload}

ParsePayloadToTabular(ChartTextPayload)

protected virtual ChartTabularData ParsePayloadToTabular(ChartFileDataSource.ChartTextPayload payload)

Parses one response payload without relying on mutable shared response state.

Parameters

Name	Type
payload	ChartGuru.ChartFileDataSource.ChartTextPayload

Returns

ChartGuru.ChartTabularData

RefreshAsync(CancellationToken)

public virtual Task RefreshAsync(CancellationToken ct = default)

Async single-flight refresh. Starting a newer refresh cancels the previous request, and only the latest generation may update the snapshot or charts. Parsing runs on a worker while all Unity object mutation is marshalled to the Unity thread captured by this component's lifecycle.

Parameters

Name	Type
ct	System.Threading.CancellationToken

Returns

System.Threading.Tasks.Task

Refresh()

public override void Refresh()

Loads, parses and publishes synchronously, canceling any refresh still in flight.

ApplyParsed(ChartTabularData)

protected void ApplyParsed(ChartTabularData parsed)

Converts the parsed table into a typed frame and publishes it to bound hosts.

Parameters

Name	Type
parsed	ChartGuru.ChartTabularData

ResolveNumberCulture()

protected CultureInfo ResolveNumberCulture()

The culture CSV cells write numbers in, or null to read them automatically; pass it to CsvParseOptions.NumberCulture.

Returns

System.Globalization.CultureInfo

QueueRefresh(CancellationToken)

protected void QueueRefresh(CancellationToken ct = default)

Starts an observed fire-and-forget refresh for lifecycle and polling callers.

Parameters

Name	Type
ct	System.Threading.CancellationToken

OnRefreshSucceeded()

protected virtual void OnRefreshSucceeded()

Called on the Unity thread after a successful refresh.

PrepareParsedForApply(ChartTabularData)

protected virtual void PrepareParsedForApply(ChartTabularData parsed)

Applies source-specific mapping changes on the Unity thread before data is promoted.

Parameters

Name	Type
parsed	ChartGuru.ChartTabularData

OnRefreshFailed(Exception)

protected virtual void OnRefreshFailed(Exception exception)

Called on the Unity thread after a failed refresh.

Parameters

Name	Type
exception	System.Exception

Constructors

ChartFileDataSource()

protected ChartFileDataSource()

Properties

DateFormat

public string DateFormat { get; set; }

DateTime.ParseExact format for date columns; empty detects common formats.

Returns

System.String

DateCulture

public string DateCulture { get; set; }

Culture name used to parse dates; empty is invariant.

Returns

System.String

NumberCulture

public string NumberCulture { get; set; }

Culture name whose number format CSV cells use, such as de-DE; empty reads invariant numbers with automatic decimal-comma detection. JSON numbers are always invariant.

Returns

System.String

MaxRows

public int MaxRows { get; set; }

Maximum number of rows read; 0 reads every row.

Returns

System.Int32

CurrentData

public ChartTabularData CurrentData { get; }

The latest parsed table, for previews and column pickers.

Returns

ChartGuru.ChartTabularData

RefreshState

public ChartDataRefreshState RefreshState { get; }

Current refresh lifecycle state.

Returns

ChartGuru.ChartDataRefreshState

IsRefreshing

public bool IsRefreshing { get; }

True while a refresh is loading, parsing, or applying data.

Returns

System.Boolean

LastRefreshError

public string LastRefreshError { get; }

Sanitized message from the most recent failed refresh.

Returns

System.String

LastRefreshUtc

public DateTime? LastRefreshUtc { get; }

UTC completion time of the most recent successful refresh.

Returns

System.Nullable{System.DateTime}

AutoApplyInEditMode

protected virtual bool AutoApplyInEditMode { get; }

Whether this source should populate an edit-mode preview when enabled.

Returns

System.Boolean

Events

RefreshStateChanged

public event Action<ChartDataRefreshState> RefreshStateChanged

Raised on the Unity thread whenever ChartFileDataSource.RefreshState changes.

Returns

System.Action{ChartGuru.ChartDataRefreshState}