md 0.3.0

md

Markdownのコードブロックを実行するツールです。

READMEに書かれたサンプルが動作するかどうかをCIなどで確かめることができます。

実行方法

dub run md -- README.md といった形式で実行できます。

この README.md も実行可能です。

機能概要

言語が d と指定されているコードブロックが実行されます。

以下のように複数のブロックがある場合、それらが結合されて実行されます。

1ブロック目

import std;

auto message = "Hello, " ~ "Markdown!";

2ブロック目

writeln(message); // Hello, Markdown!

除外設定

以下のように disabled と指定したコードブロックは実行されません。

~~~

~~~

実行されないブロック

throw new Exception("disabled");

名前指定

コードブロックに対して、以下のような名前を指定することで独立したスコープを与えることができます。 離れた位置に書かれていても、同じ名前を与えると1つのブロックとして結合されます。

~~~

~~~

import std;

auto buf = iota(10).array();
writeln(buf);

name 指定がない場合は main という名前として扱われます。

独立実行

1つのコードブロックを他のブロックと結合せず、独立して実行させるためには single という属性を付与します。

~~~

~~~

他のブロックと結合しない例

import std;

auto message = "single code block";
writeln(message);

既定のパッケージ参照

ライブラリのREADMEなどをサポートするため、実行時のカレントディレクトリがdubパッケージであった場合、自動的に dub プロジェクトとしての依存関係が追加されます。

たとえば、 dub.sdl と同じディレクトリにある本READMEの場合、内部で使っている commands.main を import することができます。

import commands.main;
import std.stdio;

writeln("current package: ", loadCurrentProjectName());

グローバル宣言

通常のコードブロックはサンプル用の記述を想定し、 void main() {} の中に書かれたものとして実行されます。（前後に void main() { と } が補われたソースが生成されます）

コードブロックを1つのソースファイルとして解釈させる場合、コードブロックに global という設定を追加します。これは single を指定した場合と同様、他のコードブロックとは結合されません。

~~~

~~~

1つのソースとして実行される例

import std;

void main()
{
    writeln("Hello, Markdown!");
}

その他

実行時の仕組み

tempディレクトリに .md ディレクトリを作り、dubのシングルファイル形式のソースを生成、 dub run --single md_xxx.md といったコマンドで実行します。

制限

UFCS

通常のコードブロックでは、 void main() {} で囲んだソースを生成します。 関数定義がグローバル関数ではないため、UFCSは動作しません

UFCSが解決されず動かない例

auto sum(R)(R range)
{
    import std.range : ElementType;

    alias E = ElementType!R;
    auto result = E(0);
    foreach (x; range)
    {
        result += x;
    }
    return result;
}

auto arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
auto result = arr.sum();

global設定を行い、main関数を適切に書くことで動作します。

UFCSのためglobal指定を追加した例

auto sum(R)(R range)
{
    import std.range : ElementType;

    alias E = ElementType!R;
    auto result = E(0);
    foreach (x; range)
    {
        result += x;
    }
    return result;
}

void main()
{
    auto arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    auto result = arr.sum();
}