Reveal My Ignorance

SyncTimerのコードをいくつかのモジュールに分解した

2023-03-13T17:28:02+09:00

これまで Main.elm だけで作ってきた Elm のコードが増えて見通しが悪くなってきたので、いくつかのモジュールに分解した。今回はリファクタリングなので機能の変更はなし。

モジュールへの分解

分解前のコードが691行になっていた。ここまで増えるとスクロールも疲れるし、どこに何があるかわからなくなってしまう。

そこで、大きな構成要素を整理しモジュールに分けてみることにした。

Main.elm
- main 関数、および起動時のパラメータ管理。
Model.elm
- Model 型を中心としたデータの定義とデータの変換に関する関数群。
- Cmd Msg , Html Msg を含まない純粋なもの。
Msg.elm
- Msg 型、 update 関数の定義。
- ユーザーインタラクションに対するふるまい。
View.elm
- view 関数の定義。
- 画面表示に関するもの。
Analytics.elm
- Google Analytics 向けのイベント送信の定義。

どうやって分解するかは我流だが、それぞれのファイルがどのライブラリやモジュールに依存するか見るとだいぶスッキリしたように見える。

import で見る依存関係

それぞれのファイルから import を抜き出してみる。

Main.elm

import Browser
import Browser.Events
import Model exposing (Model, Setting, decodeBgColor, decodeBoolean, decodeFgFont, defaultSetting)
import Msg exposing (Msg(..), update)
import View exposing (view)

main 関数はすべての起点なので Model, Msg, View のモジュールを使っていることは当然なのだが、それ以外が main 関数を作るための Browser と、 subscriptions に使う Browser.Events だけになっていてかなりシンプルになった。

Model.elm

import Dict
import Time

たったこれだけ。他のモジュールへの依存もなく、データを中心とした純粋なモジュールになった。

Msg.elm

import Analytics exposing (timerFastForwardEvent, timerPauseEvent, timerResetEvent, timerRewindEvent, timerStartEvent)
import Dict
import Model exposing (BgColor, FgFont, Model, Setting, defaultSetting, encodeBgColor, encodeBoolean, encodeFgFont)
import Time
import Url.Builder as UB

設定の更新時にURLを同期させる目的で Url.Builder を使用している以外は、 View にも依存しておらず Model を中心に動作していることがはっきりしている。

View.elm

import Html exposing (Attribute, Html, a, button, details, div, i, input, label, option, select, span, summary, text)
import Html.Attributes as A exposing (attribute, checked, class, for, id, selected, step, style, type_, value)
import Html.Events exposing (onClick, onInput)
import Model exposing (BgColor(..), FgFont(..), Model, Setting, decodeBgColor, decodeFgFont, encodeBgColor, encodeFgFont)
import Msg exposing (Msg(..))

Model, Msg に依存しているのは言うまでもないが、それ以外は完全に Html 関連のインポートだけになっている。逆に言えば、 Html 関連のインポートは View.elm だけしか存在しない。

Analytics.elm

port module Analytics exposing (..)

import Json.Encode as E
import Model exposing (Setting, encodeBgColor, encodeFgFont)

Analytics に送信するための port の定義もここに配置したので最初の宣言が port module となっている。また、 Json 関連のモジュールもここでしか使わないことが明確になっている。

変更前の import を見てみる

変更前はどうだったかというと、当たり前だが上記を全部放り込んだ形になっている。

import Browser
import Dict
import Html exposing (Attribute, Html, a, button, details, div, i, input, label, option, select, span, summary, text)
import Html.Attributes as A exposing (attribute, checked, class, for, id, selected, step, style, type_, value)
import Html.Events exposing (onClick, onInput)
import Json.Encode as E
import Time
import Url.Builder as UB

どこかで使ってるんだろうな、ということは理解できるものの、やはり見通しが悪くなるのは否めない。（フォーマッタがよしなに整理してくれて使ってないモジュールもエディタがグレーアウトしてくれるのでなんとかなっているが）

スコープは小さく、依存も小さく

アプリケーションコードが持っている構造を見えるように整理することは読み手を手助けしてくれるし、一つのモジュールについて集中して考えるときに余計なコードが目につかなくなる。

また、モジュールに分解されたことで変更履歴の差分をファイル一覧で見るだけでもどこに変更が加わったか予想しやすくなったりする。

この規模のコードで一人で開発している分にはメリットはあまりないと思うかもしれないが、逆に大規模になったりチームで開発するときはこのようなリファクタリングを行うタイミングすら少なくなり、「いつかコードを整理したい」と思っていても練習すらままならない状態でいきなり取り掛かることも難しいので実現できないリファクタリングをいつまでも夢見ることになる。

コードの構造に注目して分解するなどのリファクタリングの実践練習は自己責任で変更できる小さいプロダクトで試しておくのがいいかもしれない。

SyncTimerにフォントを追加した

2023-02-25T18:00:00+09:00

Loraというセリフ体のフォントを選択可能にしてみた。

きっかけになったのは今回もとあるVTuberの方の動画がきっかけ。

きっかけはreplica.Bさん ( @re_plica_B ) のこちらの配信を見かけたから、需要ありそうだなと思って取り急ぎ作ってみました。https://t.co/pCtB01iBNr
— mather / Eisuke Kuwahata (@mather314) February 23, 2023

Google フォントを使う

最初から使っている D-DIN フォントはGoogleフォントに存在しないのでダウンロードして著作権表記を入れて利用している。

今回は Google フォントを指定して使ってみることにする。

使いたい文字の分だけ取得する

基本的には使いたいフォントをプレビューしながら選択し、表示されるCSSの @import 文を貼り付けるだけでWebフォントが利用できる。

ただ、今回使う部分はタイマーの時刻表示のみなので、「0から9」と「-」と「:」の表示に必要な部分だけに絞った最小限のダウンロードサイズであることが望ましい。

そこで、フォントを取得するURLの指定方法をAPIドキュメントで確認すると、 text パラメータで表示したい文字を指定する事ができるので、次のような @import を行うことにした。

@import url("https://fonts.googleapis.com/css2?family=Lora&display=swap&text=-:.0123456789");

（使うかどうかわからないけど、「.」もひっそり追加している）

フォント切り替えのアレコレ

新しいフォントをただ適用すればいいかというと実はそんなことはなかったりする。

理由は「フォントによって文字の横幅が違う」「コロン(:)の位置を調整できたりできなかったりする」などのブレがあるので個別に表示確認して調整する必要があるためだ。

そこで、等幅にするために display: inline-block; を指定する共通部分とフォントごとに幅調整などのパラメータをいじる部分とにCSSを整理した。

これによって新しいフォントを追加することに障壁は少なくなったが、正直なところ面倒なのであんまりやりたくない。誰かプルリクエストで実装してくれないか。

開発しないんじゃなかったの？

一通りやりきったかなとか思ってたけど、やっぱり追加開発したいときもある。

早送り・早戻しボタンを追加してみた

2022-12-09T19:40:52+09:00

