doc:
  short_help: Make sure a file/folder has a certain mode.
  help: |
    Make sure a file/folder has a certain owner/group.

    This will recursively apply the mode change in case the path is a directory.
    If the path does not exist, nothing will be done.

    Root/sudo permissions will be used to do the chmod.
  examples:
  - title: Set the mode of an existing file.
    vars:
      path: /tmp/freckles.sh
      mode: '0775'
    dest: |
      If the file ``/tmp/freckles.sh`` exists, this sets the mode
      to be '0775' (executable). If the file doesn't exist, nothing will be done.
args:
  path:
    doc:
      short_help: the path
    type: string
    required: true
  mode:
    doc:
      short_help: The mode to apply.
    type: string
    required: true
  recursive:
    doc:
      short_help: Whether to apply the changes recursively (if folder).
    required: false
    default: false
    type: boolean

meta:
  tags:
  - filesystem
  - file
  - chmod

frecklets:

- task:
    become: true
    register: __f_stat__
  frecklet:
    name: stat
    type: ansible-module
    properties:
      elevated: true
      internet: false
      idempotent: true
    desc:
      short: "[check stats for '{{:: path ::}}]"
      long: |
        Check stats for path '{{:: path ::}}', save result in internal variable '__f_stat__'.
  vars:
    path: '{{:: path ::}}'
- task:
    become: true
    when: __f_stat__.stat.exists and __f_stat__.stat.isdir
  frecklet:
    name: file
    type: ansible-module
    properties:
      elevated: true
      internet: false
      idempotent: true
    desc:
      short: "change ownership of folder '{{:: path ::}}'"
      long: |
        Check internal variable '__f_stat__' to determine whether '{{:: path ::}}' exists and whether it a file or a folder.

        If {{:: path ::}} exists and is a folder, (as root user) ensure the mode for the folder is '{{:: mode ::}}'{%:: if recursive ::%} (recursively, incl. children){%:: endif ::%}.

  vars:
    path: '{{:: path ::}}'
    mode: '{{:: mode ::}}'
    recurse: '{{:: recursive ::}}'
    state: directory
- task:
    become: true
    when: __f_stat__.stat.exists and not __f_stat__.stat.isdir
  frecklet:
    name: file
    type: ansible-module
    properties:
      elevated: true
      internet: false
      idempotent: true
    desc:
      short: "change ownership of file '{{:: path ::}}'"
      long: |
        Check internal variable '__f_stat__' to determine whether '{{:: path ::}}' exists and whether it a file or a folder.

        As root, ensure '{{:: path ::}}' exists (create an empty one if necessary and set the mode for the file to be '{{:: mode ::}}'.
  vars:
    path: '{{:: path ::}}'
    mode: '{{:: mode ::}}'
    state: file