Salt: Document `file.replace` with regexp groups

[JensRantil]

Using file.replace with regexp groups is really useful. However, file.replace doesn't document how/that it can be used. This issue proposes or paragraph is added to document its usage.

[lorengordon]

I vaguely recall we are using regex groups somewhere or other with file.replace. So pretty sure it does. An example would be nice because I remember it being rather complicated to get the syntax right. :smile:

[kevinquinnyo]

You can definitely use groups in your regular expresssion, but if you're wanting to do something with the result of a capture group, you'll have to use file.grep, or cmd.run and issue something like grep yourself.

Someone correct me if I'm wrong here.

Quick example from a minion using salt-call:

# salt-call file.replace /tmp/testfile pattern='foo([0-9]+)bar' repl='this is a nice replacement'
[INFO    ] Determining pillar cache
local:
    --- 
    +++ 
    @@ -1 +1 @@
    -asdfasdf foo123bar asdfasdfasd
    +asdfasdf this is a nice replacement asdfasdfasd

[Ch3LL]

@JensRantil does @kevinquinnyo 's example help to clarify that regex groups can indeed be used? If so we could include this example in the docs. thanks

[JensRantil]

So, would

salt-call file.replace /tmp/testfile pattern='foo([0-9]+)bar' repl='this is a \1 replacement'

work?

[lorengordon]

Figured it was easier just to test it than to speculate. Works like a champ.

# cat foo
bar
baz

# salt-call --local file.replace ~/foo pattern='(bar)' repl='abc \1 abc'
local:
    ---
    +++
    @@ -1,2 +1,2 @@
    -bar
    +abc bar abc
     baz

# cat foo
abc bar abc
baz

[JensRantil]

Perfect. Then this issue proposes to document this.

[rallytime]

@JensRantil I've adjusted the labels/milestone so we can get this documented. Thanks!

[grinapo]

I wholly support it to be documented. I agree with it being documented. I approve. I desire. Long for. If you want, I pray for it. What would you technically need to document it? Is there a repo to file a PR against? A dev to blackmail? Anything...? ;-)

[JensRantil]

@grinapo Feel free to make a pull request to update the help text for file.replace state.

[shallot]

It looks like the file state documentation just needs to point to the relevant file module documentation at https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.file.html#salt.modules.file.replace which says nicely:

pattern
A regular expression, to be matched using Python's search().

and links to https://docs.python.org/3/library/re.html#re.search

It's sometimes obvious to readers that a state called XYZ uses the eponymous module called XYZ, but good documentation shouldn't assume such things, because it will not actually be true at all times.

[boltronics]

The file.replace state documentation now reads:

_pattern
A regular expression, to be matched using Python's search()._

which is the same as the execution module.

That's all that was required to close this, yes? Or did we want an example explicitly demonstrating this behaviour?

[grinapo]

For people who are not using python everyday an example is like water in the middle of the desert. ;-)

[nickgarber]

Here's a working example I produced after reading through this issue:
salt-call state.single file.replace '/etc/security/pam_winbind.conf' pattern='^(require_membership_of = )(.*)$' repl='\1\2,append-new-group-to-line' test=True

This capability is super useful and deserves to be more highlighted!

[rallytime]

@nickgarber If you wanted to add your example to the docs for this, that would be fantastic.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

If this issue is closed prematurely, please leave a comment and we will gladly reopen the issue.

[grinapo]

@stale oh PLEASE.

[stale[bot]]

Thank you for updating this issue. It is no longer marked as stale.

[nickgarber]

I'd suggest that this issue may now be closable.