エゴサーチしながらライブを拝見してたら、とある方がタイマーを停止したときのコメントを話していたのでフィードバックとして受け取り、簡単ながら「1秒戻る・1秒進める」ボタンを追加してみた。

ご意見ありがとうございます

九条茘枝さんのこちらの動画の11:02くらいでタイマーの話をしていただいているのだが、一旦止めたら再開するときのタイミング合わせが難しかったり、「数秒戻したい」ということができないのは確かに困るなぁ、と思ったので簡素だが作ってみることにした。

こんな挙動になります

技術的には全然難しくはないけど、ボタンの配置とかデザイン面でやっつけ仕事なので、もっと良い配置があるかもしれない。

要望があれば考えたいこと

たとえばこんな機能は使う人がいるかもなぁ、と思ったりしている。

視聴する動画の頭からではなく途中から見るので、指定された時間まで進めたい
スタート時間はマイナス30秒じゃ足りない（今回の機能でもっとマイナスにできるようになったけど）

が、ひとまずリクエストがなければ手を付けないことにしようと思う。

カウントダウン時の残り時間をバーで視覚化する

2022-12-07T19:00:17+09:00

カウントダウンの表示に追加要素として進み具合をバーで視覚化できるようにしてみた。

ミリ秒を表示していない理由

SyncTimerではミリ秒の表示をしておらず、カウントダウンの表示をするときに進み具合がわかりにくい。

ミリ秒を表示しないのは理由があって、そもそもSyncTimerで表示されている値は「ミリ秒を表示していない」のではなく「0秒を表示するときの挙動」をわかりやすくするためのものだ。

具体的にミリ秒まで含めるとタイマーがどんな値を表示するのか考えてみると良い。例えばちょうど1秒ずつ進んだとすると、こんな表示になるはずだ。

-00:00:01.234
-00:00:00.234
 00:00:00.766
 00:00:01.766

この表示から単純にミリ秒を削ると、マイナス0秒が発生していることがわかる。

-00:00:01
-00:00:00
 00:00:00
 00:00:01

こうなってしまうと、視覚的には 3, 2, 1, 0 のタイミングで再生開始したいように見えるのに、-3, -2, -1, -0, 0, 1, 2 となってタイミングが曖昧になってしまう。（人間がミリ秒の高速カウントダウンを読めるならそれでもいいけど多分読めないので、おそらく秒の表示の方を参考にしてしまうだろう）

そこで、タイマーは次のように「実際の値を超えない最大の秒」を計算して表示している。

-00:00:01.234 => -00:00:02
-00:00:00.234 => -00:00:01
 00:00:00.766 => 00:00:00
 00:00:01.766 => 00:00:01

これであれば、00:00:00 を表示したタイミングが実際の0秒と一致している。

リリースして反応を見よう

そんなわけで適切に0秒を表示するためやむを得ずミリ秒を表示していないのだが、やはり視覚的にわかりにくい気がしたので残り時間を表示できるようにしてみた。

反応があるかどうか、改善案が出てくるかどうかはわからないが、ひとまずリリースして反応を見てみることにする。

Mini Type Puzzle

2022-12-07T17:39:53+09:00

飛び入りで Elm アドベントカレンダー 2022 の12/7の記事を書いてみようと思う。

とはいえ何も準備していないので、最近の気持ちよかったことを書く。

関数がピッタリハマったときの気持ちよさ

趣味で作っているタイマーのコードをぼちぼちいじってたときに、ラジオボタンをセレクトボックスに変更しようと思って書き換えていた。

これまでのラジオボタンなら、各 input の属性に onClick <| SetBgColor GreenBack などのように個別に記述すればよかったのだが、 select になると onInput : String -> Msg を使う必要が出てくる。

でまぁ文字列を変換するコードをちまちま書けばいいじゃないか、という話なのだが、今回はこれまでに書いていたいくつかのパーツがきれいにハマって書くことができたのでちょっと嬉しかったのだ。

あらかじめ言っておくと、タイトルにいうほどのパズルではないと思うので期待はしないでいただきたい。

文字列を代数的データ型に

設定情報をクエリ文字列に変換し、クエリ文字列から設定を復元する、という仕様のため、文字列から代数的データ型の変換を行っている。このとき便利なのが Dict で、次のように対応関係を定義していた。

type BgColor
 = Transparent
 | GreenBack
 | BlueBack

dictBgColor : Dict.Dict String BgColor
dictBgColor =
 let
 pairwise bgColor =
 ( encodeBgColor bgColor, bgColor )
 in
 Dict.fromList <| List.map pairwise [ GreenBack, BlueBack, Transparent ]

これは以前 Url.Parser.Query.enum を使っていたときの名残だ。

enum : String -> Dict String a -> Parser (Maybe a)

そもそも、 Dict.get が似たようなことをしている。

get : comparable -> Dict comparable v -> Maybe v

しかし、この関数の都合の悪いのは引数の順番である。 Dict comparable v の部分を固定して使いたいときに不便だ。そこで、関数型のアイデアとしては flip : (a -> b -> c) -> b -> a -> c を使いたくなるのだが、 Elmではすでに削除されているので簡単に実装する。

flip : (a -> b -> c) -> b -> a -> c
flip f a b =
 f b a

さて、これによって String -> Maybe BgColor という対応関係が作れる

flip Dict.get dictBgColor -- String -> Maybe BgColor

`Msg` に変換する

BgColor の変更を伝える SetBgColor が定義されていて、これは SetBgColor : BgColor -> Msg とみなせるので、これを Maybe BgColor に適用したい。つまりは Maybe.map を使えば良い。

Maybe.map SetBgColor -- Maybe BgColor -> Maybe Msg

`Maybe Msg` のままでは渡せない

onInput : (String -> Msg) -> Html.Attribute Msg のシグネチャには Msg が要求されるので最後は Maybe ではだめだ。

実際にはそんなケースは発生しないことはわかっているのだが、入力が String である以上はイレギュラーなケースもカバーしなければならない。

そこで、 NoOp という値が役に立つ。もし BgColor に該当しないイレギュラーな値が入力されたときは最終的に「何もしない」が送信される。

Maybe.withDefault NoOp -- Maybe Msg -> Msg

関数合成

3つの関数の入力と出力がうまい具合に噛み合った。あとはこれを合成するだけだ。

selectBgColor : String -> Msg
selectBgColor =
 flip Dict.get dictBgColor >> Maybe.map SetBgColor >> Maybe.withDefault NoOp

カッコもなくスッキリと合成できた。一つ一つのシンプルな仕組みがうまく合致して整理できたときはやっぱり嬉しいな。

Elmアプリケーションとしての規模を小さくする

2022-12-04T17:00:00+09:00

SyncTimerのリファクタリングを行った。今回のテーマは「どこまでをElmで管理すべきか？」ということ。

疑問：リンククリックの挙動は管理されるべきか？

紹介ページを作ったことで2ページ目への遷移を行うようになったが、ここで一つ気になるポイントが生まれた。単純なリンクのクリックであっても、 Browser.application では Msg として管理しなければならないという回りくどい部分だ。

