Script content reactive to form

.gitignore

@@ -7,7 +7,14 @@ Gemfile.lock
 vendor/
 .bundle
 TODO_ja.md
+
+# Site-local runtime files. conf.yml.erb is this deployment's configuration,
+# apps/ holds its applications (apps_dir), and tmp/restart.txt is the Passenger
+# restart trigger. All three are created for the local Docker OnDemand
+# environment by ../docker_open_ondemand/bootstrap.sh; see its README.
 conf.yml.erb
+apps/
+tmp/
 
 # Regenerated from docs by misc/tests/run_tests.rb
 misc/tests/samples/

docs/application.html

@@ -36,7 +36,7 @@ <h5 class="ps-3 pe-1 d-inline">Contents</h5>
         <li class="nav-item ms-3"><a href="#save" class="nav-link">5.2. Save file</a></li>
         <li class="nav-item ms-3"><a href="#hide-script" class="nav-link">5.3. Hide script</a></li>
         <li class="nav-item ms-3"><a href="#variables" class="nav-link">5.4. Special variables</a></li>
-        <li class="nav-item ms-3"><a href="#overwrite_warning" class="nav-link">5.5. Disable warning</a></li>
+        <li class="nav-item ms-3"><a href="#reverse-parse" class="nav-link">5.5. Loading a script back into the form</a></li>
         <li class="nav-item"><a href="#check" class="nav-link">6. Check section</a></li>
         <li class="nav-item"><a href="#submit" class="nav-link">7. Submit section</a></li>
         <li class="nav-item"><a href="#header" class="nav-link">8. Header section</a></li>
@@ -776,23 +776,56 @@ <h3 id="variables">5.4. Special variables</h3>
         <li>#{OC_JOB_NAME}: <code>Job Name</code> defined in the <code>header</code> section</li>
       </ul>
 
-      <h3 id="overwrite_warning">5.5. Disable warning</h3>
+      <h3 id="reverse-parse">5.5. Loading a script back into the form</h3>
       <p>
-        If you try to modify a widget that affects the <code>script</code> or <code>submit</code> section after manually editing those sections, a warning like the one below will appear.
-        If you click "Discard and continue", the changes you made to the section will be discarded and a new script will be generated.
+        If you change any options in the form or header, this changes what is written in the contents script. Likewise, if you change what is written in the contents script, it will be updated if possible in the form or header.
       </p>
-  <img style="border-style: solid; border-width: 1px;" src="img/overwrite_warning.png" width="400" alt="warning">
       <p>
-        To disable this warning, set <code>overwrite_warning: false</code> in the configuration of the section where you want to disable the warning.
+        Three rules govern whether a line can be read back:
+      </p>
+      <ul>
+  <li>It must start with literal text. A line beginning with an interpolation, such as <code>#{command} -n 4</code>, is never matched.</li>
+  <li>That leading text must be unique. Each pattern takes the first script line it matches, so two template lines sharing a prefix will both read the same one.</li>
+  <li>It must not use <code>calc()</code>, <code>dirname()</code> or <code>basename()</code>: those lose information and cannot be reversed. Such a line is still patched in place, but no field is attached to it. <code>zeropadding()</code> is the exception — see the table below.</li>
+      </ul>
+      <p>
+        <code>#SBATCH --time=</code> is handled separately. It is decoded by a dedicated parser accepting every Slurm format (<code>D-HH:MM:SS</code>, <code>D-HH:MM</code>, <code>D-HH</code>, <code>HH:MM:SS</code>, <code>MM:SS</code>, <code>MM</code>), which fills the line's fields with days, hours, minutes and seconds — so they must appear in the template in that order.
+      </p>
+      <p>
+        The captured text is applied according to the widget:
+      </p>
+      <table class="table">
+  <thead>
+    <tr><th>Widget</th><th>Read back from the script</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>number, text, email, path</td><td>Written straight into the input.</td></tr>
+    <tr><td>select, radio</td><td>The option whose value (the second element of its <code>options</code> entry) equals the text is selected.</td></tr>
+    <tr><td>checkbox</td><td>Split on the widget's <code>separator</code>, a comma by default. Matching options are ticked and the rest unticked, so deleting a value from the line clears its box.</td></tr>
+    <tr><td>multi_select</td><td><strong>Not applied.</strong> The badges keep what they held, and an edit to the line is rebuilt from them on the next widget change.</td></tr>
+  </tbody>
+      </table>
+      <p>
+        Of the template functions, only <code>zeropadding()</code> can be read back:
+      </p>
+      <table class="table">
+  <thead>
+    <tr><th>Function</th><th>Read back from the script</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>zeropadding(field, N)</code></td><td>The padded digits are matched and the padding stripped, so <code>run-0125.log</code> puts <code>125</code> in the field. It only pads, so nothing is lost.</td></tr>
+    <tr><td><code>calc()</code></td><td><strong>Not applied.</strong> A result has no single set of inputs: <code>28</code> could be any factor pair.</td></tr>
+    <tr><td><code>dirname()</code>, <code>basename()</code></td><td><strong>Not applied.</strong> Each discards half the path, so the field's value cannot be rebuilt.</td></tr>
+    <tr><td><code>zeropadding(calc(...), N)</code></td><td><strong>Not applied.</strong> The nested <code>calc()</code> is still not reversible.</td></tr>
+  </tbody>
+      </table>
+      <p>
+        A <code>zeropadding()</code> line is only read back when every one of its interpolations is either plain or a bare <code>zeropadding(field, N)</code>, and when the interpolations are separated by literal text. Two captures written side by side, as in <code>#{zeropadding(h, 2)}#{zeropadding(m, 2)}</code>, cannot be split apart again, so such a line is patched but not parsed.
+      </p>
+      <p>
+        Loading a script may also open a hidden section: if a matched field is disabled, the <code>enable-</code> actions controlling it are fired so the section appears with the value already in it. This happens only when no other field could have written the same line. If two fields both write lines starting <code>#$ -o </code>, for instance, a loaded <code>#$ -o out.log</code> could have come from either, so its value is filled in but no section is opened.
       </p>
 
