1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2020, Brian Scholer <@briantist>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8---
9module: win_psscript
10short_description: Install and manage PowerShell scripts from a PSRepository
11description:
12  - Add or remove PowerShell scripts from registered PSRepositories.
13options:
14  name:
15    description:
16      - The name of the script you want to install or remove.
17    type: str
18    required: True
19  repository:
20    description:
21      - The registered name of the repository you want to install from.
22      - Cannot be used when I(state=absent).
23      - If ommitted, all repositories will be searched.
24      - To register a repository, use M(community.windows.win_psrepository).
25    type: str
26  scope:
27    description:
28      - Determines whether the script is installed for only the C(current_user) or for C(all_users).
29    type: str
30    choices:
31      - current_user
32      - all_users
33    default: all_users
34  state:
35    description:
36      - The desired state of the script. C(absent) removes the script.
37      - C(latest) will ensure the most recent version available is installed.
38      - C(present) only installs if the script is missing.
39    type: str
40    choices:
41      - present
42      - absent
43      - latest
44    default: present
45  required_version:
46    description:
47      - The exact version of the script to install.
48      - Cannot be used with I(minimum_version) or I(maximum_version).
49      - Cannot be used when I(state=latest).
50    type: str
51  minimum_version:
52    description:
53      - The minimum version of the script to install.
54      - Cannot be used when I(state=latest).
55    type: str
56  maximum_version:
57    description:
58      - The maximum version of the script to install.
59      - Cannot be used when I(state=latest).
60    type: str
61  allow_prerelease:
62    description:
63      - If C(yes) installs scripts flagged as prereleases.
64    type: bool
65    default: no
66  source_username:
67    description:
68      - The username portion of the credential required to access the repository.
69      - Must be used together with I(source_password).
70    type: str
71  source_password:
72    description:
73      - The password portion of the credential required to access the repository.
74      - Must be used together with I(source_username).
75    type: str
76requirements:
77  - C(PowerShellGet) module v1.6.0+
78seealso:
79  - module: community.windows.win_psrepository
80  - module: community.windows.win_psrepository_info
81  - module: community.windows.win_psmodule
82notes:
83  - Unlike PowerShell modules, scripts do not support side-by-side installations of multiple versions. Installing a new version will replace the existing one.
84author:
85  - Brian Scholer (@briantist)
86'''
87
88EXAMPLES = r'''
89- name: Install a script from PSGallery
90  community.windows.win_psscript:
91    name: Test-RPC
92    repository: PSGallery
93
94- name: Find and install the latest version of a script from any repository
95  community.windows.win_psscript:
96    name: Get-WindowsAutoPilotInfo
97    state: latest
98
99- name: Remove a script that isn't needed
100  community.windows.win_psscript:
101    name: Defrag-Partition
102    state: absent
103
104- name: Install a specific version of a script for the current user
105  community.windows.win_psscript:
106    name: CleanOldFiles
107    scope: current_user
108    required_version: 3.10.2
109
110- name: Install a script below a certain version
111  community.windows.win_psscript:
112    name: New-FeatureEnable
113    maximum_version: 2.99.99
114
115- name: Ensure a minimum version of a script is present
116  community.windows.win_psscript:
117    name: OldStandby
118    minimum_version: 3.0.0
119
120- name: Install any available version that fits a specific range
121  community.windows.win_psscript:
122    name: FinickyScript
123    minimum_version: 2.5.1
124    maximum_version: 2.6.19
125'''
126
127RETURN = r'''
128'''
129