https://github.com/mather/sync-timer/blob/bb98a2ad01d76184d9073f9a85a867e09d754a0b/src/Main.elm#L499-L501

これまでのリンクはすべて新規タブで開くようにしていたので該当しなかったが、 Browser.application はSPAのような挙動を想定して作られているため、リクエストされたURLをアプリケーションで処理すべきか、ブラウザ上のページ遷移として扱うべきかをコントロールする必要があるのだ。

そもそもなぜ Browser.application を使っていたのかというと、設定変更時にブラウザのURLを書き換えて反映させるためだった。では、その機能や静的なコンテンツであるヘッダー・フッターを HTML、JS 側に移動させるとElmが管理すべき対象はどのくらいシンプルになるのか？

アプリケーションの挙動として管理しなくてよい部分

Browser.application と Browser.document はページ全体を管理するためHTMLのタイトルなども管理対象だったが必要ない。
ヘッダー部分、フッター部分はタイマーの挙動とは関係なく固定されている。

上記のような見直しの結果、タイマーの表示・コントロール・設定の部分のみを切り出して Browser.element で実装することにした。ただし、このままではブラウザのURLを設定に合わせて変更させる機能が動かなくなるので、JSを使って連動させることにした。

読み込み時の初期値をElmに取り込む

Browser.element ではリクエストされたURLを取得することはできないので、JSで取得してElmアプリケーションに渡す必要がある。そのため、以下のようなコードを記述してクエリ文字列のパースを行うことにした。

const parseParams = () => {
 const searchParams = (new URL(document.location)).searchParams;
 const parseFg = (s) => {
 if (!s) return null;
 const re = /^#[0-9a-f]{6}$/;
 if (re.test(s)) return s;
 return null;
 }
 const parseInit = (s) => {
 if (s) {
 const n = parseInt(s, 10);
 if (n > 30 || n < -30) return null;
 return n;
 }
 return null;
 }
 return {
 fg: parseFg(searchParams.get("fg")),
 bg: searchParams.get("bg"),
 init: parseInit(searchParams.get("init")),
 h: searchParams.get("h")
 };
};


const app = Elm.Main.init({
 node: document.getElementById("root"),
 flags: parseParams()
});

RGB値、数値に関してはバリデーションや型変換を行い、 Elmアプリケーションの flags にシンプルなJavaScriptオブジェクトとして渡すだけ。仮にパースに失敗しても、 null を渡すことでデフォルト値を採用するようにしている。

Elm側は flags の値を次のように処理している。

type alias SettingFromQuery =
 { fg : Maybe String
 , bg : Maybe String
 , init : Maybe Int
 , h : Maybe String
 }

parseSettingFromQuery : SettingFromQuery -> Setting
parseSettingFromQuery setting =
 { fgColor = setting.fg |> Maybe.withDefault defaultSetting.fgColor
 , bgColor = setting.bg |> Maybe.andThen decodeBgColor |> Maybe.withDefault defaultSetting.bgColor
 , initialTimeSeconds = setting.init |> Maybe.withDefault defaultSetting.initialTimeSeconds
 , showHour = setting.h |> Maybe.andThen decodeShowHour |> Maybe.withDefault defaultSetting.showHour
 }

initialModel : SettingFromQuery -> ( Model, Cmd Msg )
initialModel setting =
 let
 initSetting =
 parseSettingFromQuery setting
 in
 ( { timeMillis = initSetting.initialTimeSeconds * 1000
 , paused = True
 , current = Nothing
 , setting = parseSettingFromQuery setting
 }
 , Cmd.none
 )

Browser.element では flags は型引数なので、入力値の型を SettingFromQuery と定義する。もしこの型に構造や値が合致しないデータがElmアプリケーションの起動時に渡された場合、Elmアプリケーションはエラーを起こし起動しない。実に潔い。

設定変更を Ports で送信する

すでに Google Analytics の際に Ports を使ってElmアプリケーション外部への挙動は実装していたが、今回はURLを書き換える機能を呼び出す Ports を作成する。

Elm側は設定の変更時に setQueryString, urlFromSetting 関数を呼び出している。(背景色変更の例)

 SetBgColor bgColor ->
 ( { model | setting = { setting | bgColor = bgColor } }
 , setQueryString <| urlFromSetting { setting | bgColor = bgColor }
 )

これらはそれぞれ次のように定義されている。 port setQueryString : String -> Cmd msg が Ports として外部に実装されている関数を呼び出すことを宣言していることになる。

port setQueryString : String -> Cmd msg

urlFromSetting : Setting -> String
urlFromSetting setting =
 UB.toQuery
 [ UB.string "fg" setting.fgColor
 , UB.string "bg" <| encodeBgColor setting.bgColor
 , UB.int "init" setting.initialTimeSeconds
 , UB.string "h" <| encodeShowHour setting.showHour
 ]

JS側では受け取ったクエリ文字列をURLにセットしている。

app.ports.setQueryString.subscribe((newQS) => {
 const currentUrl = new URL(document.location);
 const newUrl = currentUrl.origin + currentUrl.pathname + newQS;
 window.history.replaceState(null, "", newUrl);
})

これで一応同じ挙動を実装することができた。

Elmの行数

修正の結果、 src/Main.elm の行数は567行から486行に減った。そんなに減ってないように見えるが、Elmアプリケーションとして管理する範囲がシンプルになったのと、アプリケーションの挙動に影響しないヘッダー・フッター部分の修正が Main.elm で行われないことがわかっているとすごく楽に感じられる。

SyncTimer の紹介ページを作った

2022-11-27T18:40:11+09:00

タイトルそのままなのだが、これまでモーダルとして表示していた使い方動画なども紹介ページへ移動してみた。これはもともと存在していたのだが、Github Pages として公開しておりアプリケーションと同じドメインではなかったので、同じドメインに /about として表示するようにした。

https://sync-timer.netlify.app/about/

モーダルのほうがわかりやすかっただろうか？という疑問もあるが、一旦公開することにした。

紹介ページで使用している技術

Bulma というCSSフレームワークを使用している。

タブ表示の見た目についてはこのフレームワークでも対応しているのだが、実際に動かすためにはJavaScriptコードを書かないといけなくなる。

検索したらすぐ出てくると思うのだが、実例としてここにメモしておこう。

HTML上はタブで切り替えるコンテンツに id を振ってあり、一つだけ表示状態にしてある。

<div class="tab-content" id="about-content">
 ...
</div>
<div id="caution-content" class="tab-content" style="display: none">
 ...
</div>
<div class="tab-content" id="inquiry-content" style="display: none">
 ...
</div>

タブの方はBulmaのスタイルを適用し、ボタンのように機能するようにする。

<div class="container tabs is-centered is-large is-boxed">
 <ul>
 <li id="about-tab" class="is-active">
 <a onclick="activateTab('about')">概要</a>
 </li>
 <li id="caution-tab">
 <a onclick="activateTab('caution')">利用時の注意</a>
 </li>
 <li id="inquiry-tab">
 <a onclick="activateTab('inquiry')">お問い合わせ</a>
 </li>
 </ul>
