{"id":21282562,"url":"https://github.com/ayato-p/kuuga","last_synced_at":"2025-07-11T10:34:21.562Z","repository":{"id":65349409,"uuid":"100544218","full_name":"ayato-p/kuuga","owner":"ayato-p","description":"An extensible transformer for Hiccup(-like) data structure","archived":false,"fork":false,"pushed_at":"2017-12-05T23:31:40.000Z","size":110,"stargazers_count":21,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-28T13:06:45.177Z","etag":null,"topics":["clojure","clojurescript","hiccup","transformation"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayato-p.png","metadata":{"files":{"readme":"README.ja.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-17T00:27:03.000Z","updated_at":"2024-03-05T09:32:13.000Z","dependencies_parsed_at":"2023-01-19T01:15:27.036Z","dependency_job_id":null,"html_url":"https://github.com/ayato-p/kuuga","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-p%2Fkuuga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-p%2Fkuuga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-p%2Fkuuga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-p%2Fkuuga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayato-p","download_url":"https://codeload.github.com/ayato-p/kuuga/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225715909,"owners_count":17512909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","clojurescript","hiccup","transformation"],"created_at":"2024-11-21T10:57:25.613Z","updated_at":"2024-11-21T10:57:26.390Z","avatar_url":"https://github.com/ayato-p.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"* Kuuga [[https://circleci.com/gh/ayato-p/kuuga/tree/master][https://circleci.com/gh/ayato-p/kuuga/tree/master.svg?style=svg]] [[https://codecov.io/gh/ayato-p/kuuga][https://codecov.io/gh/ayato-p/kuuga/branch/master/graph/badge.svg]] [[https://opensource.org/licenses/MIT][https://img.shields.io/badge/License-MIT-blue.svg]]\n\n  #+begin_quote\n  \"こんな奴らのために！これ以上誰かの涙は見たくない！皆に笑顔でいてほしいんです！だから見ててください…俺の…変身！！\"\n  ― 五代が初めてマイティフォームに変身する際に、一条薫に向かって放った言葉\n  #+end_quote\n\n  KuugaはHiccup(-like)データ構造のための、拡張可能な変換器です。変換ルールは自由に定義することができます。\n\n** HTMLのフォームを記述する際の課題\n\n   HTMLのフォームというのはどのように記述しても冗長になりがちです。例えばサブミットしたフォームがバリデーションにひっかかったら、フォーム上にエラーを表示したり、ユーザーが入力していた値を再描画したりしないといけません。また、エラーの表示方法はCSSフレームワークによって違うことが多々あるため、ユーザーはCSSフレームワークのお作法に従ってフォームを書き換える必要があります。\n\n   例えば[[https://getbootstrap.com/][Bootstrap4]]を使った簡単なフォームの例は次の通りです。\n\n   #+begin_src clojure\n   (defn naive-form [{:keys [errors values] :as opts}]\n     [:form {:method :post}\n      [:div.form-group\n       [:label {:for \"input-email\"} \"Email address\"]\n       [:input#input-email.form-control\n        {:type :email :name :email\n         :class (if (contains? errors :email) \"is-invalid\" \"is-valid\")\n         :value (:email values)\n         :placeholer \"Enter email\"}]\n       [:div.invalid-feedback (:email errors)]\n       [:small.form-text.text-muted\n        \"We'll never share your email with anyone else.\"]]\n      [:div.form-group\n       [:label {:for \"input-password\"} \"Password\"]\n       [:input#input-password.form-control\n        {:type :password :name :password\n         :class (if (contains? errors :password) \"is-invalid\" \"is-valid\")\n         :value (:password values)\n         :placeholer \"Password\"}]\n       [:div.invalid-feedback (:password errors)]]\n      [:button.btn.btn-primary {:type :submit} \"Submit\"]])\n   #+end_src\n\n   /このコード辺の完全な例はexamples/bootstrapディレクトリにあります/\n\n   =input= タグがエラーだったなら =is-invalid= クラスを付与して、前回入力した値があるならそれを =value= として利用する…。全てのフォーム、全ての項目で同じようなことを繰り返し記述する必要があります。正直、毎回こんな風に書くのは嫌ですよね。私は嫌です。\n\n   これを解決するのがKuugaです。Kuugaを使うことによって、次のようにフォームを記述することができます。\n\n   #+begin_src clojure\n   [:form {:method :post}\n    [:div.form-group\n     [:label {:for \"input-email\"} \"Email address\"]\n     [:input#input-email.form-control\n      {:type :email :name :email :placeholer \"Enter email\"}]\n     [:small.form-text.text-muted\n      \"We'll never share your email with anyone else.\"]]\n    [:div.form-group\n     [:label {:for \"input-password\"} \"Password\"]\n     [:input#input-password.form-control\n      {:type :password :name :password :placeholer \"Password\"}]]\n    [:button.btn.btn-primary {:type :submit} \"Submit\"]]\n   #+end_src\n\n   エラーに関連するようなコードがフォーム上からなくなり、単純なHiccupデータとして定義できるようになりました。具体的な使い方は使い方 を読んでください。\n\n** インストール\n\n   以下を =project.clj= に依存ライブラリとして追加してください。\n\n   [[https://clojars.org/ayato_p/kuuga][https://img.shields.io/clojars/v/ayato_p/kuuga.svg]]\n\n** 使い方\n\n   Kuugaは任意のHTMLタグ、id属性、class属性に対して変換ルールを記述することができます。変換ルールはタグベクターのタグ名にのみ依存しています。\n\n   変換ルールを書くのは簡単で、例えば =input= タグに対応する変換ルールは以下のように書くことができます。\n\n   #+begin_src clojure\n   (require '[kuuga.growing :as growing]\n            '[kuuga.tool :as tool])\n\n   (defmethod growing/transform-by-tag :input\n     [_ options tag-vector]\n     (let [values (:values options)\n           [tag-name tag-options contents] (tool/parse-tag-vector tag-vector)\n           tname (:name tag-options)\n           tag-options (cond-\u003e tag-options\n                         (get values tname) (assoc :value (get values tname)))]\n       [tag-name tag-options contents]))\n   #+end_src\n\n   Kuugaの拡張ポイントは =kuuga.growing= ネームスペースに全て用意されています。また、 =transform-by-tag=, =transform-by-id=, =transform-by-class= とそれぞれ用意していますが、全て同じようにマルチメソッドとして定義しています。\n\n   ユーザーは上の例のように =defmethod= によってメソッドを追加することで新しい変換ルールを追加することができます。各マルチメソッドは第1引数にディスパッチ値、第2引数に変換畤のオプション、第3引数にタグベクターを受けとり、変換されたタグベクターを返します(後述しますが必ずしもタグベクターを返す必要はありません)。また、各マルチメソッドはディスパッチ値としてキーワードを渡されるので、新しい変換ルールを追加する場合はディスパッチ値をキーワードで指定してください。\n\n   任意のタグベクターはまずタグに基づく変換が行なわれ、その次にid属性に基づく変換、最後に各class属性に基づく変換が行なわれるようになっています。\n\n   最後にKuugaの変換器は関数バージョンとマクロバージョンの2種類を用意しています。どちらを利用するかによって、変換ルールの書き方が微妙に異なるため注意してください。\n\n*** 関数バージョンを利用する場合\n\n    関数バージョンの変換器は =kuuga.mighty= ネームスペースに用意してあります。特に理由がなければ =kuuga.mighty/transform= を利用することを推奨します。関数バージョンの変換器を利用する場合、変換ルールを書くのはとても簡単です。使い方の最初の例は関数バージョンの変換器を利用する場合に正しく動作します。次のように利用します。\n\n    #+begin_src clojure\n    (require '[kuuga.mighty :as mighty])\n\n    (def tagvec [:input {:name :username}])\n\n    (def transformed\n      (let [opts {:values {:username \"ayato-p\"}}]\n        (mighty/transform opts tagvec)))\n\n    transformed\n    ;;=\u003e ([:input {:name :username, :value \"ayato-p\"} nil])\n\n    (require '[hiccup2.core :as hiccup])\n\n    (str (hiccup/html {:mode :html} transformed))\n    ;;=\u003e \"\u003cinput name=\\\"username\\\" value=\\\"ayato-p\\\"\u003e\u003c/input\u003e\"\n    #+end_src\n\n*** マクロバージョンを利用する場合\n\n    マクロバージョンの変換器は =kuuga.ultimate= ネームスペースに用意してあります。こちらも特に理由がなければ =kuuga.ultimate/transform= を利用してください。マクロバージョンの変換器は、マクロ展開畤に変換を行なうため、変換ルールの書き方にちょっとしたコツが必要です。\n\n    #+begin_src clojure\n    (require '[kuuga.growing :as growing])\n\n    (defn update-input-opts [options tag-options]\n      (let [values (:values options)\n            tname (:name tag-options)]\n        (cond-\u003e tag-options\n          (get values tname) (assoc :value (get values tname)))))\n\n    (defmethod growing/transform-by-tag :input\n      [_ options tag-vector]\n      (let [[tag-name tag-options contents] (tool/parse-tag-vector tag-vector)]\n        `[~tag-name\n          (update-input-opts ~options ~tag-options)\n          ~@contents]))\n    #+end_src\n\n    この変換ルール用のマルチメソッドはマクロ展開中に利用されるため、変換ルール用の各マルチメソッドが引数に取る =options= は、マップではなくただのシンボルがやってくる可能性があることに注意しなければなりません。\n\n    実際に利用する場合は次のようになります。\n\n    #+begin_src clojure\n    (require '[kuuga.ultimate :as ultimate])\n\n    (def transformed\n      (let [opts {:values {:username \"ayato-p\"}}]\n        (ultimate/transform opts [:input {:name :username}])))\n\n    transformed\n    ;;=\u003e ([:input {:name :username, :value \"ayato-p\"}])\n\n    (require '[hiccup2.core :as hiccup])\n\n    (str (hiccup/html {:mode :html} transformed))\n    ;; \"\u003cinput name=\\\"username\\\" value=\\\"ayato-p\\\"\u003e\"\n    #+end_src\n\n    マクロバージョンの変換器はHiccupのデータ構造を直接引数に取る必要があることにも注意してください。また、実際にマクロ展開畤に変換が行なわれていることは、次のように確認することができます。\n\n    #+begin_src clojure\n    (require '[clojure.walk :as walk])\n\n    (walk/macroexpand-all\n     '(ultimate/transform opts [:input {:name :username}]))\n    ;;=\u003e (clojure.core/list [:input (user/update-input-opts opts {:name :username})])\n    #+end_src\n\n** ボーナスステージ\n\n   変換ルールのマルチメソッドは、必ずしもタグベクターを返さなくても良いと書きました。どういうことかというと、以下のようなことが出来るためです。\n\n   #+begin_src clojure\n   (require '[kuuga.growing :as growing]\n            '[kuuga.mighty :as mighty])\n\n   (defmethod growing/transform-by-tag :comment\n     [_ _ _])\n\n   (mighty/transform* [:comment \"This is comment\"])\n   ;;=\u003e nil\n\n   (defmethod growing/transform-by-tag :+\n     [_ _ tag-vector]\n     (when-let [numbers (next tag-vector)]\n       (apply + numbers)))\n\n   (mighty/transform* [:+ 1 2 3])\n   ;;=\u003e 6\n\n   (defmethod growing/transform-by-tag :field\n     [_ _ tag-vector]\n     (let [[_ label name] tag-vector]\n       [:div.form-group\n        [:label label]\n        [:input {:name name}]]))\n\n   (mighty/transform* [:field \"Name\" :username])\n   ;;=\u003e\n   ;; [:div.form-group\n   ;;  [:label \"Name\"]\n   ;;  [:input {:name :username})]]\n   #+end_src\n\n\n** FAQ\n\n   - Q. 仮面ライダークウガが好きなんですか?\n   - A. 最高です\n   - Q. 何故、Kuugaという名前を付けたんですか?\n   - A. 変換 -\u003e transform -\u003e 変身-\u003e 仮面ライダー -\u003e クウガ\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayato-p%2Fkuuga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayato-p%2Fkuuga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayato-p%2Fkuuga/lists"}