NEPLg2 Standard Library

error: 診断しんだんの値あたいモデルをまとめるライブラリ

目的もくてき:

stdlib 全体ぜんたいで共通きょうつうに使つかう Diag / Diags / Outcome / StdErrorKind を定義ていぎします。
Result<T, E> の軽量けいりょうな失敗しっぱい制御せいぎょと、Diag による構造化こうぞうか診断しんだんを分離ぶんりします。

実装じっそう:

Diag は kind/message/span/notes/help/source を持もつ struct です。
Diags は Vec<Diag> を包つつむ struct とし、順序じゅんじょ付づきで複数ふくすうの診断しんだんを保持ほじします。
Outcome<T, E> は result と diags を持もち、値あたいの成否せいひと診断しんだんを別軸べつじくで運はこびます。

注意ちゅうい:

ここは表示ひょうじのためのライブラリではなく、診断しんだん値あたいの定義ていぎを担にないます。
Result<T, Diag> は通常つうじょうのライブラリ API で、Outcome<T, E> は compiler や JSON/HTML 処理しょりのような richer な処理しょりで使つかうことを想定そうていします。
StdErrorKind は軽量けいりょうな失敗しっぱい分類ぶんるいであり、Diag.kind が持もつ詳細しょうさい情報じょうほうを置おき換かえるものではありません。

計算量けいさんりょう:

Diag / DiagKind / Span / Outcome の構築こうちくは O(1) です。
Diags の push はならし O(1)、最悪さいあく O(n)（再確保さいかくほを含ふくむ）です。

DiagLevel: 診断しんだんの大分類だいぶんるい

目的もくてき:

log/info/warn/error の 4 段階だんかいで報告ほうこくの重おもさを表あらわします。

注意ちゅうい:

これは Result の Ok/Err とは別軸べつじくです。

計算量けいさんりょう:

O(1)

StdErrorKind: stdlib 全体ぜんたいで共有きょうゆうする軽量けいりょうな失敗しっぱい分類ぶんるい

目的もくてき:

Result<T, E> の E として使つかう標準ひょうじゅんの error kind を定義ていぎします。
stdlib 横断おうだんで大おおまかな失敗しっぱい要因よういんを揃そろえて扱あつかえるようにします。

注意ちゅうい:

詳細しょうさいな背景はいけいや位置いちは Diag 側がわで補おぎないます。

計算量けいさんりょう:

O(1)

Span: 診断しんだん位置いち

目的もくてき:

file/start/end の 3 要素ようそで位置いち情報じょうほうを保持ほじします。

注意ちゅうい:

file_id の意味いみづけは呼よび出だし側がわが定義ていぎします。

計算量けいさんりょう:

O(1)

DiagKind: 診断しんだんの分類ぶんるい

目的もくてき:

共通きょうつうの重大度じゅうだいどと stdlib 共通きょうつうの error kind、さらに任意にんいの local kind を束たばねます。

注意ちゅうい:

std_error と local_kind はどちらか片方かたほうだけでも構かまいません。
階層かいそう識別子しきべつしの言語げんご機能きのうが入はいるまでは、local_kind は str として扱あつかいます。

計算量けいさんりょう:

O(1)

Diag: 単一たんいつの診断しんだん

目的もくてき:

診断しんだん 1 件けんぶんの分類ぶんるい・本文ほんぶん・補足ほそく情報じょうほうをまとめます。

実装じっそう:

notes と help は Vec<str> で保持ほじします。
source は由来ゆらいの記述きじゅつを指さす任意にんいの文字列もじれつです。

注意ちゅうい:

Diag は表示ひょうじそのものではなく、構造化こうぞうかされた診断しんだん値あたいです。

計算量けいさんりょう:

構築こうちくは O(1) です。

Diags: 複数ふくすうの診断しんだんを順序じゅんじょ付づきで保持ほじする struct

目的もくてき:

Diag の列れつを単たんなる Vec<Diag> として露出ろしゅつせず、診断群しんだんぐんとして扱あつかいます。

実装じっそう:

items に Vec<Diag> を保持ほじします。

計算量けいさんりょう:

構築こうちくは O(1) です。

Outcome: Result と Diags を同時どうじに運はこぶ struct

目的もくてき:

