design discussion

Open timotheecour opened this issue 7 years ago • 1 comments

how about:

myarchive.har:

@DELIMITER:*** (can be anything)
*** hello.txt
Hello, this is a file currently archived in a HAR file.
*** foo/other.txt
This is another file ; assumed to located in foo/other.txt
*** foo/bar/ (trailing `/`means theres a directory; useful if dir is empty)
*** /mydir/other.txt (needs an analog of dmd's `-J=/mydir` to allow HAR to write outside it's output directory
this is a file assumed to be rooted outside of this HAR

har cmd line

$ har myarchive.har -J=/mydir -o /tmp/
#creates these:
/tmp/hello.txt
/tmp/foo/other.txt
/tmp/foo/bar
/mydir/other.txt

$ har myarchive.har -o /tmp/
error: need -J=/mydir

reverse operation:

find . | har - -o myarchive.har

libhar API

module har;

import std.file;

struct Har {
  // read a harInput (itself obtained eg via readText)
  this(string harInput);

  // archive => disk
  void unarchive(string outDir = getcwd);

  // disk => archive
  static Har archive(DirEntry[] entries, bool withFileAttribs);

  DirEntry[] toDirEntries();
}

special cases / syntax

*** "foo/some path with space and \"stuff\".txt"
*** ../bar.txt (does what you'd expect; requires for example -J.. if attempts to write outside of destination dir)
*** target.txt @symlink:source.txt # cf ln -s source.txt target.txt #NOTE: no -J required if source is outside
*** "foo.txt @symlink:bar.txt" (this is to show we use quotes to actually mean a file called `foo.txt @symlink:bar.txt` so there's no ambiguity)
*** foo.txt @chmod:0664 @last_modified_time:<UTCTIME>

file pointers (allows referring to large files or binary data)

NOTE: this is not a symlink, when serialized to disk it'll be a regular file

*** funny_cat_pic.jpg @linked

$ har myarchive.har -o /tmp/
error at myarchive.har:1: need to provide linked `funny_cat_pic.jpg`

$ har myarchive.har -o /tmp/ -L=funny_cat_pic.jpg:myarchive_aux_files/mypic.jpg
#produces:
/tmp/funny_cat_pic.jpg

#also:
-L=funny_cat_pic.jpg:dir/ #same as funny_cat_pic.jpg:dir/funny_cat_pic.jpg
-L=funny_cat_pic.jpg:files.zip # gets corresponding file from files.zip

NOTE: the reverse (unarchive) operation works the same:

find . | har - -o myarchive.har -L=funny_cat_pic.jpg:myarchive_aux_files/mypic.jpg
# will treat all -L arguments as @linked

syntax highlight (allows hints for programs that syntax highlight; by default will use extension)

*** foo.d (assumes syntax is d)
void fun(){}
*** foo.d @syntax:d (can also make it explicit)
void fun(){}
*** BUILD @syntax:python (sometimes it's needed to be explicit)
import foo

NOTE: a leading ```har indicates HAR format

design discussion

har cmd line

libhar API

special cases / syntax

file pointers (allows referring to large files or binary data)

syntax highlight (allows hints for programs that syntax highlight; by default will use extension)

links