</div>

タブがクリックされると、 activateTab 関数を呼び出してタブの表示を切り替える。指定されたクラスにマッチするHTMLエレメントを探して、一旦非表示に切り替えて、指定されたものだけ表示状態に切り替えているシンプルな実装だ。

function activateTab(to) {
 const tabs = document.querySelectorAll(".tabs li");
 const tabContents = document.getElementsByClassName("tab-content");
 for (const tab of tabs) {
 tab.className = "";
 if (tab.id == to + "-tab") tab.className = "is-active";
 }
 for (const content of tabContents) {
 content.style.display = "none";
 if (content.id == to + "-content") content.style.display = "block";
 }
 gtag("event", "activate_tab", { event_label: to });
}

ただ、難点が一つ。 display: none; を適用して切り替えるまで、 <iframe> で読み込んでいる要素がロードされないのだ。

ユーザーとしては必要ない読み込みが減って良いようにも思えるが、問い合わせフォームをタブで表示すると一瞬遅れて表示される結果になってしまう。

微妙にユーザー体験が良くない気がするが、そもそも問い合わせフォームが使われたことがないので許容範囲としている。

時間の表示を切り替えられるようにした

2022-11-18T00:29:11+09:00

タイマーの利用状況をたまに観察していると、1時間未満（アニメなどはおおよそ30分未満）の動画再生などに使われるケースもそれなりに多いため、「時・分・秒」ではなく「分・秒」の表示だけに切り詰めたほうがレイアウトとしても便利かもしれない、と思ったので機能を追加してみた。

どんな機能？

百聞は一見にしかず。

注意点

1時間を超えてしまった場合は自動的に「時・分・秒」の表示になる。レイアウトが崩れると思うので注意してほしい。

SyncTimerのリファクタリング

2022-11-15T22:32:53+09:00

SyncTimerのコードをリファクタリングしてみた。

リファクタリングとは、動作を変更させずにコードを整理する作業のことである。繰り返している無駄な機能をまとめたり、わかりやすく整理することで保守しやすくすることができる。

リセット時の初期秒数を Setting にまとめる

作るときの順番としてたまたま initialTimeSeconds の値が Model に含まれておりそのままにしていたのだが、文字色や背景色の設定を追加されたことで複数の設定項目をまとめたくなり、 Setting という型を作成してまとめた。

内容的に Setting がタイマーの表示の設定値のみであるように思っていたのだが、よくよく考えるとクエリ文字列に保存している値を作るために initialTimeSeconds と渡しているので、これもいわゆる設定値である。

urlFromConfig : String -> BgColor -> Int -> String
urlFromConfig fg bg initialTimeSeconds = ...

ということで、この後のことも考えて設定値全般を Setting にまとめることにした。

設定の初期値をまとめる

これまでクエリ文字列をパースしたときに設定値が指定されていない場合に初期値を設定するように定義していた。しかし、当初よりも設定情報の種類が増えそうな予感がしたので、あちこちに散らばるより Setting 型の初期値 defaultSetting を具体的に一つ定義してあげたほうが適切だと思い、一つの値として整理した。

defaultSetting : Setting
defaultSetting =
 { fgColor = "#415462"
 , bgColor = GreenBack
 , initialTimeSeconds = -10
 }

Url.Parser.Query の仕組みを上手く使う

クエリ文字列からパラメータを取り出す処理に Url.Parser.Query を使っているが、これまでは Query.string などの関数を用いて得られる Maybe String などの値をそのまま利用していた。

Query.string : String -> Parser (Maybe String)

そのため、得られる値を定義した型 InitParams が Setting とほぼ同じ内容ですべて Maybe がついた状態となっていた。

type alias InitParams =
 { fgColor : Maybe String
 , bgColor : Maybe BgColor
 , initialTimeSeconds : Maybe Int
 }

しかし、改めて考えてみると Parser (Maybe String) に初期値を加えてあらかじめ Parser String に変換しておけばよい。ということで以下の処理を加えた。

parserWithDefault : a -> Query.Parser (Maybe a) -> Query.Parser a
parserWithDefault default =
 Query.map <| Maybe.withDefault default

Query.map : (a -> b) -> Parser a -> Parser b を用いることで「存在しなければ初期値を返す」という関数適用を行えば、Maybe ではなく確実に値を返すパーサーが出来上がる。

これを最後に Query.map3 を使って Setting に変換することができる。

queryParser : Query.Parser Setting
queryParser =
 Query.map3
 Setting
 (parserWithDefault defaultSetting.bgColor <| Query.enum "bg" dictBgColor)
 (parserWithDefault defaultSetting.fgColor <| Query.string "fg")
 (parserWithDefault defaultSetting.initialTimeSeconds <| Query.int "init")

ここで Setting そのものは本来は型エイリアスなのだが、3つの値を受け取って Setting を返すコンストラクタとしても使えることに留意する。

これにより InitParams という中間処理の型が不要になった。

ネストしたモデルの更新方法

そんな文法があることを知らなかっただけなのだが、ネストしたモデルの更新などに使える方法を見つけたので使ってみた。

これまで、 update には Model の値をそのまま渡しており、その内部の Setting の値を更新したいときは専用の関数を作ってこんな風にしていた。

{ model | setting = updateBgColor bgColor model.setting }

updateBgColor : BgColor -> Setting -> Setting
updateBgColor bgColor setting =
 { setting | bgColor = bgColor }

しかし、関数の引数で受け取るときに { setting } as model という形でネストした値についても変数の束縛ができるのである。

https://faq.elm-community.org/#how-can-i-pattern-match-a-record-and-its-values-at-the-same-time

そんなわけで、これを使えばわざわざ専用の関数を作る必要はなくシンプルに記述できた。

update msg ({ setting } as model) = ...

{ model | setting = { setting | bgColor = bgColor } }

「みんな面倒に思うポイントだしきっと良い解決方法があるはずだ」と思って探してみれば、やっぱりあるもんだ。納得するまでしつこく調べてみよう。

リファクタリングは大事

その他の細かい修正点もあるが、おおよそ上記のような修正を行った。

リファクタリングは機能を追加することもなく変更を行うため、ビジネスの現場では「生産性がない」「変更したことでバグを生むリスクがある」という考え方で避けられがちなのだが、以下の面でメリットが大きいと思う。

改めてコードを見ることで理解を深め、もっと良い方法に気づく
出来上がっている機能から本質的な問題（今回でいうと初期時間が Setting に含まれるべきであること）に還元できる

本来はリファクタリングを行う上で動作するテストを記述し「動作が変わっていないこと」を担保するのが良いが、 SyncTimerの場合はそもそも機能が少ないことやElmの純粋関数型の利点もあり十分信頼できるのでリファクタリングを行った。

SyncTimerのレイアウトを変更

2022-11-10T10:42:00+09:00

開始・リセットボタンとタイマーの表示設定の配置を変更した。

変更前

変更後

変更の目的