compiler や source code を伴ともなう richer な処理しょりで、値あたいの成否せいひと診断しんだんを一緒いっしょに返かえします。

注意ちゅうい:

通常つうじょうの stdlib API では Result で十分じゅうぶんなことが多く、Outcome は限定的げんていてきに使つかいます。
diags は Option<Diags> とし、必要ひつようなときだけ持もたせます。

計算量けいさんりょう:

構築こうちくは O(1) です。

diag_kind_new: DiagKind を構築こうちくする
std_error_kind: StdErrorKind を持もつ error 診断しんだん分類ぶんるいを作つくる
log_kind: local kind 付つきの log 分類ぶんるいを作つくる
info_kind: local kind 付つきの info 分類ぶんるいを作つくる
warn_kind: local kind 付つきの warn 分類ぶんるいを作つくる
diag_new: 診断しんだん 1 件けんを構築こうちくする
diag_log: log 診断しんだんを作つくる
diag_info: info 診断しんだんを作つくる
diag_warn: warn 診断しんだんを作つくる
diag_error: StdErrorKind 付つき error 診断しんだんを作つくる
diag_with_span: 位置いち情報じょうほうを付与ふよする
diag_with_source: 由来ゆらい情報じょうほうを付与ふよする
diag_add_note: note を 1 件けん追加ついかする
diag_add_help: help を 1 件けん追加ついかする
diag_level: 重大度じゅうだいどを取とり出だす
diag_std_error_kind: StdErrorKind を取とり出だす
diag_std_error_kind_str: StdErrorKind の文字列もじれつ名めいを取とり出だす
diag_err: Diag を Result::Err に包つつむ
diag_out_of_memory: 確保かくほ失敗しっぱいを表あらわす error 診断しんだんを作つくる
diag_empty_collection: 空からコレクション操作そうさの error 診断しんだんを作つくる
diag_capacity_exceeded: 容量ようりょう超過ちょうかの error 診断しんだんを作つくる
diag_key_not_found: 欠落けつらく key の error 診断しんだんを作つくる
diags_new: 空からの Diags を作つくる
diags_one: Diag 1 件けんから Diags を作つくる
diags_push: Diags に Diag を 1 件けん追加ついかする
diags_len: 診断しんだん件数けんすうを返かえす
diags_has_errors: error level の診断しんだんを 1 件けんでも含ふくむか判定はんていする
outcome_ok: 診断しんだんなしの成功せいこう結果けっかを作つくる
outcome_err: 診断しんだんなしの失敗しっぱい結果けっかを作つくる
outcome_with_diags: 診断しんだん群ぐんを付与ふよする
result_to_outcome: Result を診断しんだんなし Outcome に昇格しょうかくする
into_outcome: Result を Outcome に昇格しょうかくする共通きょうつう入口いりぐち

目的もくてき

Result と Outcome を同おなじ helper 名めいで扱あつかい、呼よび出だし側がわが必要ひつような時点じてんで Outcome に揃そろえられるようにします。

使用例しようれい

TEST

#entry main
#target std
#import "std/test" as *
#import "alloc/diag/error" as *
fn main <()*>i32> ():
    let o <Outcome<i32, StdErrorKind>> into_outcome Result::Ok<i32, StdErrorKind> 7;
    assert outcome_is_ok o;
    0

実装じっそう

result_to_outcome をそのまま呼よび、診断しんだん群ぐんなしの Outcome を返かえします。

注意ちゅうい

Result 側がわに診断しんだん群ぐんはないため、昇格しょうかくしても diags は none です。

計算量けいさんりょう

時間じかん: O(1)
空間くうかん: O(1)

into_outcome: そのまま Outcome を返かえす

目的もくてき

すでに Outcome を持もっている値あたいも Result と同おなじ helper 名めいで扱あつかえるようにします。

実装じっそう

入力にゅうりょくをそのまま返かえします。

注意ちゅうい

diags の有無うむは保持ほじされます。

計算量けいさんりょう

時間じかん: O(1)
空間くうかん: O(1)

result_like_result: Result をそのまま読よみ出だす

目的もくてき

Result / Outcome を共通きょうつう helper で扱あつかうとき、成否せいひの軸じくだけを同おなじ名前なまえで取とり出だせるようにします。

実装じっそう

入力にゅうりょくの Result をそのまま返かえします。