-      <pre>script:
-  overwrite_warning: false
-  content: |</pre>
-
-      <pre>submit:
-  overwrite_warning: false
-  content: |</pre>
       <h2 id="check">6. Check section</h2>
       <p>
   Variables defined in the <code>form</code> section can be validated in the <code>check</code> section using the Ruby language and the function <code>oc_assert(condition, message)</code>.

docs/application_ja.html

@@ -36,7 +36,7 @@ <h5 class="ps-3 pe-1 d-inline">目次</h5>
         <li class="nav-item ms-3"><a href="#save" class="nav-link">5.2. ファイルの保存</a></li>
         <li class="nav-item ms-3"><a href="#hide-script" class="nav-link">5.3. 非表示化</a></li>
         <li class="nav-item ms-3"><a href="#variables" class="nav-link">5.4. 特殊な変数</a></li>
-        <li class="nav-item ms-3"><a href="#overwrite_warning" class="nav-link">5.5. 警告の無効化</a></li>
+        <li class="nav-item ms-3"><a href="#reverse-parse" class="nav-link">5.5. フォームへのスクリプトの読み戻し</a></li>
         <li class="nav-item"><a href="#check" class="nav-link">6. checkセクション</a></li>
         <li class="nav-item"><a href="#submit" class="nav-link">7. submitセクション</a></li>
         <li class="nav-item"><a href="#header" class="nav-link">8. headerセクション</a></li>
@@ -720,22 +720,55 @@ <h3 id="variables">5.4. 特殊な変数</h3>
         <li>#{OC_JOB_NAME}: ヘッダで定義されている<code>Job Name</code></li>
       </ul>
 
-      <h3 id="overwrite_warning">5.5. 警告の無効化</h3>
+      <h3 id="reverse-parse">5.5. フォームへのスクリプトの読み戻し</h3>
       <p>
-        <code>script</code>セクションや<code>submit</code>セクションを手動で変更した後に、それらを変更するウィジットを変更しようとすると、下記のような警告が表示されます。"Discard and continue"をクリックすると、各セクションに加えられた変更は消去され、新しいスクリプトが生成されます。
+        formやheaderの項目を変更すると、それに応じてスクリプトの内容も変更されます。逆に、スクリプトの内容を変更した場合も、可能であればformやheaderの項目が更新されます。
+      </p>
       <p>
