Feature Request: Create file from code block

[svrnm]

Thanks for creating runme! I have been looking for this kind of functionality for a while now.

Many of the markdown files I work with have a structure where the user is asked to create a file and then in some of the next steps this file is used. I could not figure out if runme is already able to do something like this, so that's why I raise this feature request.

A big use case for me would be verification of documentation, as it is right now fairly painful to check if what you write works while wrangling your docs. And with software getting updated docs break sometimes without you realizing it.

Bonus Feature: sometimes docs state "change file X like the following", so updating files would be amazing as well 🤩

Here is an example.md (just making up all the logic):

# Test

Setup sample configuration file `config.yaml`:

```yaml { writeToFile = config.yaml }
- key1: val1
  key2: val2
```

Next, run `myapp` with the custom configuration: 

```shell
./myapp config.yaml
```

When I now execute runme --filename example.md run -a what I would like to happen is:

• The YAML is written into a file called config.yaml in the current working directory
• The ./myapp can use that config.yaml

Or another example:

# Hello World Websever

First create a file `package.json` with the following content:

```json { writeToFile=package.json }

{
  "name": "hello-world-server",
  "license": "Apache-2.0"
}
```

Next, add `express` as a dependency:

```shell
npm install --save express
```

Create file `app.js` with the following content:

```javascript { writeToFile=app.js }
const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})
```

Now you can start your server:

```shell
node app.js
```

Let's add another route to `app.js`:

```javascript { writeToFile=app.js, mode=append, line=8 } 
app.get('/de', (req, res) => {
  res.send('Hallo Welt!')
})
```

Run your server again:

```shell
node app.js
```

Now, if I use runme the following would happen:

• The package.json is created
• express is installed (and added as dependency to package.json)
• The app.js is created
• The app.js is executed
• The app.js is updated
• The app.js is executed again

[christian-bromann]

@svrnm thanks for the feedback 🙏 I love this idea and will bring it to the team.

[sourishkrout]

Hi @svrnm. Thanks again for raising this ticket. Great stuff.

Could you provide us with some background info on what your specific use case is? E.g. is this for a tutorial where a reader/user starts from scratch or are you intending to use it in an existing project as onboarding instructions or something different? I am asking because different approaches might make sense for one or the other. Specifically, whether or not the files need synchronization or are created from scratch every time.

As a workaround in the meantime, you could use bash's heredoc like so. While it's a bit more verbose, it does allow ENV var interpolation inside the heredoc. Please see the screenshot below.

rm -f package.json
cat > package.json << EOF
{
  "name": "hello-world-server",
  "license": "Apache-2.0"
}
EOF

We've been interested in this "window into a file" feature and love seeing users' use cases. Any additional contextual info is much appreciated.

[svrnm]

Could you provide us with some background info on what your specific use case is? E.g. is this for a tutorial where a reader/user starts from scratch or are you intending to use it in an existing project as onboarding instructions or something different? I am asking because different approaches might make sense for one or the other. Specifically, whether or not the files need synchronization or are created from scratch every time.

My need is for tutorials, where people start from scratch and go over individual steps to learn something. For the end-user it would be nice to be able to "click" through things to see them in action quickly, for me as the person writing those tutorials having the capabilities of runme, I would be able to verify that my tutorial is still working as expected (think about version updates of the software you are writing about, or copy edits that move stuff around and by that break something).

To answer the question about file synchronization or not, for me, to begin with a check if a file exists already and then asking if it should be overwritten or not, should be enough.

[sourishkrout]

Thank you, very much appreciate the background information @svrnm.