Module (RunJS-Utils.mjs) - Add writing functions

[eoureo]

Add functions to Module (RunJS-Utils.mjs) #9

• appendToFile(app, filePath, text)
• writeAtHeading(app, filePath, heading, text, where = "append", deleteBlankLine = false)
• appendAtHeading(app, filePath, heading, text, deleteBlankLine)
• insertAtHeading(app, filePath, heading, text, deleteBlankLine)
• replaceAtHeading(app, filePath, heading, text, deleteBlankLine)

Download the RunJS-Utils.mjs file and put it in the script folder of RunJS. You can change the file name.

Module of frequently used functions in Obsidian-RunJS.
https://gist.github.com/eoureo/e5cb83afac9c9e39d7f909a3cae7ecf2

How to use

Put text in "Heading 1-2-3" of "Test - Add Text.md" file

Test page: pages/Test - Add Text

## Heading 1

### Heading 1-1

#### Heading 1-1-1

#### Heading 1-1-2

### Heading 1-2

#### Heading 1-2-1

#### Heading 1-2-2

#### Heading 1-2-3

### Heading 1-3

## Heading 2

Code: Put the following code inside the code block of the .md file.

```js RunJS="{n:'Examples/Write/append',t:'s'}"
// import { appendAtHeading } from 'Write/writeAtHeading';
import { appendAtHeading } from 'RunJS/Utils';
import { moment } from 'obsidian';

const filePath = "pages/Test - Add Text.md";
const heading = "Heading 1-2-3";
const text = "Hello, World!\n" + moment().format() + "\n";

await appendAtHeading(this.app, filePath, heading, text, true);
// await writeAtHeading(this.app, filePath, heading, text, "append", true);
```

```js RunJS="{n:'Examples/Write/insert',t:'s'}"
// import { insertAtHeading } from 'Write/writeAtHeading';
import { insertAtHeading } from 'RunJS/Utils';
import { moment } from 'obsidian';

const filePath = "pages/Test - Add Text.md";
const heading = "Heading 1-2-3";
const text = "\nHello, World!\n" + moment().format();

await insertAtHeading(this.app, filePath, heading, text, true);
// await writeAtHeading(this.app, filePath, heading, text, "insert", true);
```

```js RunJS="{n:'Examples/Write/replace',t:'s'}"
// import { replaceAtHeading } from 'Write/writeAtHeading';
import { replaceAtHeading } from 'RunJS/Utils';
import { moment } from 'obsidian';

const filePath = "pages/Test - Add Text.md";
const heading = "Heading 1-2-3";
const text = "\nHello, World!\n" + moment().format() + "\n";

await replaceAtHeading(this.app, filePath, heading, text);
// await writeAtHeading(this.app, filePath, heading, text, "replace");
```

Source code (partial)

Here is part of the RunJS-Utils.mjs file:

/**
 * A function that appends text to a file.
 * 
 * @param {App} app - The instance of the Obsidian application.
 * @param {string} filePath - The file path.
 * @param {string} text - The text to append.
 * @returns {Promise<void>} - An asynchronous function that appends text to a file.
 * @example
 * const app = this.app; // new App();
 * const filePath = "path/to/file.md";
 * const text = "New text";
 * await appendToFile(app, filePath, text);
 * console.log("Text successfully appended.");
 */
export async function appendToFile(app, filePath, text) {
  const tFile = app.vault.getAbstractFileByPath(filePath);
  console.log("tFile:", tFile);
  if (tFile instanceof TFile) app.vault.append(tFile, text);
}

/**
 * Writes(append, insert, replace) text at the specified heading in a file.
 * 
 * @param {App} app - The Obsidian application instance.
 * @param {string} filePath - The file path.
 * @param {string} heading - The heading to write at.
 * @param {string} text - The text to write.
 * @param {string} [where="append"] - The position to write: "append", "insert", or "replace".
 * @param {boolean} [deleteBlankLine=false] - Whether to delete a blank line before the inserted text.
 * @returns {Promise<void>} - A promise that resolves when the text has been written.
 */
export async function writeAtHeading(app, filePath, heading, text, where = "append", deleteBlankLine = false) {
  const tFile = app.vault.getAbstractFileByPath(filePath);

  let position;

  if (tFile instanceof TFile) {
    const fileCache = app.metadataCache.getFileCache(tFile);

    for (let h_i = 0; h_i < fileCache.headings.length; h_i++) {
      const cacheHeading = fileCache.headings[h_i];
      if (cacheHeading.heading === heading) {
        const lines = (await app.vault.read(tFile)).split("\n");
        const startLine = cacheHeading.position.start.line + 1;

        if (where === "insert") {
          if (deleteBlankLine && lines[startLine] === "") lines.splice(startLine, 1);
          lines.splice(startLine, 0, text);
        } else {
          let endLine;
          for (let h_i2 = h_i + 1; h_i2 < fileCache.headings.length; h_i2++) {
            const cacheHeadingNext = fileCache.headings[h_i2];
            if (cacheHeading.level >= cacheHeadingNext.level) {
              endLine = cacheHeadingNext.position.start.line - 1;
              break;
            }
          }

          if (endLine === undefined) {
            endLine = lines.length;
          }

          if (where === "replace") {
            lines.splice(startLine, endLine - startLine + 1, text);
          } else {
            // append
            lines.splice(endLine + 1, 0, text);
            if (deleteBlankLine && lines[endLine] === "") lines.splice(endLine, 1);
          }
        }

        await app.vault.modify(tFile, lines.join("\n"));
      }
    }
  }
}

/**
 * Appends text at the specified heading in a file.
 * 
 * @param {App} app - The Obsidian application instance.
 * @param {string} filePath - The file path.
 * @param {string} heading - The heading to append at.
 * @param {string} text - The text to append.
 * @param {boolean} [deleteBlankLine=false] - Whether to delete a blank line before the appended text.
 * @returns {Promise<void>} - A promise that resolves when the text has been appended.
 */
export async function appendAtHeading(app, filePath, heading, text, deleteBlankLine) {
  await writeAtHeading(app, filePath, heading, text, "append", deleteBlankLine);
}

/**
 * Inserts text at the specified heading in a file.
 * 
 * @param {App} app - The Obsidian application instance.
 * @param {string} filePath - The file path.
 * @param {string} heading - The heading to insert at.
 * @param {string} text - The text to insert.
 * @param {boolean} [deleteBlankLine=false] - Whether to delete a blank line before the inserted text.
 * @returns {Promise<void>} - A promise that resolves when the text has been inserted.
 */
export async function insertAtHeading(app, filePath, heading, text, deleteBlankLine) {
  await writeAtHeading(app, filePath, heading, text, "insert", deleteBlankLine);
}

/**
 * Replaces text at the specified heading in a file.
 * 
 * @param {App} app - The Obsidian application instance.
 * @param {string} filePath - The file path.
 * @param {string} heading - The heading to replace at.
 * @param {string} text - The text to replace.
 * @param {boolean} [deleteBlankLine=false] - Whether to delete a blank line before the replaced text.
 * @returns {Promise<void>} - A promise that resolves when the text has been replaced.
 */
export async function replaceAtHeading(app, filePath, heading, text, deleteBlankLine) {
  await writeAtHeading(app, filePath, heading, text, "replace", deleteBlankLine);
}