From f262863188e86756c63e42fdb129dfad6fe98db8 Mon Sep 17 00:00:00 2001 From: duerst Date: Tue, 15 Dec 2015 00:14:17 +0000 Subject: tool/transcode_tablegen.rb: detailled documentation for transcode_tblgen function [ci skip] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@53115 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- tool/transcode-tblgen.rb | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'tool') diff --git a/tool/transcode-tblgen.rb b/tool/transcode-tblgen.rb index 17c5ebf3d4..2c8464b276 100644 --- a/tool/transcode-tblgen.rb +++ b/tool/transcode-tblgen.rb @@ -842,6 +842,43 @@ def transcode_tbl_only(from, to, map, valid_encoding=UnspecifiedValidEncoding) return map, tree_name, real_tree_name, max_input end +# +# call-seq: +# transcode_tblgen(from_name, to_name, map [, valid_encoding_check [, ascii_compatibility]]) -> '' +# +# Returns an empty string just in case the result is used somewhere. +# Stores the actual product for later output with transcode_generated_code and +# transcode_register_code. +# +# The first argument is a string that will be used for the source (from) encoding. +# The second argument is a string that will be used for the target (to) encoding. +# +# The third argument is the actual data, a map represented as an array of two-element +# arrays. Each element of the array stands for one character being converted. The +# first element of each subarray is the code of the character in the source encoding, +# the second element of each subarray is the code of the character in the target encoding. +# +# Each code (i.e. byte sequence) is represented as a string of hexadecimal characters +# of even length. Codes can also be represented as integers (usually in the form Ox...), +# in which case they are interpreted as Unicode codepoints encoded in UTF-8. So as +# an example, 0x677E is the same as "E69DBE" (but somewhat easier to produce and check). +# +# In addition, the following symbols can also be used instead of actual codes in the +# second element of a subarray: +# :nomap (no mapping, just copy input to output), :nomap0 (same as :nomap, but low priority), +# :undef (input code undefined in the destination encoding), +# :invalid (input code is an invalid byte sequence in the source encoding), +# :func_ii, :func_si, :func_io, :func_so (conversion by function with specific call +# convention). +# +# The forth argument specifies the overall structure of the encoding. For examples, +# see ValidEncoding below. This is used to cross-check the data in the third argument +# and to automatically add :undef and :invalid mappings where necessary. +# +# The fifth argument gives the ascii-compatibility of the transcoding. See +# rb_transcoder_asciicompat_type_t in transcode_data.h for details. In most +# cases, this argument can be left out. +# def transcode_tblgen(from, to, map, valid_encoding=UnspecifiedValidEncoding, ascii_compatibility='asciicompat_converter') map, tree_name, real_tree_name, max_input = transcode_tbl_only(from, to, map, valid_encoding) -- cgit v1.2.1