そもそも開始ボタンが大きいほうが押しやすくていいのでは、くらいの安易な気持ちでこの配置にしたのだが、

表示設定をもうちょっと拡張しようかな、と思い始めたときに「表示設定」がこの位置にあると狭い
タブレットサイズで表示したときにタイマーと再生ボタンの間に設定が入ってしまう
- 設定は配信を開始する前に調整するし、一度設定を決めたら基本的には再生とリセットしか押さないはずなので設定が下のほうがいい、と思う

という考えがあり配置を変更することにした。

技術的には難しくなかった。自動的なグリッドレイアウトって便利だねぇ。

Pico.cssのグリッドレイアウトはシンプルに等分配置しかできないし、多段階のレスポンシブではないので融通は利かないけど。（もっと柔軟なグリッドレイアウトが必要な場合はBootstrapなどの機能を追加する方法が提示されている）

SyncTimer に Google Analytics を導入した

2022-04-30T19:00:00+09:00

たぶん使ってる人はいるんだろうなー、と思いつつも利用報告をしてくれるユーザーはほぼいない。それは当然で、報告するメリットもないし、不具合があったり使い勝手が悪いなーと思っても似たような手段はいくらでもあるので別のツールに切り替えるだけになる。だったら自分で調べるしか無いよね、ということで Google Analytics を導入して実際のアクセスを調査するしか無いのである。

今回は Elm で書いたアプリケーション内のイベントをGA4に送信する実装のお話。

イベントを送信する

素直にタグを記述するだけでページへのアクセスなどは取得できるのだが、そもそもSyncTimerは1ページしか無く、「アクセスがあった」「スクロールした」くらいの情報やOS,ブラウザの種類などが取れる程度なので、実際にタイマーを動かしたかを知りたい場合はイベントを送信する必要がある。

GA4 - イベントを設定する

Elm側で実行されたイベントを送信するには、Elmコードの外にある gtag() 関数を呼び出す必要があるので、ここで Ports という機能を使うことになる。

ポート(Ports) - Elm

簡単に言ってしまえば外部とやり取りする方法で、「外部に文字列(String)を送る」「外部からStringを受け取る」しかない。今回の場合はイベントを文字列で送るのだが、イベントの種類などの構造を持ったデータを送信したいので JSON 形式に変換する関数を作る。

import Json.Encode as E

encodeAnalyticsEvent : String -> String -> String -> Maybe Int -> String
encodeAnalyticsEvent category action label value =
 E.encode 0 <|
 E.object <|
 [ ( "category", E.string category )
 , ( "action", E.string action )
 , ( "label", E.string label )
 ]
 ++ (Maybe.map (\v -> [ ( "value", E.int v ) ]) value |> Maybe.withDefault [])

で、この関数で生成される文字列を port で外部に送信する

port sendAnalyticsEvent : String -> Cmd msg

timerStartEvent : Int -> Cmd msg
timerStartEvent currentTime =
 sendAnalyticsEvent <| encodeAnalyticsEvent "sync_timer" "sync_timer_start" (formatTimeForAnalytics currentTime) Nothing

外部のJSで受け取る方は JSON 文字列をパースして gtag() 関数でイベントを送信する。

app.ports.sendAnalyticsEvent.subscribe((event) => {
 const { category, action, label, value } = JSON.parse(event);
 console.debug({ category, action, label, value });
 if (gtag) {
 const data = Object.assign({
 "event_category": category,
 "event_label": label
 }, value ? { value } : {});
 gtag("event", action, data);
 }
});

という仕組みで送信されている。

おかげで利用状況がある程度わかるようになってきた。

SyncTimerの使い方動画を作りました

2022-03-15T19:00:00+09:00

SyncTimerはシンプルなので、使い方は細かく書かなくても分かってくれるかなーと思ってたので書かなかったが、やはり具体的な使い方を説明したほうがいいかなーと思ったので動画を作って公開した。

おおよその内容は

SyncTimerってどんなタイマーか
設定の変更方法
URLが連動していること
OBSでの使い方の例

といったところ。使う人が迷わないといいな。

続・ランダム生成IDの衝突確率について

2022-02-10T17:25:18+09:00

前回では数学的な側面として誕生日パラドックスに関する確率を求めた。

\[\]

$$ P_{\text{nc}}(n) = \frac{M}{M}\frac{M-1}{M} \dots \frac{M-(n-1)}{M} = \frac{M!}{M^n (M-n)!} $$

$$ P_{\text{c}}(n) = 1 - P_{\text{nc}}(n) = 1 - \frac{M!}{M^n (M-n)!} $$

これは余事象である「一度も衝突しない確率」を求めることで計算したが、余事象を使わずに求めることができるだろうか？

余事象を使わない方法

「 $n$ 回目までに衝突が発生する確率」を求めるには

1回目に「初めて」衝突する確率 $P_\text{fc}(1)$( = 0 )
2回目に「初めて」衝突する確率 $P_\text{fc}(2)$
…
$n$ 回目に「初めて」衝突する確率 $P_\text{fc}(n)$

をそれぞれ求めて足し合わせれば良い。注意すべきポイントはそれぞれの「初めて衝突する事象」が重複していないことである。

具体的に求めていこう。

$n = 1$ ならばどれが選ばれても衝突しないので、

$$ P_\text{fc}(1) = \frac{0}{M} = 0$$

となる。次に $n = 2$ ならば、1つ目は何を選んでもよく、最初に選んだ1つと一致した場合なので、

$$ P_\text{fc}(2) = \frac{M}{M}\frac{1}{M} = \frac{1}{M}$$

となる。続いて、 $n = 3$ ならば、2つ目までは衝突せず、先に選ばれた2つと一致した場合なので、

$$ P_\text{fc}(3) = \frac{M}{M}\frac{M-1}{M}\frac{2}{M}$$

となる。これを $n$ の場合について考えると

$$ P_\text{fc}(n) = \frac{M!}{M^{n-1}(M-(n-1))!}\frac{n-1}{M}$$

となる。したがって求めるべき $n$ 回目までに衝突が発生する確率は

$$ P_{\text{c}}’(n) = \sum_{k=1}^n P_\text{fc}(k) = \sum_{k=1}^n \frac{M!}{M^{k-1}(M-(k-1))!}\frac{k-1}{M}$$

となるはずである。

はたして、 $ P_{\text{c}}(n) = P_{\text{c}}’(n)$ となるだろうか？（一致しないとおかしいはずだが）

一致することを示す

一致することを示そう。

まず、 $ P_\text{nc}(k)$ のときの数式とよく見比べて、形の違う部分 $\frac{k-1}{M}$ に注目し次のように変形する。

$$ \frac{k-1}{M} = \frac{M-M+k-1}{M} = 1 - \frac{M-(k-1)}{M}$$

これにより、 $P_\text{fc}(k)$ は次のように変形できる。

$$ \begin{align*} P_\text{fc}(k) &= \frac{M!}{M^{k-1}(M-(k-1))!}\bigg\{1 - \frac{M-(k-1)}{M}\bigg\} \\ &= \frac{M!}{M^{k-1}(M-(k-1))!} - \frac{M!}{M^k(M-k)!} \end{align*} $$

