{"id":17799467,"url":"https://github.com/polettix/data-embed","last_synced_at":"2025-06-28T17:08:21.918Z","repository":{"id":25178076,"uuid":"28601247","full_name":"polettix/Data-Embed","owner":"polettix","description":"embed arbitrary data in a file","archived":false,"fork":false,"pushed_at":"2016-04-19T04:46:39.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T04:12:34.019Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polettix.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-29T18:10:40.000Z","updated_at":"2016-01-31T22:14:34.000Z","dependencies_parsed_at":"2022-08-28T23:30:53.476Z","dependency_job_id":null,"html_url":"https://github.com/polettix/Data-Embed","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/polettix/Data-Embed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polettix%2FData-Embed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polettix%2FData-Embed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polettix%2FData-Embed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polettix%2FData-Embed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polettix","download_url":"https://codeload.github.com/polettix/Data-Embed/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polettix%2FData-Embed/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262465789,"owners_count":23315641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-27T12:07:23.044Z","updated_at":"2025-06-28T17:08:21.902Z","avatar_url":"https://github.com/polettix.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nData::Embed - embed arbitrary data in a file\n\n# VERSION\n\nThis document describes Data::Embed version 0.32.\n\n# SYNOPSIS\n\n    use Data::Embed qw\u003c embed embedded \u003e;\n\n    # this is the file where thing will be embedded, at the end\n    my $container = '/path/to/some/file';\n\n    # first of all we embed an external file\n    my $datafile  = '/path/to/data.tar.gz';\n    embed($container, name =\u003e 'data.tar.gz', filename =\u003e $datafile);\n\n    # we can also embed some data, directly\n    use Data::Dumper;\n    my $conf = { ... };\n    embed($container, name =\u003e 'config.yml', data =\u003e Dumper($conf));\n\n    # if the data is in a scalar but it's huge, use filename and\n    # pass a reference to the scalar so no copy will happen\n    my $huge_png = ...;\n    embed($container, name =\u003e 'image.png', filename =\u003e \\$huge_png);\n\n    # to retrieve the stuff, use embedded()\n    my @files = embedded($container);\n\n    # each item in @files is a Data::Embed::File object\n\n    # get whole contents of file\n    my $config_text = $files[1]-\u003econtents();\n\n    # otherwise, you can get a filehandle and use it, e.g. to\n    # dump it on standard output\n    my $data_fh = $files[0]-\u003efh();\n    binmode STDOUT;\n    print {*STDOUT} \u003c$data_fh\u003e;\n\n    # or save the file back, using the available name\n    open my $ofh, '\u003e:raw', $file[2]-\u003ename(); # well, do your checks!\n    my $ifh = $files[2]-\u003efh();\n    while (! eof $ifh) {\n       read $ifh, my $buffer, 4096\n          or last; # do proper checks in production!\n       print {$ofh} $buffer;\n    }\n\n# DESCRIPTION\n\nThis module allows you to manage embedding data at the end of other\nfiles, providing both means for embedding the data ([\"embed\"](#embed) and\n[\"writer\"](#writer)) and accessing them ([\"embedded\"](#embedded) and [\"reader\"](#reader)).\n\nHow can this be helpful? For example, suppose that you want to bring\nsome data along with your perl script, some of which might be binary\n(e.g. an image, or a tar archive), you can embed these data inside the\nperl and then retrieve them. For example, this can be the basis for an\ninstaller.\n\nFor embedding data, you can use the [\"embed\"](#embed) function. See the relevant\ndocumentation or the examples in the [\"SYNOPSYS\"](#synopsys) to use it properly.\n\nFor extracting the embedded data, you can use the [\"embedded\"](#embedded) function\nand access each embedded file as a [Data::Embed::File](https://metacpan.org/pod/Data::Embed::File) object. You can\nthen use its methods `contents` for accessing the whole data, or get a\nfilehandle through `fh` and avoid getting the whole data in memory at\nonce.\n\nNote: the filehandle provided by the `fh` method of\n[Data::Embed::File](https://metacpan.org/pod/Data::Embed::File) is actually a [IO::Slice](https://metacpan.org/pod/IO::Slice) object, so it might not\nsupport all the functions/methods of a regular filehandle.\n\nYou can also access the lower level interface through the two functions\n[\"reader\"](#reader) and [\"writer\"](#writer). See the documentation for\n[Data::Embed::Reader](https://metacpan.org/pod/Data::Embed::Reader) and [Data::Embed::Writer](https://metacpan.org/pod/Data::Embed::Writer).\n\n# FUNCTIONS\n\n## **embed**\n\n    embed($hashref); # OR\n    embed(%keyvalue_pairs);\n\nEmbed new data inside a container file.\n\nParameters can be passed as key-value pairs either directly or through a\nhash reference. The following keys are supported:\n\n- `container`\n\n    shortcut to specifying the same input and output, i.e. the value will be\n    replicated both on the `input` and `output` keys below. Caller still\n    has to ensure that the two are compatible. Provision of a filehandle is\n    currently not supported.\n\n- `input`\n\n    any previous container file to use as base for the generated container.\n    If missing, no previous data will be considered (like starting from an\n    empty file). Can be:\n\n    - the `-` string in a plain scalar, in which case standard input is\n    considered\n    - any other string in a plain scalar, considered to be a file name\n    - a plain reference to a scalar, considered to hold the input data\n    - something that supports the filehandle interface for reading\n\n- `output`\n\n    the target container for the newly generated archive. Might be the same\n    as the input or different; in the latter case, the input will be copied\n    over the output, apart from the bits regarding the management of the\n    inclusions. Can be:\n\n    - missing/undefined or the `-` string in a plain scalar, in which case\n    standard output is used\n    - any other string in a plain scalar, considered to be a file name\n    - a plain reference to a scalar, considered to be the target scalar to\n    hold the data\n    - something that supports the filehandle interface for printing. You\n    should not provide the same filehandle for both input and output, even\n    if you opened it in read-write mode. This limitation might be removed in\n    the future.\n\n- `name`\n\n    the name to associate to the section, optionally. If missing it will be\n    set to the empty string\n\n- `fh`\n\n    the filehandle from where data should be taken. The filehandle will be\n    exausted starting from its current position\n\n- `filename`\n\n    a filename or a reference to a scalar where data will be read from\n\n- `data`\n\n    a scalar from where data will be read. If you have a huge amount of\n    data, it's better to use the `filename` key above passing a reference\n    to the scalar holding the data.\n\nOptions `fh`, `filename` and `data` are exclusive and will be\nconsidered in the order above (first come, first served).\n\nThis function does not return anything.\n\n## **embedded**\n\nGet a list of the embedded files inside a target container. The calling\nsyntax is as follows:\n\n    my $arrayref = embedded($container); # scalar context, OR\n    my @files    = embedded($container); # list context\n\nThe only input parameter is the `$container` to use as input. It can be\neither a real filename, or a filehandle.\n\nDepending on the context, a list will be returned (in list context) or\nan array reference holding the list.\n\nWhatever the context, each item in the list is a [Data::Embed::File](https://metacpan.org/pod/Data::Embed::File)\nobject that you can use to access the embedded file data (most notably,\nyou'll be probably using its `contents` or `fh` methods).\n\n## **generate\\_module\\_from\\_file**\n\n    # when %args includes details for an output channel\n    generate_module_from_file(%args);\n\n    # in case no output is provided in %args:\n    my $text = generate_module_from_file(%args);\n\nGenerate a module's file contents from a file. The module contains code\nof a package that has code to read the included data. Arguments are:\n\n- package\n\n    the name of the package that will be put into the module. This is a\n    mandatory parameter.\n\n- output\n\n    the output channel. If not present, the output will be provided as a\n    string returned by the function, otherwise you can provide\n\n    - a filehandle where the output will be printed\n    - a reference to a scalar (it will be filled with the contents)\n    - the `-` string, in which case the output will be printed\n    to STDOUT\n    - a filename\n\n- output\\_from\\_package\n\n    if this key is present and true, the `output` parameters is overridden\n    and generated automatically from the package name provided in key\n    `package`. The generated file will assume that the file is contained in\n    the _normal_ path under a `lib` directory, e.g. if the package name is\n    `Some::Module` then the generated filename will be\n    `lib/Some/Module.pm`.\n\n- fh\n\n    a filehandle where data will be read from\n\n- filename\n\n    the input will be taken from the provided filename\n\n- dataref\n\n    the input will be taken from the scalar pointed by the\n    reference\n\n- data\n\n    the input is taken from the scalar provided with the data key\n\nInput keys are `fh`, `filename`, `dataref` and `data`. In case\nmultiple of them are present, they will be considered in the order\nspecified.\n\n## **reader**\n\nThis is a convenience wrapper around the constructor for\n[Data::Embed::Reader](https://metacpan.org/pod/Data::Embed::Reader).\n\n## **reassemble**\n\n    # when %args includes details for an output channel\n    reassemble(%args);\n\nReassemble a target container fitting new input sequence. The available\narguments are:\n\n- sequence\n\n    the sequence of items that have to be embedded. Each item can be:\n\n    - a [Data::Embed::File](https://metacpan.org/pod/Data::Embed::File) (e.g. coming from what you read from some other\n    file)\n    - a reference to a hash whose contents is compatible with what expected by\n    [Data::Embed::Writer::add](https://metacpan.org/pod/Data::Embed::Writer::add).\n\n- target\n\n    the target container. It can be:\n\n    - a _filehandle_\n    - a _filename_ (including `-`, that does what you mean)\n    - a _reference to a scalar_\n\n    If the file or reference to a scalar are used, it will make sure to\n    avoid clobbering. In particular, the _prefix_ data (i.e. data that is\n    not part of the list of files) will be preserved.\n\n## **writer**\n\nThis is a convenience wrapper around the constructor for\n[Data::Embed::Writer](https://metacpan.org/pod/Data::Embed::Writer).\n\n# BUGS AND LIMITATIONS\n\nReport bugs either through RT or GitHub (patches welcome).\n\nPassing the same filehandle for both `input` and `output` in [\"embed\"](#embed)\nis not supported. This applies to `container` too.\n\n# SEE ALSO\n\n[Data::Section](https://metacpan.org/pod/Data::Section) covers a somehow similar need but differently. In\nparticular, you should look at it if you want to be able to modify the\ndata you want to embed directly, e.g. if you are embedding some textual\ntemplates that you want to tweak.\n\n# AUTHOR\n\nFlavio Poletti \u003cpolettix@cpan.org\u003e\n\n# COPYRIGHT AND LICENSE\n\nCopyright (C) 2014-2016 by Flavio Poletti \u003cpolettix@cpan.org\u003e\n\nThis module is free software. You can redistribute it and/or modify it\nunder the terms of the Artistic License 2.0.\n\nThis program is distributed in the hope that it will be useful, but\nwithout any warranty; without even the implied warranty of\nmerchantability or fitness for a particular purpose.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolettix%2Fdata-embed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolettix%2Fdata-embed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolettix%2Fdata-embed/lists"}