/* pk-extract.pk - `extract' command.  */

/* Copyright (C) 2020, 2021, 2022, 2023, 2024 Jose E. Marchesi */

/* This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

pk_help_add_topic
  :entry Poke_HelpEntry {
          category = "commands",
          topic = "extract",
          summary = "extract the contents of a mapped value to a mem IOS",
          description ="
Get the bytes corresponding to a given mapped value and create a
memory IO space that contains them.

Synopsis:

  extract :val VALUE [:to IOS_NAME]

Arguments:

  :val (any)
         Mapped value.

  :to (string)
         Name of the memory IO space created to hold the value
         bytes.  If this argument is not specified, or if it is
         the empty string, then an unique name is generated.

If the given value is not mapped `extract' raises E_map.

See `.doc extract' for more information."
         };

fun extract = (any val, string to = "") void:
{
  var notify_p = to == "";

  if (to == "")
    to = pk_get_unique_mem_ios_handler;

  copy :to_ios open ("*" + to + "*") :from val'offset
       :size val'size :to 0#B;
  if (notify_p)
    printf "%v extracted to IOS `%s'\n", val'size, to;
}