したがって、総和である $P_{\text{c}}’(n)$ は

$$ P_{\text{c}}’(n) = \sum_{k=1}^n \bigg\{ \frac{M!}{M^{k-1}(M-(k-1))!} - \frac{M!}{M^k(M-k)!} \bigg\} $$

となるが、総和の各項は次のように打ち消すことができる。

$$ \begin{align*} P_\text{fc}(k) + P_\text{fc}(k+1) &= \frac{M!}{M^{k-1}(M-(k-1))!} - \frac{M!}{M^k(M-k)!} + \frac{M!}{M^{k}(M-k)!} - \frac{M!}{M^{k+1}(M-(k+1))!} \\ &= \frac{M!}{M^{k-1}(M-(k-1))!} - \frac{M!}{M^{k+1}(M-(k+1))!} \end{align*} $$

結果として最初と最後だけが残り、次の結果が得られる。

$$ \begin{align*} P_{\text{c}}’(n) &= \sum_{k=1}^n \bigg\{ \frac{M!}{M^{k-1}(M-(k-1))!} - \frac{M!}{M^k(M-k)!} \bigg\} \\ &= 1 - \frac{M!}{M^n(M-n)!} \\ &= P_{\text{c}}(n) \end{align*} $$

よって、一致することが示せた。

別の考え方

$n$ 回目で初めて衝突する確率 $P_\text{fc}(n)$ から $n$ 回目までに衝突が発生する確率 $P_\text{c}(n)$ を計算してみたが、逆に考えることもできる。

$P_\text{fc}(k)$ の変形後の数式を更に変形すると( $P_\text{c}(0)$ は定義されていないため) $k \geq 2$ の場合について次のことがわかる。

$$ \begin{align*} P_\text{fc}(k) &= \frac{M!}{M^{k-1}(M-(k-1))!} - \frac{M!}{M^k(M-k)!} \\ &= \bigg(1 - \frac{M!}{M^k(M-k)!}\bigg) - \bigg(1 - \frac{M!}{M^{k-1}(M-(k-1))!}\bigg) \\ &= P_\text{c}(k) - P_\text{c}(k-1) \end{align*} $$

よく考えればわかることだが、 $n$ 回目で「初めて」衝突する場合というのは「$n$ 回目までに衝突が起こる場合」から「 $n-1$ 回目までに衝突が発生する場合」を取り除いたものに等しく、この変形は納得の行く結果となる。

この結果から改めて $P_{\text{c}}’(n)$ を計算してみると同様の結果が得られる。

$$ \begin{align*} P_{\text{c}}’(n) &= \sum_{k=2}^n\{P_\text{c}(k) - P_\text{c}(k-1)\} + P_\text{fc}(1) \\ &= P_\text{c}(k) - P_\text{c}(1) + P_\text{fc}(1) \\ &= P_\text{c}(k) \end{align*} $$

ランダムに生成したIDが衝突する確率の議論

2022-02-03T20:00:00+09:00

「ランダムなIDをあるパターンに従って生成するとき、どう設計すべきか？」という質問があったので技術的な側面と数学的な側面で説明してみよう。

技術的な側面

そもそも衝突したくないなら典型的な方法として「時間の情報を含めてIDを生成する」という方法があり、 UUIDv1にもタイムスタンプが使われているし、 ULID という選択肢もある。

しかし、UUIDv1はMACアドレスに依存してしまう設計なので現在はほぼ使われていないし、ULIDは最初の10桁がタイムスタンプ情報なので短く詰めることでランダム性を失ったり、IDそのものに特定の構造を定義したいという場合はそのままでは使えない。

今回の質問でも特定の構造が指定された場合の話だったので、シンプルにランダム生成することを前提とした。

もし衝突したら何が問題か

IDの生成直後にすぐDBに保存する仕組みであれば、DBに登録済みか確認し重複している場合には再生成すれば実用上は問題なく使える。（もちろん、衝突が何度も発生するような状況ではパフォーマンスの問題に発展してしまうが）

それでも問題になるのは次のようなケースが考えられる。

一時的にIDを生成しユーザーがデータを入力したタイミングでDBに保存するため、生成時には重複が検知できない
多数の同時リクエストや冗長構成によって、ほぼ同時にID生成される可能性が高く、DBに保存されていたとして生成時の重複が検知できない可能性がある
- かといってINSERT時のテーブルロックなどをしてしまうとパフォーマンス上の問題となってしまう

そのような状況の解決を図ったID生成方法の実例に Twitter IDs(Snowflake) がある。大規模なサービスではID生成だけでもミッションクリティカルな機能になったりもする。

数学的な側面

\(\)

数学的には「誕生日のパラドックス」が有名である。

$ M $ を生成可能なパターン数とする。例えば 8 桁の数字でランダムな値を作る場合、00000000 から 99999999 までの範囲で $10^8$ 個生成可能である。

このうち、 $n$ 回ランダムに生成したとき「一度でも衝突が発生する確率」を考える。「$ n $ 回目で発生する確率」と読み間違えないように注意してほしい。

余事象の確率で考える

「$n$ 回生成したときに一度でも衝突が発生する」ということを考えたいとき、「$n$ 回生成しても一度も衝突が発生しなかった場合」の余事象を考えれば良い。

「全く衝突が発生しなかった場合」の反対なので、「少なくとも一度は衝突が発生している場合」ということになる。

「$n$ 回生成しても一度も衝突が発生しない確率 $P_\text{nc}(n)$」を求めよう。

$n=1$ ならば、 $M$個中どれが選ばれても衝突することがないので、 $\frac{M}{M} = 1$ (100%)である。

次に $n=2$ ならば、 $M$個中最初に選んだものを除く $M-1$ 個から選ばれても衝突することがないので、 $\frac{M}{M} \frac{M-1}{M}$ である。

このようにして、衝突が発生しない確率が次のように計算できる

$$ P_{\text{nc}}(n) = \frac{M}{M}\frac{M-1}{M} \dots \frac{M-(n-1)}{M} = \frac{M!}{M^n (M-n)!} $$

つまり衝突が発生する確率は全確率 1 から発生しない確率を引いたものとなる。

$$ P_{\text{c}}(n) = 1 - P_{\text{nc}}(n) = 1 - \frac{M!}{M^n (M-n)!} $$

数値計算してみる

Node.js で次のようなコードを実行してみる

const M = 10**8;
let p_nc = 1.0;
let n = 1;

while (p_nc > 0.5) {
 n += 1;
 p_nc *= (M - (n-1)) / M;
}

console.log(`n = ${n}`);

数値計算上の誤差はあるだろうが、計算結果は n = 11775 となる。上記の「8桁の数字」で生成されるIDでは、11,775回生成するだけで衝突が発生する確率が50%を超える結果となる。

では、実際に生成してみて衝突が発生するまでの生成回数を調べてみよう。100回試してみて、その平均値を取ってみる。