-        <img style="border-style: solid; border-width: 1px;" src="img/overwrite_warning.png" width="400" alt="warning">
+        行を読み戻せるかどうかは、次の3つの規則で決まります。
+      </p>
+      <ul>
+  <li>リテラルのテキストで始まること。<code>#{command} -n 4</code>のように補間から始まる行は、決して一致しません。</li>
+  <li>先頭のテキストが一意であること。各パターンは最初に一致したスクリプトの行を使用するため、2つのテンプレートの行が同じ先頭を持つ場合、両方が同じ行を読み取ってしまいます。</li>
+  <li><code>calc()</code>、<code>dirname()</code>、<code>basename()</code>を使用しないこと。これらは情報が失われるため逆算できません。そのような行も所定の位置で書き換えられますが、項目は関連付けられません。<code>zeropadding()</code>は例外です（後述の表を参照）。</li>
+      </ul>
       <p>
-        この警告を無効化するには、無効化したいセクションの設定で<code>overwrite_warning: false</code>を指定します。
+        <code>#SBATCH --time=</code>は個別に扱われます。この行は専用の解析処理で扱われ、Slurmのすべての形式（<code>D-HH:MM:SS</code>、<code>D-HH:MM</code>、<code>D-HH</code>、<code>HH:MM:SS</code>、<code>MM:SS</code>、<code>MM</code>）を受け付けて、その行の項目を日、時、分、秒で埋めます。そのため、これらの項目はテンプレートにこの順序で記述する必要があります。
+      </p>
+      <p>
+        キャプチャされたテキストは、対象のウィジットに応じて適用されます。
+      </p>
+      <table class="table">
+  <thead>
+    <tr><th>ウィジット</th><th>スクリプトからの読み戻し</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>number, text, email, path</td><td>入力欄にそのまま書き込まれます。</td></tr>
+    <tr><td>select, radio</td><td>値（<code>options</code>の要素の2つ目）がテキストと等しい選択肢が選択されます。</td></tr>
+    <tr><td>checkbox</td><td>ウィジットの<code>separator</code>（既定はカンマ）で分割されます。一致する選択肢はチェックされ、それ以外はチェックが外れるため、行から値を削除するとその選択肢のチェックも外れます。</td></tr>
+    <tr><td>multi_select</td><td><strong>適用されません。</strong>バッジは元の状態を保持し、その行への編集は次にウィジットを変更した時点でバッジの内容から再生成されます。</td></tr>
+  </tbody>
+      </table>
+      <p>
+        テンプレートの関数のうち、読み戻せるのは<code>zeropadding()</code>だけです。
+      </p>
+      <table class="table">
+  <thead>
+    <tr><th>関数</th><th>スクリプトからの読み戻し</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>zeropadding(field, N)</code></td><td>桁を埋めた数字に一致し、その埋めた分が取り除かれます。例えば<code>run-0125.log</code>からは<code>125</code>が項目に入ります。桁を埋めるだけなので情報は失われません。</td></tr>
+    <tr><td><code>calc()</code></td><td><strong>適用されません。</strong>計算結果からは元の値の組を一意に定められません。例えば<code>28</code>はどの因数の組でもあり得ます。</td></tr>
+    <tr><td><code>dirname()</code>、<code>basename()</code></td><td><strong>適用されません。</strong>いずれもパスの一部を捨てるため、項目の値を復元できません。</td></tr>
+    <tr><td><code>zeropadding(calc(...), N)</code></td><td><strong>適用されません。</strong>入れ子になった<code>calc()</code>は逆算できないままです。</td></tr>
+  </tbody>
+      </table>
+      <p>
+        <code>zeropadding()</code>を含む行が読み戻されるのは、その行のすべての補間が、単純な補間または<code>zeropadding(field, N)</code>そのものであり、かつ補間どうしがリテラルのテキストで区切られている場合だけです。<code>#{zeropadding(h, 2)}#{zeropadding(m, 2)}</code>のように2つの補間が隣接している場合は分割できないため、その行は書き換えの対象にはなりますが、読み戻しは行われません。
+      </p>
+      <p>
+        スクリプトの読み込み時には、非表示の区画が開くこともあります。一致した項目が無効になっている場合、その項目を制御する<code>enable-</code>の動作が発火し、値が入った状態で区画が現れます。これは、他のどの項目も同じ行を書き出せない場合にのみ起こります。例えば2つの項目がどちらも<code>#$ -o </code>で始まる行を書き出す場合、読み込まれた<code>#$ -o out.log</code>はどちらの項目のものか判別できないため、値は入力されますが区画は開きません。
       </p>
