datauris 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8b17d925dd560274e1e3a4f21e5caa118762e74c1d5b1e4e07777c9456b64f0f
+  data.tar.gz: 34c7263eea9cd31e1bfede00bb4002d303dc59d7870d3bad620a88a7345d292a
+SHA512:
+  metadata.gz: 509299375bebbc22eee68c3c3a704030df51c1d555a57ee5ff83435b1b5d6a0cf9de75c49d1551f277e89db01280bb7f15dc2f2ddd42cfa9bf3ef7279cef0ce4
+  data.tar.gz: b0aba84982c23968350395e3aedf91e11bf7f31a20566e1262f715f9638fdcf05b91aa2e575f4189ca0d58318f8702de0d587efbd7262d7a0c466a3b8e1e33e9

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+### 1.0.0
+### 0.0.1 / 2023-11-23
+
+* Everything is new. First release

data/Manifest.txt

@@ -0,0 +1,7 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+lib/datauri.rb
+lib/datauris.rb
+lib/datauris/version.rb

data/README.md

@@ -0,0 +1,174 @@
+# Data URI Helpers
+
+datauris - helpers to parse (decode) and build (encode) data uris incl. (strict)base64-encoded/decoded images and more
+
+* home  :: [github.com/s6ruby/rubidity](https://github.com/s6ruby/rubidity)
+* bugs  :: [github.com/s6ruby/rubidity/issues](https://github.com/s6ruby/rubidity/issues)
+* gem   :: [rubygems.org/gems/datauris](https://rubygems.org/gems/datauris)
+* rdoc  :: [rubydoc.info/gems/datauris](http://rubydoc.info/gems/datauris)
+
+
+
+## What are Data URIs?!
+
+Data URI Syntax via [Wikipedia](https://en.wikipedia.org/wiki/Data_URI_scheme):
+
+> The syntax of data URIs is defined in [Request for Comments (RFC) 2397](https://datatracker.ietf.org/doc/html/rfc2397), 
+> published in August 1998, and follows the URI scheme syntax. A data URI consists of:
+>
+>     data:[<mediatype>][;base64],<data>
+> 
+> -  The **scheme**, `data`. It is followed by a colon (`:`).
+> -  An optional **media type**. The media type part may include one or more parameters,
+>    in the format `attribute=value`, separated by semicolons (`;`). 
+>    A common media type parameter is charset, specifying the character 
+>    set of the media type, where the value is from the IANA list of character set names.
+>    If one is not specified, the media type of the data URI is assumed 
+>    to be `text/plain;charset=US-ASCII`.
+> -  An optional **base64 extension** `base64`, separated from the preceding part by a semicolon.
+>    When present, this indicates that the data content of the URI is binary data, encoded in ASCII format using the Base64 scheme for binary-to-text encoding.
+>    The base64 extension is distinguished from any media type parameters 
+>    by virtue of not having a `=value` component and 
+>    by coming after any media type parameters. 
+> -  The **data**, separated from the preceding part by a comma (`,`). 
+>    The data is a sequence of zero or more octets represented as characters. 
+>    The comma is required in a data URI, even when the data part has zero length. 
+>    The characters permitted within the data part include ASCII upper 
+>    and lowercase letters, digits, and many ASCII punctuation and special characters. 
+>    Note that this may include characters, such as colon, semicolon, 
+>    and comma which are delimiters in the URI components preceding the data part. 
+>    Other octets must be percent-encoded. If the data is Base64-encoded, 
+>    then the data part may contain only valid Base64 characters. 
+>    Note that Base64-encoded data: URIs use the standard Base64 character set 
+>    (with `+` and `/` as characters 62 and 63) 
+>    rather than the so-called "URL-safe Base64" character set.
+
+
+
+## Usage
+
+[Parse](#parse) • [Build](#build)
+
+### Parse
+
+
+Let's try and parse the Wikipedia Data URI examples:
+
+``` ruby
+uri = "data:text/vnd-example+xyz;foo=bar;base64,R0lGODdh"
+DataUri.valid?( uri )  
+#=> true
+mediatype, data = DataUri.parse( uri )    ## returns 1) mediatype (+parameters), 2) data
+#=> "text/vnd-example+xyz;foo=bar", "<blob>"
+
+uri = "data:text/plain;charset=UTF-8;page=21,the%20data:1234,5678"
+DataUri.valid?( uri )  
+#=> true
+mediatype, data = DataUri.parse( uri )    ## returns 1) mediatype (+parameters), 2) data
+#=> "text/plain;charset=UTF-8;page=21", "the data:1234,5678"
+
+
+uri = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD/"
+DataUri.valid?( uri )  
+#=> true
+mediatype, data = DataUri.parse( uri )    ## returns 1) mediatype (+parameters), 2) data
+#=> "image/jpeg", "<blob>"
+```
+
+
+
+Let's try the DataUri helpers on inscriptions (that encode the "on-chain" data 
+in Data URIs). A valid inscribe must use a valid data uri in the calldata.
+
+The "useless" (null) minimum - no media-type, and zero-length data - is:
+
+``` ruby
+uri = "data:,"
+
+DataUri.valid?( uri )  
+#=> true
+mediatype, data = DataUri.parse( uri )    ## returns 1) mediatype (+parameters), 2) data
+#=> "", ""
+```
+
+Let's try the (genesis) inscribe no. 0:
+
+``` ruby
+uri = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHV..."
+
+DataUri.valid?( uri )  
+#=> true
+mediatype, data = DataUri.parse( uri )    ## returns 1) mediatype (+parameters), 2) data
+#=> "image/jpeg", "<blob>"
+
+## let's save the jpeg image (blob)
+write_blob( "0.jpeg", data )
+```
+
+and voila!
+
+![](i/0.jpeg)
+
+
+Let's try the inscribe no. 15:
+
+``` ruby
+uri = "data:image/png;base64,/9j/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAAB..."
+
+DataUri.valid?( uri )  
+#=> true
+mediatype, data = DataUri.parse( uri )    ## returns 1) mediatype (+parameters), 2) data
+#=> "image/png", "<blob>"
+
+## let's save the png image (blob)
+write_blob( "15.png", data )
+```
+
+and voila!
+
+![](i/15.png)
+
+
+
+
+### Build
+
+Let's build Data URIs.
+
+```ruby
+uri = DataUri.build( "" )
+#=> "data:,"
+
+uri = DataUri.build( "the data:1234,5678", "text/plain" )
+#=> "data:text/plain,the%20data:1234,5678"
+
+# let's try images
+data = read_blob( "0.jpeg" )
+uri = DataUri.build( data, "image/jpeg" )
+#=> "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHV..."
+
+data = read_blob( "15.png" )
+uri = DataUri.build( data, "image/png" )
+#=> "data:image/png;base64,/9j/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAAB..."
+```
+
+
+
+That's it for now.
+
+
+
+
+## Bonus - More Blockchain (Crypto) Tools, Libraries & Scripts In Ruby
+
+See [**/blockchain**](https://github.com/rubycocos/blockchain) 
+at the ruby code commons (rubycocos) org.
+
+
+## Questions? Comments?
+
+Join us in the [Rubidity (community) discord (chat server)](https://discord.gg/3JRnDUap6y). Yes you can.
+Your questions and commentary welcome.
+
+Or post them over at the [Help & Support](https://github.com/geraldb/help) page. Thanks.
+

data/Rakefile

@@ -0,0 +1,28 @@
+require 'hoe'
+require './lib/datauris/version.rb'
+
+
+Hoe.spec 'datauris' do
+  self.version =  DataUri::VERSION
+
+  self.summary = "datauris gem -  DataUri helpers to parse (decode) and build (encode) data uris incl. (strict) base64-encoded/decoded images and more"
+  self.description = summary
+
+  self.urls    = { home: 'https://github.com/s6ruby/rubidity' }
+
+  self.author  = 'Gerald Bauer'
+  self.email   = 'gerald.bauer@gmail.com'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.extra_deps = [
+  ]
+
+  self.licenses = ['Public Domain']
+
+  self.spec_extras = {
+    required_ruby_version: '>= 2.3'
+  }
+end

data/lib/datauri.rb

@@ -0,0 +1,5 @@
+
+## let's you use require 'datauri'  singular too
+require_relative 'datauri'
+
+

data/lib/datauris/version.rb

@@ -0,0 +1,19 @@
+
+module DataUri
+  MAJOR = 1 ## todo: namespace inside version or something - why? why not??
+  MINOR = 0
+  PATCH = 0
+  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+  def self.version
+    VERSION
+  end
+
+  def self.banner
+    "datauris/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}] in (#{root})"
+  end
+
+  def self.root
+    File.expand_path( File.dirname(File.dirname(File.dirname(__FILE__))) )
+  end
+end

data/lib/datauris.rb

@@ -0,0 +1,211 @@
+
+require 'base64'   ## pull in Base64.strict_encode64/decode64 (standard) module
+require 'uri'      ## pull in URI.decode_uri_component
+
+
+## our own code
+require_relative 'datauris/version'     # let version go first
+
+
+module DataUri
+    REGEX_V0 = %r{
+      \Adata:
+      (?<mediatype>
+        (?<type> .+? / .+? )?
+        (?<parameters> (?: ; .+? = .+? )* )
+      )?
+      (?<base64extension>;base64)?
+      ,
+      (?<data>.*)\z
+    }x
+
+    ## allow type only - why? why not?
+    ## split subtype into [tree prefix] and subtype
+    ##  check if type can include dash (-) - why? why not?
+    ## 
+    ## note: \w =>  A word character 
+    ##               is a character a-z, A-Z, 0-9, including _ (underscore).
+    ##
+    ## official grammar:
+    ##   mime-type = type "/" [tree "."] subtype ["+" suffix]* [";" parameter];
+    ##
+    ## Types
+    ##  The "type" part defines the broad use of the media type. 
+    ##   As of November 1996, the registered types were:
+    ##   application, audio, image, message, multipart, text and video.
+    #    By December 2020, the registered types included the foregoing, 
+    ##   plus font, example, and model.
+    ##
+    ##  An unofficial top-level type in common use is chemical
+
+    ## examples with numbers:
+    #    application/vnd.software602.filler.form+xml
+    #    application/x-shockwave-flash2-preview
+    #    application/vnd.isac.fcs; version="1.0-3.1"
+
+   ## make parameters key/value more strict  - why? why not?
+   ##  e.g. MIME_PARAM_RE = /^;([-\w.+]+)=([^;,]+)/.freeze
+   ##
+   ##  allow  +(plus) or .(dot) in param key - possible?? why? why not?
+
+    REGEX = %r{
+      \A
+      data:
+      (?<mediatype>
+        (?:
+            (?<type> [\w-]+? )  
+             / 
+            (?<subtype> [\w.+-]+? )
+        )?
+        (?<parameters> (?: ; 
+                           [\w.+-]+? 
+                              = 
+                              .+? 
+                        )* 
+        )
+      )?
+      (?<base64extension>;base64)?
+      ,
+      (?<data>.*)
+      \z
+    }x
+
+
+    def self._parse( str ) REGEX.match( str ); end
+
+    def self.parse( str )
+        m = _parse( str ) 
+  
+        if m
+          ## 1) return mediatype (mimetype PLUS optional parameters)
+          ## 2) return data (base64 decoded or not)
+  
+          mediatype = m[:mediatype]  
+          data      = if m[:base64extension]   ## assume base64 encoded
+                         Base64.strict_decode64(m[:data])
+                      else
+                         ## e.g. %20 => space(20)
+                         ##  etc.
+                         ## todo/double check - use a different URI decoder - why? why not?
+                         URI.decode_uri_component(m[:data])
+                      end
+          [mediatype, data]
+        else
+           raise ArgumentError, "invalid datauri - cannot match regex; sorry"
+        end
+    end
+
+
+    def self.valid?( str )
+      m = _parse( str )
+      if m 
+        if m[:base64extension]   ## assume base64
+          begin
+            Base64.strict_decode64(m[:data])
+            true
+          rescue ArgumentError
+            false
+          end
+        else
+          true
+        end
+      else
+        false
+      end
+    end
+
+
+   ###
+   ## fix-fix-fix - use our own encode_uri instead of encode_uri_component
+   ##                 why? keep more chars unescaped
+   ##                   e.g.   ??
+   ## 
+   ##   check about space ( ) - must be encoded - why? why not??
+   ##               comma (,)
+   ##               more from json -  [] or {} or ""
+   ##
+   ## see <https://en.wikipedia.org/wiki/Percent-encoding>
+
+
+   ## RFC 3986 section 2.3 Unreserved Characters (January 2005)
+   ##   A-Z => A	B	C	D	E	F	G	H	I	J	K	L	M	N	O	P	Q	R	S	T	U	V	W	X	Y	Z
+   ##   a-z => a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u	v	w	x	y	z
+   ##   0-9 => 0	1	2	3	4	5	6	7	8	9
+   ##   	-	_	.	~	
+   ##  Other characters in a URI must be percent-encoded.   
+
+   ## RFC 3986 section 2.2 Reserved Characters (January 2005)
+   ##  !	#	$	&	'	(	)	*	+	,	/	:	;	=	?	@	[	]
+   ##
+   ##  what's missing in reserved?  
+   ##              space(20)  and 
+   ##              double quoutes (") and
+   ##              curly bracket ({}), and ??
+   ##
+   ##  note:  Reserved characters that have no reserved purpose in a particular context
+   ##  may also be percent-encoded but
+   ##   are not semantically different from those that are not.
+
+
+   ## add more reserved chars here - to keep verbatim (as literal) and NOT percent-encoded
+   ##   why? why not?
+
+
+    NOT_SAFECHARS_RX = /([^a-zA-Z0-9\-_.~]+)/
+
+    def self.encode_uri( str )
+      encoding = str.encoding
+      str.b.gsub( NOT_SAFECHARS_RX ) do |m|
+        '%' + m.unpack('H2' * m.bytesize).join('%').upcase
+      end.force_encoding(encoding)
+    end
+
+
+    ## base64 - force base64 encoding (instead of "automagic")
+    def self.build( data, type=nil, base64: nil )
+        uri = "data:"
+        uri += type      if type   ## note: allow optional / no type
+        
+        ## puts "  type: #{type.inspect}, base64: #{base64.inspect}"
+
+        ## add more (binary) media types here - why? why not?
+        ##   note svg is text AND an image => image/svg+xml
+        if base64.nil?                   
+            base64 = if type 
+                       if type.start_with?( 'image/svg+xml' )
+                         false
+                       elsif type.start_with?( 'image/') ||
+                             type.start_with?( 'application/octet-stream' )
+                         true
+                       else 
+                         false
+                       end
+                     else # no type (assume text)
+                        false
+                     end
+        end
+
+        if base64    
+            uri += ";base64," + Base64.strict_encode64( data )
+        else
+            ## use encode_uri_component by default - why? why not?
+            ##  space becomes %20
+            ##  :     becomes %3A
+            ##  ,     becomes %2C  and so on
+            uri += "," + encode_uri( data )
+        end   
+    end
+      
+
+
+    ## add alias convenience names - why? why not?
+    class << self 
+      alias_method :is_valid?,   :valid?
+      alias_method :decode,      :parse
+      alias_method :encode,      :build
+    end
+end  # module  DataUri
+
+
+
+puts  DataUri.banner      # say hello

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: datauris
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Gerald Bauer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-11-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: datauris gem -  DataUri helpers to parse (decode) and build (encode)
+  data uris incl. (strict) base64-encoded/decoded images and more
+email: gerald.bauer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/datauri.rb
+- lib/datauris.rb
+- lib/datauris/version.rb
+homepage: https://github.com/s6ruby/rubidity
+licenses:
+- Public Domain
+metadata: {}
+post_install_message:
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: datauris gem -  DataUri helpers to parse (decode) and build (encode) data
+  uris incl. (strict) base64-encoded/decoded images and more
+test_files: []