doc:
  short_help: Download a file.
  help: |
    Download a file, create intermediate destination directories and a user/group if necessary.

    If no 'dest' option is provided, the file will be downloaded into '~/Downloads'.

    This uses the [Ansible get_url module](https://docs.ansible.com/ansible/latest/modules/get_url_module.html), check
    it's help for more details.
  references:
    '``get_url`` Ansible module': https://docs.ansible.com/ansible/latest/modules/get_url_module.html
  examples:
  - title: Download a file into /tmp
    vars:
      url: https://frkl.io/images/frkl-logo-black.svg
      dest: /tmp/logo.svg
  - title: Download a file into ~/Downloads
    vars:
      url: https://frkl.io/images/frkl-logo-black.svg
  - title: Download a file, change owner.
    desc: |
      The user 'freckles' will be create if not availble on the sytem.
    vars:
      url: https://frkl.io/images/frkl-logo-black.svg
      dest: /tmp/logo.svg
      owner: freckles

args:
#  become:
#    doc:
#      short_help: Whether to use root privileges to do the downloading and saving.
#    type: boolean
#    default: false
#    required: false
#    cli:
#      is_flag: true
  url:
    doc:
      short_help: The url to download.
    type: string
    required: true
    cli:
      nargs: 1
      metavar: URL
      param_type: argument
  dest:
    doc:
      short_help: The destination file (or directory).
    type: string
    required: false
    default: ~/Downloads/
    cli:
      metavar: DEST
      show_default: true
  owner:
    doc:
      short_help: The owner of the target file.
    type: string
    required: false
    empty: true
    cli:
      metavar: USER
  group:
    doc:
      short_help: The group of the target file.
    type: string
    required: false
    empty: false
    cli:
      metavar: GROUP
  force:
    doc:
      short_help: Whether to force download/overwrite the target.
    type: boolean
    required: false
    default: false
    cli:
      is_flag: true
  mode:
    doc:
      short_help: The mode the file should have, in octal (e.g. 0755).
    type: string
    required: false
    cli:
      metavar: MODE

meta:
  tags:
  - download
  - web
  - featured-frecklecutable

frecklets:
- folder-exists:
    path: "{%:: if dest.endswith('/') ::%}{{:: dest ::}}{%:: else ::%}{{:: dest | dirname ::}}{%:: endif ::%}"
    owner: '{{:: owner ::}}'
    group: '{{:: group ::}}'
- task:
    become: '{{:: owner | true_if_not_empty ::}}'
  frecklet:
    name: get_url
    type: ansible-module
    desc:
      short: "download '{{:: url ::}}' -> '{{:: dest ::}}'"
      long: |
        Download '{{:: url ::}}' to {{:: dest ::}}.

        {%:: if owner ::%}Change the downloaded files owner to be '{{:: owner ::}}'.{%:: endif ::%}{%:: if group ::%}Change the group for the file to be '{{:: group ::}}'.{%:: endif ::%}
        {%:: if mode ::%}Change the files mode to '{{:: mode ::}}'.{%:: endif ::%}

        {%:: if owner ::%}Use root permissions to do all this.{%:: endif ::%}
      references:
        "'get_url' Ansible module": https://docs.ansible.com/ansible/latest/modules/get_url_module.html
    properties:
      idemportent: true    # we assume the remote file doesn't change
      elevated: '{{:: owner | true_if_not_empty ::}}'
      internet: true
  vars:
    url: '{{:: url ::}}'
    dest: '{{:: dest ::}}'
    owner: '{{:: owner ::}}'
    group: '{{:: group ::}}'
    force: '{{:: force ::}}'
    mode: '{{:: mode ::}}'