ChartFileDataSourceBase

ClassChartGuruChartGuru

public abstract class ChartFileDataSourceBase : ChartDataSourceBase, IChartGuruElementDataSource, IChartDataSource

Common base for every data source that parses a text payload (CSV, JSON, Google Sheets export, an HTTP body, …) into a ChartGuru.ChartTabularData, then maps it through a ChartGuru.ChartDataMapping to produce ChartGuru.IChartMarks.

Subclasses provide just two things:

1. A way to obtain the raw text — synchronously (`ChartGuru.ChartFileDataSourceBase.LoadText`) or asynchronously (`ChartGuru.ChartFileDataSourceBase.LoadTextAsync(System.Threading.CancellationToken)`);
2. A parser that converts that text into a [ChartGuru.ChartTabularData](/tools/chartguru/api/chartguru-charttabulardata/) (`ChartGuru.ChartFileDataSourceBase.ParseToTabular(System.String)`).

The base class handles mapping suggestion (when `ChartGuru.ChartFileDataSourceBase.AutoMapping` is on), snapshot caching, the diff fast-path (SetValues when shape is unchanged, otherwise SetData), async refresh with `ChartGuru.ChartFileDataSourceBase.Refresh` / `ChartGuru.ChartFileDataSourceBase.RefreshAsync(System.Threading.CancellationToken)`, and forwarding to the UI Toolkit pipeline via BuildMarksForChartType.

Fields

_mapping

protected ChartDataMapping _mapping

Returns

ChartGuru.ChartDataMapping

_autoMapping

protected bool _autoMapping

Returns

System.Boolean

_applyOnEnable

protected bool _applyOnEnable

Returns

System.Boolean

_snapshot

protected ChartTabularData _snapshot

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

Returns

ChartGuru.ChartTabularData

_appliedMapping

protected ChartDataMapping _appliedMapping

Mapping snapshot that was last applied — used by the diff fast-path.

Returns

ChartGuru.ChartDataMapping

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 UnityEngine.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 ChartGuru.ChartTabularData. Implemented per source (CSV vs JSON).

Parameters

Name	Type
rawText	System.String

Returns

ChartGuru.ChartTabularData

LoadPayloadAsync(CancellationToken)

protected virtual Task<ChartFileDataSourceBase.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.ChartFileDataSourceBase.ChartTextPayload}

ParsePayloadToTabular(ChartTextPayload)

protected virtual ChartTabularData ParsePayloadToTabular(ChartFileDataSourceBase.ChartTextPayload payload)

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

Parameters

Name	Type
payload	ChartGuru.ChartFileDataSourceBase.ChartTextPayload

Returns

ChartGuru.ChartTabularData

Refresh()

public virtual void Refresh()

Drive a synchronous load → parse → push cycle. Equivalent to ChartGuru.ChartFileDataSourceBase.ApplyData; provided as a more discoverable alias.

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

ApplyData()

public override void ApplyData()

Synchronous ChartGuru.ChartFileDataSourceBase.ApplyData override. Loads the text, parses it, and pushes the result to all resolved target charts. Errors are caught and logged so a single misconfigured source does not break a whole scene.

BuildMarksForChartType(ChartType, ChartAuthoringStyleOptions)

public override List<IChartMark> BuildMarksForChartType(ChartType chartType, ChartAuthoringStyleOptions style)

UI Toolkit / runtime-pull entry point. Returns marks shaped for chartType from the cached snapshot. If the snapshot is empty, a fresh load+parse is attempted (best-effort).

Parameters

Name	Type
chartType	ChartGuru.ChartType
style	ChartGuru.ChartAuthoringStyleOptions

Returns

System.Collections.Generic.List{ChartGuru.IChartMark}

ApplyParsed(ChartTabularData)

protected void ApplyParsed(ChartTabularData parsed)

Push a freshly parsed dataset to every resolved chart. Updates existing marks in place when the shape is identical to the previous push, otherwise replaces the mark set with SetData.

Parameters

Name	Type
parsed	ChartGuru.ChartTabularData

PromoteSnapshot(ChartTabularData)

protected void PromoteSnapshot(ChartTabularData parsed)

Cache parsed and (if ChartGuru.ChartFileDataSourceBase.AutoMapping is on and Y columns are empty) populate the mapping from the suggester.

Parameters

Name	Type
parsed	ChartGuru.ChartTabularData

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

ChartFileDataSourceBase()

protected ChartFileDataSourceBase()

Properties

Mapping

public ChartDataMapping Mapping { get; set; }

Inspector-editable mapping. Subclasses and inspectors mutate via this property.

Returns

ChartGuru.ChartDataMapping

AutoMapping

public bool AutoMapping { get; set; }

When true, missing Y columns will be auto-suggested on parse.

Returns

System.Boolean

CurrentData

public ChartTabularData CurrentData { get; }

The last parsed snapshot. May be null.

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}

RefreshVersion

public int RefreshVersion { get; }

Monotonic version incremented after each successfully applied refresh.

Returns

System.Int32

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 ChartGuru.ChartFileDataSourceBase.RefreshState changes.

Returns

System.Action{ChartGuru.ChartDataRefreshState}