const M = 10**8;

function collisionTest() {
 let memo = {};
 let generated = Math.ceil(Math.random() * M);
 while (!memo[generated]) {
 memo[generated] = true;
 generated = Math.ceil(Math.random() * M);
 }
 return Object.keys(memo).length;
}

const trial = 100;
const results = [...Array(trial).keys()].map(() => collisionTest());
const average = results.reduce((a,b) => a+b) * 1.0 / trial;
console.log(`average = ${average}`);

average = 11866.35 という結果になる。ランダムなので実行ごとにばらつきはあるが、平均値が上記の50%の確率で衝突する値に近いことがわかる。

実用的な範囲は？

実用性を考えると、衝突確率が1%未満である安全性の高い範囲を考えておきたい。 p_nc > 0.99 と置き換えればその値は計算でき、 n = 1419 である。設計するサービスが1,000個未満のIDで運用できるなら衝突する可能性はかなり少ないだろうが、それを超え始めると度々衝突が発生することも考えられるため、サービスのスケールを見積もりながら安全な範囲を計算すると良い。

一例として、先程の確率計算を関数化したものを使ってみる。

/**
 * max_ids: 生成可能なIDの数
 * p_under: 衝突確率がこれ以下である最大値を求める (0以上1未満の値を指定)
 */
function collisionSafe(max_ids, p_under) {
 let p_nc = 1.0;
 let n = 1;

 while (p_nc > 1 - p_under) {
 n += 1;
 p_nc *= (max_ids - (n-1)) / max_ids;
 }

 return n;
}

collisionSafe(10**8, 0.01); // => 1419
collisionSafe(10**9, 0.01); // => 4484
collisionSafe(10**10, 0.01); // => 14179

まとめ

「誕生日のパラドックス」の解説にもあるように、「思ったより少ない生成個数で衝突が発生しやすい」ということを意識して、ランダムなIDを生成すると良い。

同時視聴配信用のタイマーを作った話

2021-08-16T16:43:12+09:00

作ったものはこちら

https://sync-timer.netlify.app/

ソースコードはこちら

https://github.com/mather/simple-stopwatch

経緯

きっかけは 2020 年 8 月にとある VTuber の同時視聴配信でつぶやかれた一言。

以前VTuberの磁富モノエさん( @Jitomi_Monoe )の Nintendo Direct 同時視聴配信で「マイナスからスタートするストップウォッチがほしい」って話があったから、最近Elmを書いてなかったから試しに作ってみた。https://t.co/kCVSEZBV0C
— mather / Eisuke Kuwahata (@mather314) August 8, 2020

誰かに使われる予定もなく自己満足で開発を終え早一年…。

本当はグリーンバックとか入れたほうがいいのかな、とか考えながらやり残した感はあったのですが、細かく実装を追加してもどうせ使わないかと思うのでとりあえず放置していた。

そんな折、きっかけとなった VTuber の方も突然の引退…。「推しは推せるときに推しておけ」とはこのこと。

しかし、そういったイベントとは一切関係なく開発意欲は突然湧き上がってくるもので、

使い慣れてたので Tailwind CSS を使ってたけど、1 ページだけのアプリに Tailwind はやりすぎ感があった
Elm アプリに対してもっと簡単に導入できる CSS はないだろうかと考えてた
- 最近 Pico.css というものの存在を知って使ってみたくなった
どうせ開発するならグリーンバックとか作っちゃえ
どうせ開発するならヘルプとか作って使いやすくしたい

と週末に思いついたことをガンガン作ってみた。

ひとまず、やりたいことはやったかな。あとはもし誰かからフィードバックがあったら考えよう。

技術について

言語、フレームワークなど技術的な要素は次のようなものです。

Elm 0.19.1
- 関数型プログラミング言語
- TEA (The Elm Architecture)
- 0.19.0 がリリースされたのが 2018 年。 0.19.1 が 2019 年。なんかもうこれで慣れてきた。
- 未体験の方はぜひ一度触ってみて欲しい。エラーメッセージの丁寧さは群を抜いている。
Pico.css master(2021-08-13)
- ミニマル CSS フレームワーク
- div とかではなく main, section, article など適切な HTML を書くことで自然にスタイルが適用されるように設計されている
Parcel 2
- 設定ファイルの（ほぼ）不要なビルドツール
- Elm にも対応している
- 昨年の段階で使っていた v1 が非推奨になったので v2 へ変更したが、 2.0.0-rc.0 が最新だった。正式版をリリースしてから旧バージョンを非推奨にしたほうが良いのでは…？
Netlify
- Github と連携すると Github Actions なしでもある程度の CI, CD を行ってくれるホスティングサービス
- 静的ホスティングだけなら 10 サイトまで無料で公開できる

振り返って

ユーザーテストをしていない

本来ならちゃんと動いて満足行く出来になっているかユーザーにテストしてもらいたいのだが、そもそもユーザーを捕まえてテストしようとしていない。

誰か使ってみてくれないか。

Elm と CSS

関数型プログラミング言語のため、 elm-css などで型付きの CSS 記述(CSS-in-JS)をするなどの選択肢も考えられる。

今回は CSS フレームワークに乗っかって手軽に書きたいという考えで、敢えて CSS を分離することにしてみた。個人的にはこれもありだと感じている。

技術を試す

不利益をもたらさない小さなサービスで新しい技術要素や実験的な試みをするのは大事だと改めて思った。

小ネタ

タイマーのフォントは「D-DIN」。きっかけとなった VTuber の初回配信のカウントダウンに使われているフォント（だと思う）。

自分が感じる東京と宮崎の勉強会の違い

2019-12-09T14:01:16+09:00

宮崎 IT 関連勉強会 Advent Calendar 2019 9 日目の記事です。投稿がものすごく遅れてしまい申し訳ない…。

数年前まで東京でお仕事をしていたときにも勉強会に参加していたのですが、宮崎でも積極的に勉強会に参加するようになって思ったことをつらつらと書いてみます。

東京の場合

まずはそもそもエンジニアを含む人口密度が大きいために、勉強会の開催数や参加人数がものすごく多いです。そのため、こんなことが起こります。

細分化 : 地域型、専門化、ニッチな領域の勉強会
参加枠が埋まりやすいためとりあえずで登録する人がいるため、キャンセル率がそれなりに高く、キャンセル連絡もなく来ないケースも多い
ピラミッド構造 : エヴァンジェリスト、積極的にコミュニティ運営する人、ある程度質問などをする人、聞くだけの人などに分かれやすい

宮崎の場合

エンジニアの人口密度が低いです。そのため、当然ながら勉強会の開催頻度もそこまで多くないです。東京の場合とは逆に次のような状況です。

総合化 : 各回でテーマはそれなりに決めるけど、細かすぎず参加しやすいテーマを選ぶ傾向がある
キャンセル率が低い（これは僕も結構驚き）
ある程度定番の登壇者や LT 登壇者がいる
多くても 30 人程度なので、参加者の顔が認識しやすく、質問とかはしやすい
ゆるふわ

まとめ

