WikiChree.COM 新規   編集   添付   管理  



トップ   編集 編集〔GUI〕 差分 履歴 添付 複製 名前変更 リロード   新規 一覧 検索 最終更新   ヘルプ   最終更新のRSS   ログイン
Pkript/API の変更点 
#author("2026-08-31T22:18:52+09:00","default:guide","guide")
#author("2026-09-04T00:06:05+09:00","default:mcp","bot-mcp")
* Pkript/API [#lb31b8d1]

組み込み関数とメソッドのリファレンスです。
組み込み関数とオブジェクトのリファレンス。詳細は各ページへ。

** 個別ページ [#j0fe3348]
- [[Pkript/API/グローバル関数]]: htmlsc, String, Number, Boolean, func_get_args, PHPエイリアス
#contents

** ページ一覧 [#pages]

- [[Pkript/API/グローバル関数]]: htmlsc, String, Number, Boolean, parseInt, parseFloat, isNaN, isFinite, NaN, Infinity, func_get_args, PHPエイリアス
- [[Pkript/API/wiki]]: exists, link, convert, source, pages, write, append, token, canWrite, time, isFrozen, uri, redirect
- [[Pkript/API/data]]: get, set, has, remove, keys, canWrite
- [[Pkript/API/url]]: encode, decode
- [[Pkript/API/date]]: now, format
- [[Pkript/API/JSON]]: stringify, parse
- [[Pkript/API/console]]: log, warn, error
- [[Pkript/API/html]]: escape, br, strip
- [[Pkript/API/Math]]: floor, ceil, round, abs, min, max, random
- [[Pkript/API/Object]]: keys, values, has
- [[Pkript/API/Array]]: length, push/pop, shift/unshift, map, filter, find, reduce, sort, ...
- [[Pkript/API/String]]: length, indexOf, includes, replace, split, substring, padStart, spanWhile, ...
- [[Pkript/API/Math]]: floor, ceil, round, trunc, abs, sign, min, max, random, sqrt, pow, hypot, exp, log, 三角関数, PI, E
- [[Pkript/API/Object]]: keys, values, entries, has, assign, fromEntries
- [[Pkript/API/Array]]: length, push/pop, shift/unshift, at, map, filter, find, reduce, sort, flat, splice ほか
- [[Pkript/API/String]]: length, indexOf, includes, replace, split, substring, padStart, charCodeAt, spanWhile ほか
- [[Pkript/API/RegExp]]: test, exec, source, flags, global
- [[Pkript/API/Number]]: toFixed, toString
- [[Pkript/API/Number]]: toFixed, toPrecision, toString, valueOf

** 目次 [#y1ecbee7]
#contents
** 概要 [#summary]

** グローバル関数 [#mbdaee9b]
PHPの関数は呼べない。使えるのは以下のオブジェクトと、グローバルに置かれた少数の関数だけ。

|~関数|~説明|h
|htmlsc(str)|HTMLエスケープ|
|String(val)|文字列に変換|
|Number(val)|数値に変換|
|Boolean(val)|真偽値に変換|
|func_get_args()|引数配列を取得|
|func_num_args()|引数の個数を取得|
|func_get_arg(n)|n番目の引数を取得|
|is_page(page)|wiki.exists(page) の別名|
|make_pagelink(page, [label])|wiki.link(page, label) の別名|
|convert_html(text)|wiki.convert(text) の別名|
|strip_bracket(str)|wiki.stripBracket(str) の別名|
|encode(str) / decode(str)|wiki.encode / decode の別名|
|get_source(page)|wiki.source(page) の別名|
|get_existpages([prefix])|wiki.pages(prefix) の別名|
|get_filetime(page)|wiki.time(page) の別名|
|is_freeze(page)|wiki.isFrozen(page) の別名|
|format_date(t, [paren])|date.format(t, paren) の別名|
|~分類|~入り口|~できること|h
|Wikiデータ|wiki|ページの読み書き、存在確認、リンクとURI生成、Wiki記法の変換|
|永続データ|data|リクエストをまたぐキーと値の保存|
|時刻|date|現在時刻の取得と書式整形|
|変換|JSON, url, html|JSONの相互変換、パーセントエンコード、HTMLエスケープ|
|デバッグ|console|PKRIPT_DEBUG が有効なときだけ出力されるログ|
|計算|Math, Number|数値計算と数値の文字列化|
|データ操作|Array, String, Object, RegExp|値そのものが持つメソッド|

#highlight{{
function plugin_recent_convert(e) {
    const pages = wiki.pages("Blog/");
    const sorted = pages.slice().sort((a, b) => wiki.time(b) - wiki.time(a));
    return "<ul>" + sorted.map((p) => "<li>" + wiki.link(p) + "</li>").join("") + "</ul>";
}
}}

** wiki [#xf1f26e7]
書き込み系（wiki.write, wiki.append, data.set, wiki.redirect）は action かつ POST、さらにトークンと信頼度を要求する。読み出し系に制限はない。

Wikiのデータ操作APIです。
** 関連 [#related]

|~メソッド|~説明|h
|wiki.exists(page)|ページの存在確認|
|wiki.link(page, [label])|ページへのリンクHTML生成|
|wiki.convert(text)|WikiテキストをHTMLに変換|
|wiki.source(page)|ページのWikiソースを取得|
|wiki.pages([prefix])|ページ名一覧を配列で取得|
|wiki.stripBracket(str)|ページ名を囲む二重角括弧 &#91;&#91; &#93;&#93; を除去|
|wiki.encode(str)|ページ名を16進ファイル名表現に変換|
|wiki.decode(str)|16進表現からページ名に変換|
|wiki.write(page, text)|ページを上書き保存（action専用）|
|wiki.append(page, text)|ページ末尾に追記保存（action専用）|
|wiki.token()|CSRF対策トークンを取得|
|wiki.canWrite(page)|そのページを書き込める状態か（下記）|
|wiki.time(page)|ページの最終更新時刻（存在しない・読めないページは 0）|
|wiki.isFrozen(page)|ページが凍結されているか確認（存在しないページは false）|
|wiki.uri([page], [absolute])|Wiki自身 / ページのURI（既定は相対、第2引数 true で絶対URI）|
|wiki.redirect(page)|リクエストをそこで終わらせ、page に移動する（action + POST のみ）|

*** canWrite が見るもの [#canwrite]

wiki.canWrite(page) は、書き込みの条件のうち''フォームでは変えられない側だけ''を返します。スクリプトの信頼度、PKWK_READONLY、ページ名、凍結、$edit_auth_pages です。

action・POST・トークンの3つは''見ません''。フォームが描かれるのはページの描画中だけで、そこでは3つとも必ず偽になります。全部を見ると canWrite() は常に偽になり、「書けないならフォームを描かない」という本来の用途でフォームが1つも描けなくなります。

書き込みそのもの（wiki.write）は従来どおり全条件を見ます。canWrite() が真でも、トークンの無いPOSTは失敗します。

*** 書き込んだあと (wiki.redirect) [#redirect]

 function plugin_guestbook_action(e) {
     wiki.append("GuestBook", "- " + e.vars["text"]);
     wiki.redirect("GuestBook");   // ここで終わる
 }

wiki.redirect(page) はリクエストをそこで終わらせ、page に移動させます。戻り値は無く、後ろの処理は実行されません。

これが無いと、フォームを送った人は action のページに取り残され、そこで再読み込みするとフォームがもう一度送信されます。

- action からのみ、かつ POST からのみ呼べます。
- 移動先はこのWikiのページのみです。: で始まるページと存在しないページは拒否します。
- try / catch では捕まえられません。

*** ページの書き込み例 [#ce4d5a63]
 // フォーム出力 (convert)
 return "<form method=\"post\">"
     + "<input type=\"hidden\" name=\"plugin\" value=\"pkript\">"
     + "<input type=\"hidden\" name=\"script\" value=\"guestbook\">"
     + "<input type=\"hidden\" name=\"pkript_token\" value=\"" + wiki.token() + "\">"
     + "<textarea name=\"text\"></textarea>"
     + "<input type=\"submit\" value=\"投稿\">"
     + "</form>";

 // 投稿処理 (action)
 function plugin_guestbook_action(e) {
     wiki.append("GuestBook", "\n- " + e.vars["text"]);
     return "<p>投稿しました。</p>";
 }


** data [#data_api]

スクリプトがリクエストをまたいで値を残せる場所です。キー1つが :config/pkript/data/<キー> ページ1枚で、値はJSONで入ります。

|~メソッド|~説明|h
|data.get(key, [default])|値。書かれていなければ default（既定は null）|
|data.set(key, value)|書き込み（action + POST + トークン + 信頼度）|
|data.has(key)|あるか|
|data.remove(key)|削除。無かったときは false|
|data.keys([prefix])|キーの配列（ソート済み）|
|data.canWrite(key)|書き込める状態か|

 function plugin_counter_action(e) {
     const n = data.get("counter/" + e.vars["page"], 0) + 1;
     data.set("counter/" + e.vars["page"], n);
     wiki.redirect(e.vars["page"]);
 }

- キーは [A-Za-z0-9_-] を / でつないだもの（128バイトまで）。接頭辞の外のページは指せません。
- 書き込みの条件は wiki.write と同じです。ページを描いているだけのときには書き込めません。
- ''読み出しに閲覧権限はありません。'' どのスクリプトからもどのキーも読めます。秘密を置く場所ではありません。
- PKRIPT_ALLOW_DATA を 0 にすると、読み出しは既定値を返し、書き込みは拒否されます。


** url [#url_api]

|~メソッド|~説明|h
|url.encode(str)|パーセントエンコード（RFC 3986。空白は %20）|
|url.decode(str)|パーセントデコード。UTF-8にならないものは空文字列|

ページへのリンクは wiki.uri() で足ります。url.encode はクエリの値を自分で組み立てるときに使います。

 return "<a href=\"" + htmlsc(wiki.uri() + "?cmd=pkript&script=v&q=" + url.encode(q)) + "\">検索</a>";


** date [#date_api]

時刻の取得と整形のAPIです。

|~メソッド|~説明|h
|date.now()|現在時刻を取得（エポック秒 - サーバTZ差）|
|date.format(t, [format])|時刻を整形して文字列化|

*** 時刻の持ち方 [#c84210d0]
PukiWikiは時刻を「エポック秒 − サーバのタイムゾーン差」で保持し、表示時に ZONETIME を足します。
wiki.time() と date.now() はその値をそのまま返し、date.format() は同じ規則で解釈します。
そのため、date.format(wiki.time(page)) は PukiWiki 本体の #lastmod と同じ表示になります。

*** 書式の指定 [#z798ed69]
書式を省略（または空文字）にした場合は本体の format_date() に委譲され、$date_format / $time_format / $weeklabels の設定がそのまま反映されます。#lastmod 系の表示を作成する場合は省略を推奨します。

書式を指定する場合、PHP の date() で許可された以下の文字のみを解釈します（64バイトまで）。

 Y y m n d j H G h g i s D l N w M F a A U t L

- 上記以外の文字（日本語など）はそのまま出力されます（例: "Y年n月j日"）。
- \ を前置すると、次の1文字をリテラルとして扱います。
- タイムゾーン名（e T Z など）はホスト設定依存を防ぐため除外されています。
- 第2引数に真偽値（true）を渡す format_date(t, true) の括弧付きスタイルも動作します。


** JSON [#json_api]

JSONの生成と解析を行うAPIです。

|~メソッド|~説明|h
|JSON.stringify(val, [indent])|値をJSON文字列に変換|
|JSON.parse(str)|JSON文字列をオブジェクト・配列・スカラーに解析|

- オブジェクトは {}、配列は [] に変換されます。空のオブジェクトも {} のまま出力されます。
- 関数はJSONにならないため、オブジェクト内では項目ごと除外され、配列内では null になります（JavaScriptの動作と同様）。
- 循環参照を含む値はエラーになります。
- UTF-8文字列は \uXXXX にエスケープされず素通しされます。
- indent に数値を指定すると、その文字数分の空白でインデント（整形）されます（既定値 0 は1行）。
- 入れ子の深さは PKRIPT_MAX_DEPTH、サイズは PKRIPT_MAX_STRING / PKRIPT_MAX_ARRAY の上限に従います。
- JSON.parse() は不正なJSONでエラーを投げます。try / catch で捕捉可能です。


** console [#console_api]

デバッグ用の出力です。ページへの出力手段ではありません。

|~メソッド|~説明|h
|console.log(...)|ログを1行残す|
|console.warn(...)|警告として1行残す|
|console.error(...)|エラーと同じ見た目で1行残す（実行は止まりません）|

 console.log("count =", items.length, e.opts);
 // Pkript Log: count = 3 {sort: "date"}

- 呼んだ時点では何も出力されません。スクリプトが終わったあと、PKRIPT_DEBUG が有効なときだけ、戻り値のHTMLの''後ろ''にまとめて表示されます。
- 引数は空白区切りで連結されます。オブジェクトと配列は中身が展開されます（深さ3まで。それより深いものは {...} / [...]、循環は [circular]）。
- 内容はHTMLエスケープされます。エラー表示と同じ1行の形なので、インライン呼び出しでも段落は壊れません。
- 専用のCSSは同梱していません。「Pkript Log:」というラベルで読めるようにしてあり、pkript-log / pkript-log-warn / pkript-error のクラスは色を付けたい場合の目印です。
- 実行が途中でエラーになった場合も、そこまでのログがエラーの前に出ます。
- 行数は PKRIPT_MAX_LOG、全体のバイト数は PKRIPT_MAX_LOG_BYTES が上限です。超えるとそこで記録を止めますが、''スクリプトは失敗しません''。
- 即時出力する echo はありません。出力はエントリポイントの戻り値だけがサニタイザを通る仕組みのためで、echo すると戻り値より前に出てしまい位置も合いません。


** html [#e6e6fafb]

|~メソッド|~説明|h
|html.escape(str)|HTMLエスケープ|
|html.br(str)|改行文字を <br /> に変換|
|html.strip(str)|HTMLタグを除去|


** Math [#s26f3ae7]

|~メソッド|~説明|h
|Math.floor(n)|切り捨て|
|Math.ceil(n)|切り上げ|
|Math.round(n)|四捨五入|
|Math.abs(n)|絶対値|
|Math.min(a, b, ...)|最小値|
|Math.max(a, b, ...)|最大値|
|Math.random()|0以上1未満の乱数を取得|


** Object [#j1ccae89]

|~メソッド|~説明|h
|Object.keys(obj)|キー一覧を配列で取得|
|Object.values(obj)|値一覧を配列で取得|
|Object.has(obj, key)|キーが存在するか確認|


** 配列 (Array) [#rb7b25da]

|~メソッド / プロパティ|~説明|h
|arr.length|要素数|
|arr.push(val)|末尾に追加|
|arr.pop()|末尾を取り出し|
|arr.shift()|先頭を取り出し|
|arr.unshift(val)|先頭に追加|
|arr.join(sep)|連結して文字列化|
|arr.indexOf(val)|要素の位置を検索|
|arr.includes(val)|要素の存在確認|
|arr.slice(start, [end])|部分配列を抽出|
|arr.reverse()|順序を反転|
|arr.concat(other)|配列を結合|
|arr.map(fn)|要素を変換|
|arr.filter(fn)|要素を絞り込み|
|arr.find(fn)|条件に合う最初の要素|
|arr.findIndex(fn)|条件に合う最初の位置|
|arr.forEach(fn)|全要素にコールバックを適用（戻り値なし）|
|arr.some(fn)|1つでも条件に合えば true|
|arr.every(fn)|すべて条件に合えば true|
|arr.reduce(fn, [initial])|1つの値に畳み込む|
|arr.sort([compareFn])|並べ替え|

 const nums = [1, 2, 3, 4, 5];
 const evens = nums.filter((x) => x % 2 == 0);     // [2, 4]
 const doubled = nums.map((x) => x * 2);            // [2, 4, 6, 8, 10]
 const sorted = [10, 9, 1].sort((a, b) => a - b);   // [1, 9, 10]

*** コールバックを受け取るメソッド [#array_callback]

map / filter / find / findIndex / forEach / some / every のコールバックは、JavaScript と同じく (item, index, array) を受け取ります。走査するのは配列のコピーなので、コールバックが元の配列に push してもループは伸びません。

- some は真になった時点で、every は偽になった時点で走査を打ち切ります。
- 空の配列に対しては some が false、every が true になります（JavaScript と同じ）。

*** 畳み込み (reduce) [#array_reduce]

reduce のコールバックだけは形が違い、(acc, item, index, array) を受け取ります。

 const total = rows.reduce((a, r) => a + r.count, 0);
 const index = keys.reduce((acc, k) => { acc[k] = 1; return acc; }, {});

初期値を省略すると先頭の要素が初期値になり、走査は2番目から始まります。このとき空の配列は返す値を持てないためエラーになります（JavaScript が TypeError を投げる場面です）。


** 文字列 (String) [#j8ef85aa]

マルチバイト（UTF-8）に対応しています。

|~メソッド / プロパティ|~説明|h
|str.length|文字数|
|str.toUpperCase()|大文字化|
|str.toLowerCase()|小文字化|
|str.trim()|前後の空白除去|
|str.trimStart()|先頭の空白除去|
|str.trimEnd()|末尾の空白除去|
|str.indexOf(sub, [from])|部分一致の位置検索|
|str.lastIndexOf(sub)|後方から部分一致の位置検索|
|str.includes(sub)|部分一致の確認|
|str.startsWith(sub)|前方一致の確認|
|str.endsWith(sub)|後方一致の確認|
|str.replace(from, to)|置換（最初の一致）|
|str.replaceAll(from, to)|置換（すべての一致）|
|str.split(sep)|分割して配列化|
|str.substring(start, [end])|部分文字列を取得|
|str.slice(start, [end])|部分文字列を取得|
|str.charAt(index)|指定位置の1文字|
|str.at(index)|指定位置の1文字（負の添字対応）|
|str.padStart(len, [pad])|文字数が len になるまで先頭を埋める|
|str.padEnd(len, [pad])|文字数が len になるまで末尾を埋める|
|str.repeat(count)|指定回数繰り返し|
|str.match(re)|正規表現で照合（[[Pkript/文法/正規表現]]）|
|str.matchAll(re)|正規表現で全件照合|
|str.search(re)|正規表現に最初に一致した位置|
|str.spanWhile(from, set)|set に含まれる文字が続く間だけ進み、止まった位置を返す|
|str.spanUntil(from, set)|set に含まれない文字が続く間だけ進み、止まった位置を返す|

*** 文字列のパディング (padStart / padEnd) [#za90a8a7]
文字数が len になるまで pad 文字列（既定値は半角空白）を繰り返して埋めます。マルチバイトを文字数として正しく数え、すでに len 以上の文字列はそのまま返します。長すぎる要求（PKRIPT_MAX_STRING 超過）はメモリ確保前に弾かれます。

 const cells = rows.map((r) => r.no.padStart(3, "0") + " " + r.name);

*** 負の添字アクセス (at) [#s21dbd9f]
str.at(i) は負の数を受け付けます。-1 は最後の1文字を指します。範囲外は空文字列を返します。

*** 文字列の走査 (spanWhile / spanUntil) [#k53b4c55]

1文字ずつ回るループの代わりに使います。構文ハイライタのような走査系のスクリプトでは、1文字あたり50〜60ステップかかるループが1回の呼び出しになります。

 const IDENT = "a-zA-Z0-9_$";
 let i = 0;
 while (i < code.length) {
     const end = code.spanWhile(i, IDENT);
     if (end > i) {
         out += htmlsc(code.substring(i, end));
         i = end;
         continue;
     }
     out += htmlsc(code.charAt(i));
     i++;
 }

- set には a-z のような範囲を書けます。- 自体を入れるときは先頭か末尾に置いてください。
- 範囲として扱うのは昇順のときだけです。z-a は3文字の集合になります。
- 戻り値は止まった位置なので、そのまま substring() に渡せます。
- マルチバイトでも charAt や substring と同じ数え方です。


** 正規表現 (RegExp) [#regexp_api]

/パターン/フラグ で作ります。詳しくは [[Pkript/文法/正規表現]] を参照してください。

|~メソッド|~説明|h
|re.test(str)|一致するかどうか|
|re.exec(str)|最初の一致の配列（全体, グループ1, ...）。無ければ null|
|re.source()|書いたパターン|
|re.flags()|書いたフラグ|
|re.global()|g フラグが付いているか|

文字列側の match / matchAll / search / replace / replaceAll / split も正規表現を受け取ります。

 const DATE = /(\d{4})-(\d{2})/;
 return "2024-05".replace(DATE, "$1年$2月");   // 2024年05月


** 数値 (Number) [#w7b12857]

|~メソッド|~説明|h
|num.toFixed(digits)|指定桁数の小数文字列に変換|
|num.toString()|文字列に変換|

- [[Pkript/文法]] - 言語仕様
- [[Pkript/設定]] - 設定定数と上限値
- [[Pkript/サンプル]] - 実用スクリプト集
- [[Pkript/エラー一覧]] - エラーメッセージと対処法