-
-      <pre>script:
-  overwrite_warning: false
-  content: |</pre>
-
-      <pre>submit:
-  overwrite_warning: false
-  content: |</pre>
 
       <h2 id="check">6. checkセクション</h2>
       <p>

docs/manual.html

@@ -51,14 +51,14 @@ <h2 id="application">3. Application Page</h2>
         <li>The "Script location," "Script name," and "Job name" in the header section specify the "Directory where the job script is stored," "Name of the job script file," and "Job name," respectively. </li>
         <li>The "Cluster name" in the header section  is only displayed if multiple job schedulers are configured. The job script will be submitted to the selected cluster. </li>
         <li>An asterisk next to the label of a web form indicates that it is a required field.</li>
-        <li>If you try to modify a web form with a white background after manually editing the job script, a warning like the one shown below will appear.
-          If you click "Discard and continue", the changes made in the job script will be discarded and a new script will be generated.
-          <p>
-            <img style="border-style: solid; border-width: 1px;" src="img/overwrite_warning.png" width="400" alt="warning">
-          </p>
+        <li>A web form with a white background writes to the job script, and each such form owns one line of it.
+          Changing a form rewrites only that line, so any edits you have made elsewhere in the job script are kept.
+        </li>
+        <li>The reverse also holds: when you edit the job script by hand, the web forms update to match it about half a second after you stop typing.
+          Editing a line that no form owns simply leaves the forms alone.
         </li>
         <li>If the background color of the web form is <span style="background-color:#FFE28A">yellow</span>, it indicates that neither the job script nor the script that performs processing before job submission will be modified.</li>
-        <li>If the background color of the web form is <span style="background-color:#FFCCCC">pink</span>, it indicates that only the script that performs processing before job submission will be modified. If you try to modify these web forms after manually editing that script, the same warning described above will appear.
+        <li>If the background color of the web form is <span style="background-color:#FFCCCC">pink</span>, it indicates that only the script that performs processing before job submission will be modified.
           <p>
             <img src="img/application_page3.png" width="600" alt="Application page">
           </p>

docs/manual_ja.html

@@ -43,14 +43,14 @@ <h2 id="application">3. アプリケーションページ</h2>
         <li>ヘッダの「Script location」と「Script name」と「Job name」は、それぞれ「ジョブスクリプトの保存先ディレクトリ」と「ジョブスクリプトのファイル名」と「ジョブ名」を記述します。</li>
         <li>ヘッダの「Cluster name」は複数のジョブスケジューラを設定している場合のみ表示されます。選択されたクラスタにジョブスクリプトが投入されます。</li>
         <li>Webフォームのラベルにアスタリスクがある場合、それは必須項目であることを表します。</li>
-        <li>ジョブスクリプトを手動で変更した後に、背景色が白色のWebフォームを変更しようとすると、下記のような警告が表示されます。
-          "Discard and continue"をクリックすると、ジョブスクリプトに加えられた変更は消去され、新しいスクリプトが生成されます。
-          <p>
-            <img style="border-style: solid; border-width: 1px;" src="img/overwrite_warning.png" width="400" alt="warning">
-          </p>
+        <li>背景色が白色のWebフォームはジョブスクリプトを変更し、それぞれのフォームがスクリプトの1つの行を担当します。
+          フォームを変更してもその行だけが書き換えられるため、ジョブスクリプトの他の箇所に加えた手動での変更は保持されます。
+        </li>
+        <li>連携は双方向です。ジョブスクリプトを手動で編集すると、入力を止めてから約0.5秒後にWebフォームがその内容に合わせて更新されます。
+          どのフォームも担当していない行を編集した場合は、フォームは変更されません。
         </li>
         <li>Webフォームの<span style="background-color:#FFE28A">背景色が黄色</span>は、ジョブスクリプトおよびジョブ投入前の処理を行うスクリプトを変更しないことを示します。</li>
-        <li>Webフォームの<span style="background-color:#FFCCCC">背景色がピンク</span>は、ジョブ投入前の処理を行うスクリプトのみを変更することを示します。そのスクリプトを手動で変更した後に、これらのWebフォームを変更しようとすると、上記と同様の警告が表示されます。
+        <li>Webフォームの<span style="background-color:#FFCCCC">背景色がピンク</span>は、ジョブ投入前の処理を行うスクリプトのみを変更することを示します。
           <p>
             <img src="img/application_page3.png" width="600" alt="Application page">
           </p>