僕自身は良い悪いということを論じるつもりはなく、人口密度の違いによってコミュニティの形は自然とこのような違いになっていくんだと思います。

宮崎は点と点の結びつきでアットホームなコミュニティが形成されている面白い場所だと感じています。そのようなコミュニティをより盛り上げていくために、会社という枠を超えたところでエンジニア同士の会話や意見交換を楽しむ場として勉強会の形を模索していくことになるでしょう。

これからは地方を拠点として活動するエンジニアの幅も大きくなってきて、ワーケーションとかフルリモートで活動される方も増えてくると思います。そのような方々と接点を作る場としても、定期開催（または随時思いつきで開催）される勉強会を積極的に作っていきたいですね。

ポートフォリオサイトを Hugo で Github Pages + Github Actions で構築する話

2019-12-07T23:57:04+09:00

宮崎 IT 関連勉強会 Advent Calendar 2019 8 日目の記事です。

皆さん、Github 活用してますか？

Github には Github Pages という機能があり、静的サイトのホスティングを行うことができます。特に、 [アカウント名].github.io という名前のリポジトリの場合はドメイン直下のページが作成できます。

参考: GitHub Pages サイトの種類

それに加えて、Github Actions が一般に公開されました。これは Push などのイベントをトリガーとしてビルド、テスト、デプロイなどが自動的に実行できる仕組みです。いわゆる CI(継続的インテグレーション)や CD(継続的デプロイ)として機能させることができますし、他にもプルリクのレビュー補助や通知などの機能にも利用できるでしょう。

これらを組み合わせると、以下のようなワークフローが可能になります。

静的サイトジェネレーター(Hugo, Jekyll, etc…) でサイトを作る
ローカルでレビューし、問題なければ指定のブランチにプッシュ
Github Actions でプッシュを検知し、静的サイトをビルド
[アカウント名].github.io の場合、ビルド完了した静的サイトを master ブランチにデプロイ
- それ以外のリポジトリの場合は gh-pages ブランチがデプロイ先となります

今回はこれを Hugo でやってみよう、という話です。

ポートフォリオを作る

Hugo をインストールします。Mac なので Homebrew でインストールできます。

$ brew install hugo

今回は空っぽの Jekyll サイト(5 年ほど前に作って放置してた)を削除して作り直しますので、既存のファイルを削除したあとは以下のように Hugo の初期化を行います。

$ hugo new site . --force

Hugo のテーマはシンプルな hermit にしてみました。個人的にはこのくらい落ち着いた色合いが好みです。

インストール手順はテーマのページに記載されているドキュメントのとおりですので割愛します。

設定ファイルである config.toml はテーマのデモページで適用されているものを参考に自分のページに合わせて編集します。

トップページのメニューはこれから作るパスを考えながら設定します。

[menu]

 [[menu.main]]
 name = "Posts"
 url = "posts/"
 weight = 10

 [[menu.main]]
 name = "About"
 url = "pages/about/"
 weight = 20

以下のコマンドで Hugo のホットリロードサーバーを起動します。

$ hugo server -D

-D は draft: true となっているドラフト記事（本番ではまだ表示しない）もビルドして表示してくれるフラグです。

自己紹介を書く

pages/about/ に自己紹介を掲載するので、以下のコマンドでページを作ります。

$ hugo new pages/about.md

このコマンドで content/pages/about.md が生成されます。生成されたファイルの内容は archetypes/default.md をテンプレートとして生成したものですが、この archetypes/ フォルダには固定ページ向け、ブログ記事向けなどに切り分けたテンプレートも設置できます。

参考: Archetypes | Hugo

生成された Markdown ファイルに内容を記載して保存すると自動的にビルドが行われ、ブラウザで表示している場合は自動的にリロードされます。

表示された内容を確認し、内容に問題がなければ draft: true を削除し git commit しましょう。今回は hugo ブランチを作ってコミットします。

$ git checkout -b hugo
$ git commit -v

Github Actions の準備

リポジトリメニューの Actions を選択すると Github Actions のワークフロー (workflow) を作成できます。

ワークフローを作るときはすでに用意されているワークフローを参考に生成することもできますが、今回は自分で作るので “Set up a workflow yourself” ボタンを押します。

すると YAML ファイルを作成するエディタとマーケットプレイス(Marketplace)が表示されます。エディタではワークフロー定義の文法エラーなどを指摘してくれます。また、Marketplace にはすでに Actions で利用可能なアクションが検索可能な状態になっていますので、目当てのものを探して導入することでワークフローを手軽に構成できます。

今回はエディタ開始時にすでに指定されている actions/checkout@v1 以外に、以下の action を利用します。

peaceiris/actions-hugo@v2.3.0 : Hugo をインストールする
peaceiris/actions-gh-pages@v2.5.1 : Github Pages をデプロイする

これらを使って構成した Workflow は次のようになります。

name: Deploy Github Pages

on:
 push:
 branches:
 - hugo

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout Source
 uses: actions/checkout@v1
 - name: Clone submodule
 run: git submodule update --init --recursive
 - name: Hugo setup
 uses: peaceiris/actions-hugo@v2.3.0
 with:
 # The Hugo version to download (if necessary) and use. Example: 0.58.2
 hugo-version: 0.60.1
 # Download (if necessary) and use Hugo extended version. Example: true
 extended: true
 - name: Build Hugo
 run: hugo -v
 - name: GitHub Pages action
 uses: peaceiris/actions-gh-pages@v2.5.1
 env:
 ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
 PUBLISH_BRANCH: master
 PUBLISH_DIR: ./public

内容は各ステップの name にあるとおりです。

ソースコードをチェックアウト
submodule をチェックアウト ( themes/hermit を submodule で導入したため )
Hugo をインストール
Hugo をビルド
Github Pages へデプロイ

uses ではなく run になっているステップでは、実際にこのコマンドをシェルで実行するだけです。

作成が完了したら “Start Commit” を押してコミットを作成するのですが、直接 master ブランチにコミットするのではなく、 hugo ブランチに作成したいのでプルリクエストを作成する方を選びます。

デプロイキー (Deploy Key) の登録

上記ワークフロー定義の ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }} となっている部分でデプロイキーの指定が必要なのですが、こちらはローカルで SSH 鍵ペアを生成する必要があります。

以下はパスフレーズなしの鍵ペアを作成するコマンドの例です。

$ ssh-keygen -t rsa -b 4096 -f /path/to/key -C "[Githubアカウントのメールアドレス]" -N ""

生成した鍵ペアをリポジトリのメニューから以下のように登録します。

Setting -> Deploy Key -> 公開鍵 (.pub の方) を追加
Setting -> Secrets -> ACTIONS_DEPLOY_KEY というキー名で秘密鍵を登録

これで準備完了です。 hugo ブランチが更新されたら、ワークフローが起動します。

まとめ

やや操作は多くなりましたが、静的サイトジェネレーターを使って Github Pages を自動デプロイする方法が Github だけで完結するのはとても便利だと思います。

ぜひ皆さんもワークフローを作ってみてください。