計算量けいさんりょう

時間じかん: O(1)
空間くうかん: O(1)

result_like_result: Outcome 内部ないぶの Result を読よみ出だす

目的もくてき

Outcome 内部ないぶの result field を Result と同おなじ名前なまえで取とり出だせるようにします。

実装じっそう

outcome_result を呼よびます。

計算量けいさんりょう

時間じかん: O(1)
空間くうかん: O(1)

result_like_is_ok: Result の成功せいこうを判定はんていする
result_like_is_ok: Outcome の成功せいこうを判定はんていする
result_like_is_err: Result の失敗しっぱいを判定はんていする
result_like_is_err: Outcome の失敗しっぱいを判定はんていする
outcome_result: Outcome 内部ないぶの Result を取とり出だす

目的もくてき:

Outcome を受うけ取とった呼よび出だし側がわが、診断しんだん群ぐんとは別べつに成否せいひだけを確認かくにんできるようにします。
Result と Outcome を共通きょうつう helper で扱あつかうときの読よみ取とり入口いりぐちとして使つかいます。

使用例しようれい:
neplg2:test

#entry main
#target std
#import "std/test" as *
#import "alloc/diag/error" as *
fn main <()*>i32> ():
    let o <Outcome<i32, StdErrorKind>> outcome_ok<i32, StdErrorKind> 42;
    match outcome_result o:
        Result::Ok v:
            assert_eq_i32 42 v;
        Result::Err _e:
            test_fail "expected ok";
    0

実装じっそう:

struct field result をそのまま返かえします。

注意ちゅうい:

diags は返かえさないので、診断しんだん群ぐんも見みたい場合ばあいは outcome_diags_or_empty を併用へいようします。

計算量けいさんりょう:

時間じかん: O(1)
空間くうかん: O(1)

outcome_is_ok: Outcome.result が Ok か判定はんていする

目的もくてき:

値あたいの成否せいひだけを短みじかく読よみ取とりたい場面ばめんで、match を省はぶいて使つかえるようにします。

実装じっそう:

outcome_result o を match し、Result::Ok なら true を返かえします。

注意ちゅうい:

diags に warning や error が含ふくまれていても、result が Ok なら true です。
診断しんだん群ぐんの重大度じゅうだいどは outcome_has_errors で別途べっとに確認かくにんします。

計算量けいさんりょう:

時間じかん: O(1)
空間くうかん: O(1)

outcome_is_err: Outcome.result が Err か判定はんていする

目的もくてき:

軽量けいりょうな失敗しっぱい制御せいぎょだけを見みたい場面ばめんで、Result の Err かどうかを即座そくざに調しらべられるようにします。

実装じっそう:

outcome_is_ok の否定ひていを返かえします。

注意ちゅうい:

Outcome の診断しんだん群ぐんとは独立どくりつです。

計算量けいさんりょう:

時間じかん: O(1)
空間くうかん: O(1)

outcome_diags_or_empty: Outcome の診断しんだん群ぐんを空からなら空からの Diags に置おき換かえて返かえす

目的もくてき:

Outcome を使つかう側がわが Option<Diags> をそのつど match せず、一貫いっかんして Diags として扱あつかえるようにします。

実装じっそう:

some ならそのまま返かえし、none なら diags_new を作つくります。

注意ちゅうい:

none のときは空から Diags を新規しんき確保かくほします。

計算量けいさんりょう:

時間じかん: O(1)
空間くうかん: O(1)

outcome_has_errors: Outcome の診断しんだん群ぐんに error level が含ふくまれるか判定はんていする

目的もくてき:

compiler や richer な parser が Outcome.result とは別べつに、診断しんだん群ぐんの重大度じゅうだいどで処理しょり継続けいぞくを判断はんだんするときに使つかいます。

実装じっそう:

diags が none なら false、some なら diags_has_errors を呼よびます。

注意ちゅうい:

Result::Err であっても diags が空からなら false を返かえします。
Outcome.result の成否せいひと DiagLevel::Error は別軸べつじくです。

計算量けいさんりょう:

時間じかん: O(n)
空間くうかん: O(n)（再帰さいきぶん）

std_error_kind_str: StdErrorKind を文字列もじれつへ変換へんかんする
diag_level_str: DiagLevel を文字列もじれつへ変換へんかんする