txt: ## dist_zef-lizmat-Edit-Files.md
  [![Actions Status](https://github.com/lizmat/Edit-Files/actions/workflows/linux.yml/badge.svg)](https://github.com/lizmat/Edit-Files/actions) [![Actions Status](https://github.com/lizmat/Edit-Files/actions/workflows/macos.yml/badge.svg)](https://github.com/lizmat/Edit-Files/actions) [![Actions Status](https://github.com/lizmat/Edit-Files/actions/workflows/windows.yml/badge.svg)](https://github.com/lizmat/Edit-Files/actions)
  
  # NAME
  
  Edit::Files - edit a given set of files
  
  # SYNOPSIS
  
  ```
  use Edit::Files;
  
  edit-files(@files, :editor<vim>);
  
  ```
  
  # DESCRIPTION
  
  Edit::Files attempts to provide an abstract interface to editing a set of files, with optional line number and column number specifications.
  
  # EXPORTED SUBROUTINES
  
  ## edit-files
  
  ```
  # edit files "foo" and "bar" with vim
  edit-files(<foo bar>, :editor<vim>);
  
  # edit file "foo" at line 42, file "bar" at line 666 with default editor
  edit-files( (foo => 42,  bar => 666) );
  
  # edit file "foo" at line 42, column 3 and file "bar" with default editor
  edit-files( (foo => 42 => 3,  "bar") );
  
  ```
  
  The `edit-files` subroutine slurps the given file specifications and calls the (implicitely) specified editor to edit these files.
  
  The files can be specified in 3 ways:
  
  * just as a filename
  * a Pair with filename as key, and line number as value
  * a Pair with filename as key, and a line number => column Pair as value
  
  The following additional optional named arguments can be specified:
  
  ### :editor
  
  Specifies the editor to be used. Defaults to the contents of `$*EDITOR` or `%*ENV<EDITOR>` or 'vim'.
  
  ### :tag
  
  An optional tag to be added to each location specified. Defaults to `" "` (aka a space).
  
  # SUPPORTED EDITORS
  
  These editors are currently supported:
  
  * vi
  * vim
  * view
  * nvim
  
  # SUPPORTING YOUR OWN EDITOR
  
  ```
  use Edit::Files;
  
  my sub feditor(@specs, $tag) {
      # handle specs
      run 'feditor', ...
  }
  
  edit-files <foo bar>, :editor(&feditor); # edit "foo" and "bar" with "feditor"
  
  ```
  
  You can add your own editor to the list of editors supported by `Edit::Files` by creating a `sub` that accepts an array with file / line / column specifications and a tag to be applied. Then you can specify that subroutine in the `:editor` argument to `edit-files`.
  
  # ADDING AN EDITOR TO THIS DISTRIBUTION
  
  Create a `sub` as described above, and create a [Pull Request](https://github.com/lizmat/Edit-Files/pulls) to have that subroutine added to this distribution.
  
  # CAVEATS
  
  ## Redirected STDIN
  
  If `STDIN` was redirected, then the `$*IN` handle will be closed, and be opened again with a TTY (by opening `/dev/tty`). This may not work on some operating systems, most notably Windows.
  
  # ACKNOWLEDGEMENTS
  
  Thanks to Damian Conway for showing the way to handle multiple files / lines using the compilation error `-q` feature of `vim`.
  
  # AUTHOR
  
  Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)
  
  Source can be located at: <https://github.com/lizmat/Edit-Files> . Comments and Pull Requests are welcome.
  
  If you like this module, or what I’m doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2022, 2025 Elizabeth Mattijsen
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  