Skip to content

[Documentation][2234]update_zos_replace_documentation #2239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 20 commits into
base: dev
Choose a base branch
from
Open

[Documentation][2234]update_zos_replace_documentation #2239

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
cb0671a
Test
AndreMarcel99 Jul 10, 2025
1aca7d0
Change documentation
Aug 14, 2025
6cc4ac8
Add fragment
Aug 14, 2025
a198ca8
Merge branch 'dev' into documentation/2234/improve_zos_replace_docume…
AndreMarcel99 Aug 14, 2025
254bdce
Fix :
Aug 14, 2025
d32fe82
Fix line too long
Aug 14, 2025
4714e2c
Fix content
Aug 14, 2025
7b154bd
Update plugins/modules/zos_replace.py
fernandofloresg Aug 21, 2025
8d8cf87
Update plugins/modules/zos_replace.py
fernandofloresg Aug 21, 2025
d4b4bc2
Apply suggestions from code review
fernandofloresg Aug 21, 2025
e84c153
Modified zos_replace documentation with latest feedback
Aug 22, 2025
222734c
Fixed documentation lint issue
fernandofloresg Aug 22, 2025
600e18d
Fix O for I and new examples
Aug 25, 2025
092731d
Avoid check
Aug 27, 2025
c555448
Fixed a couple of sanity issues
fernandofloresg Aug 31, 2025
3761d7f
Updated doc source
fernandofloresg Aug 31, 2025
487522d
Merge branch 'dev' into documentation/2234/improve_zos_replace_docume…
AndreMarcel99 Sep 1, 2025
3d97e6f
Updated the generated RST
fernandofloresg Sep 3, 2025
5173ef0
Merge branch 'dev' into documentation/2234/improve_zos_replace_docume…
AndreMarcel99 Sep 3, 2025
12f26de
Merge branch 'dev' into documentation/2234/improve_zos_replace_docume…
AndreMarcel99 Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions changelogs/fragments/2239_Update_zos_replace_documentation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
trivial:
- zos_replace_func.py - Update documentation adding default values and add verbosity for after, before and literal options.
(https://github.com/ansible-collections/ibm_zos_core/pull/2239).
58 changes: 40 additions & 18 deletions plugins/modules/zos_replace.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,17 @@
options:
after:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are pending reviews, I can not multi select the entire section of text for after so I am going to offer my rewrite that also updates the URL so there is no version embedded, also makes the latest Ansible markup O(...) and other things like B(bold). This is for the entire after section of text.

  - A regular expression that if specified, determines which content will be replaced or removed B(after) the match.
  - Option O(after) is the start position from where the module will seek to match the O(regexp) pattern. When a pattern is matched, occurrences are substituted with the value set for O(replace).
  - If option O(after) is not set, the module will search from the beginning of the O(target).
  - Option O(after) is a regular expression as described in the L(Python library,https://docs.python.org/3/library/re.html).
  - Option O(after) can be used in combination with O(before). When combined with O(before), patterns are replaced or removed from O(after) until the value set for O(before).
  - Option O(after) can be interpreted as a literal string instead of a regular expression by setting option I(literal=after).

description:
- If specified, only content after this match will be replaced/removed.
- A regular expression that if specified, only content after this match will be replaced/removed.
- I(after) works as the opening bracket for a search block where the module will search for I(regexp) and
if found, replace it with I(replace).
- By default works as a regular expression based on re python library L(re python library,https://docs.python.org/es/3.13/library/re.html).
- Can be used in combination with I(before).
- If I(after) is empty, the module will start searching from the beginning of the file till the line match of I(before).
Within that range, it will look for a match with I(regexp) and replace it with I(replace) if found.
- The I(after) value can be treated as a literal string instead of a regular expression by using the I(literal) option.
- To disable the regex behavior of I(after) only, set the I(literal) option to 'after'.
required: false
default: ''
type: str
backup:
description:
Expand Down Expand Up @@ -63,9 +71,17 @@
type: str
before:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are pending reviews, I can not multi select the entire section of text for before so I am going to offer my rewrite that also updates the URL so there is no version embedded, also makes the latest Ansible markup O(...) and other things like B(bold). This is for the entire before section of text.

  - A regular expression that if specified, determines which content will be replaced or removed B(before) the match.
  - Option O(before) is the end position from where the module will seek to match the O(regexp) pattern. When a pattern is matched, occurrences are substituted with the value set for O(replace).
  - If option O(before) is not set, the module will search to the end of the O(target).
  - Option O(before) is a regular expression as described in the L(Python library,https://docs.python.org/3/library/re.html).
  - Option O(before) can be used in combination with O(after). When combined with O(after), patterns are replaced or removed from O(after) until the value set for O(before).
  - Option O(before) can be interpreted as a literal string instead of a regular expression by setting option I(literal=before).

description:
- If specified, only content before this match will be replaced/removed.
- A regular expression that if specified, only content before this match will be replaced/removed.
- I(before) works as the closing bracket for a search block where the module will search for I(regexp) and
if found, replace it with I(replace).
- By default works as a regular expression based on L(re python library,https://docs.python.org/es/3.13/library/re.html).
- Can be used in combination with I(after).
- If I(before) is empty, the module will start searching from the line that matches I(after) and continue to the end of the file.
Within that range, it will look for a match with I(regexp) and replace it with I(replace) if found.
- The I(before) value can be treated as a literal string instead of a regular expression by using the I(literal) option.
- To disable the regex behavior of I(before) only, set the I(literal) option to 'before'.
required: false
default: ''
type: str
encoding:
description:
Expand All @@ -81,7 +97,10 @@
literal:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are pending reviews, I can not multi select the entire section of text for literal so I am going to offer my rewrite that also updates the URL so there is no version embedded, also makes the latest Ansible markup O(...) and other things like B(bold). This is for the entire literal section of text.

  - If specified, it enables the module to interpret options O(after), O(before) and O(regex) as a literal rather than a regular expression.
  - Option O(literal) uses any combination of V(after), V(before) and V(regexp).
  - To interpret one option as a literal, use O(literal=regexp), O(literal=after) or O(literal=before).
  - To interpret multiple options as a literal, use a list such as C(['after', 'before']) or C(['regex', 'after', 'before'])

description:
- A list or string that allows the user to specify choices "before", "after", or "regexp" as regular strings instead of regex patterns.
- To treat multiple options as literal strings disabling regex, include them in the I(literal) list e.g., C(['before', 'after']).
- To treat only one option as a literal string disabling regex, set I(literal) to one of the choices "before", "after" or "regexp".
required: false
default: []
type: raw
target:
description:
Expand Down Expand Up @@ -112,34 +131,35 @@
- If not set, matches are removed entirely.
required: false
type: str
default: ""
default: ''

notes:
- For supported character sets used to encode data, refer to the
L(documentation,https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/resources/character_set.html).
"""

EXAMPLES = r"""
- name: Replace with blank space on a USS file any occurrences of the regex
- name: Replace 'profile/' pattern from USS file via blank substitution.
zos_replace:
target: /tmp/src/somefile
regexp: 'profile\/'

- name: Replace using after on USS file
- name: Replace regexp match with blank after line match in USS file.
zos_replace:
target: "/tmp/source"
regexp: '^MOUNTPOINT*'
after: export ZOAU_ROOT

- name: Replace a specific line with special character on a dataset after a line
- name: Replace a specific line with special character on a dataset after a line, treating the text specified
for regexp as a literal string and after as regular expression.
zos_replace:
target: SAMPLE.SOURCE
regexp: //*LIB DD UNIT=SYS,SPACE=(TRK,(1,1)),VOL=SER=vvvvvv
replace: //*LIB DD UNIT=SYS,SPACE=(CYL,(1,1))
after: '^\$source base \([^\s]+\)'
literal: regexp

- name: Replace a specific line before a specific sentence with backup
- name: Replace a specific line before a specific sentence with backup, treating the text specified for regexp and before as literal strings.
zos_replace:
target: SAMPLE.SOURCE
backup: true
Expand All @@ -149,7 +169,7 @@
- regexp
- before

- name: Replace some words between two lines with a backup with tmp_hlq
- name: Replace 'var' with 'vars' between matched lines after and before with backup.
zos_replace:
target: SAMPLE.DATASET
tmp_hlq: ANSIBLE
Expand All @@ -160,7 +180,7 @@
after: ^/tmp/source*
before: ^ if*

- name: Replace lines on a GDS and generate a backup on the same GDG
- name: Replace lines on a GDS and generate a backup on the same GDG.
zos_replace:
target: SOURCE.GDG(0)
regexp: ^(IEE132I|IEA989I|IEA888I|IEF196I|IEA000I)\s.*
Expand All @@ -169,7 +189,7 @@
backup: true
backup_name: "SOURCE.GDG(+1)"

- name: Delete some calls to SYSTEM on a member using a backref
- name: Delete 'SYSTEM' calls via backref between matched lines in PDS member.
zos_replace:
target: PDS.SOURCE(MEM)
regexp: '^(.*?SYSTEM.*?)SYSTEM(.*)'
Expand All @@ -183,13 +203,13 @@
description: Name of the backup file or data set that was created.
returned: if backup=true
type: str
sample: /path/to/file.txt.2015-02-03@04:15
sample: "/path/to/file.txt.2015-02-03@04:15"
changed:
description:
Indicates if the source was modified.
returned: always
type: bool
sample: 1
sample: True
found:
description: Number of matches found
returned: success
Expand Down Expand Up @@ -557,28 +577,28 @@ def replace_func(file, regexp, replace, module, uss, literal, encoding="cp1047",
def run_module():
module = AnsibleModule(
argument_spec=dict(
after=dict(type='str'),
after=dict(type='str', default=''),
backup=dict(type='bool', default=False, required=False),
backup_name=dict(type='str', default=None, required=False),
before=dict(type='str'),
before=dict(type='str', default=''),
encoding=dict(type='str', default='IBM-1047', required=False),
target=dict(type="str", required=True, aliases=['src', 'path', 'destfile']),
tmp_hlq=dict(type='str', required=False, default=None),
literal=dict(type="raw", required=False, default=None),
literal=dict(type="raw", required=False, default=[]),
regexp=dict(type="str", required=True),
replace=dict(type='str', default=""),
),
supports_check_mode=False
)
args_def = dict(
after=dict(type='str'),
after=dict(type='str', default=''),
backup=dict(type='bool', default=False, required=False),
backup_name=dict(type='data_set_or_path', default=None, required=False),
before=dict(type='str'),
before=dict(type='str', default=''),
encoding=dict(type='str', default='IBM-1047', required=False),
target=dict(type="data_set_or_path", required=True, aliases=['src', 'path', 'destfile']),
tmp_hlq=dict(type='qualifier_or_empty', required=False, default=None),
literal=dict(type=literals, required=False, default=None),
literal=dict(type=literals, required=False, default=[]),
regexp=dict(type="str", required=True),
replace=dict(type='str', default=""),
)
Expand Down Expand Up @@ -708,6 +728,8 @@ def literals(contents, dependencies):
allowed_values = {"after", "before", "regexp"}
if not contents:
return None
if contents == []:
return None
if not isinstance(contents, list):
contents = [contents]
for val in contents:
Expand Down