XYENC/XYDEC helper frames for Xy4+U2 (#1 of 2)

[Carl Distefano cld@xxxxxxxx]

After putting some finishing touches on the routines and
documentation, tinkering with the nomenclature, and filling a gap, I
think these are pretty much done now.

The encode/decode frames, XYENC and XYDEC, are the same as before.
There are now five formatting frames: XYFMT (formerly known as XYTOG,
a 3-way toggle among XPL, "raw" XYENCode and "deep-fried" XYENCode)
and XYFMTA, B, C and D.

The new frames, XYFMTA and XYFMTB, create "parboiled" code, similar
to the output of QDF1.PM in Wally's package. "Parboiled" output is
confined to the Ascii range 32-127, and is therefore suitable for e-
mail. XYFMTA and B have an option to use spaces instead of tab
characters for indentation, and a "failsafe" option to ensure that no
line breaks fall within multicharacter encodings. (A bonus frame,
XPLFMT, adds line breaks to the output of U2 frame ENCODE.)

The verisimilitude of the "deep-fried" code listing (produced by
frames XYFMT and XYFMTC) is, I think, very good, with virtually every
standard XyWrite character, including Speedo chars 256-999, rendered
realistically. "Deep-fried" is decodable only with frame XYDEC, but
running XYFMTD against it makes it "well-done" -- decodable with
XYDEC.COM outside of XyWrite 4, and with frame XYDEC as well.

Here is the documentation. The next post will have the frames.

'%--_XYENCode_start--
'0 checksum 8A9F9248
'02-20-2009 23:59:59
~~~~'^[Add_to_XYWWWEB.INF_--_replace_earlier_ver
sion_of_same]'^'^{xyenc,xydec}'^{xyfmt,xyfmta,xyfmtb,xyfmtc,xy
fmtd}'^{xyrun,xyenc50,xydec50,xyrun50,ifei2}'^'^~XYENCo
de_Helper_Frames_for_XyWrite_IV~_--_C.L.Distefano_rev._
2/20/09'^Encode,_Decode,_Format_and_Execute_XPL_using_Wally_Ba
ss'`s_Amazing_XYENCode_and_XYDECode_Programs'^'^Wally_Bass'`s_
XYENCode_utility_(XYENC.COM)_translates_XPL_programs_into_pure
_Ascii,_for_viewing_in_any_text_editor_or_for_transmission_in_
the_message_body_of_an_e-mail._Its_companion,_XYDECode_(XYDEC.
COM),_returns_an_encoded_program_to_the_original_XPL._White_sp
ace_and_XyWrite_formatting_can_be_added_to_XYENCoded_programs_
to_create_a_structured_listing_that_makes_XPL_easier_to_read_a
nd_debug,_yet_the_listing_remains_fully_decodable._Because_of_
their_blazing_speed,_these_assembly_language_utilities_can_be_
tightly_integrated_with_XyWrite'`s_command_line_(CMline),_as_e
xemplified_by_the_routines_described_below.'^'^~Require
d_External_Programs~'^Download_Wally_Bass'`s_XYENCode_a
nd_XYDECode_package_here'.'^~I~~'JM2.ViewURL'Q2~>http'.//basspad.com/xywr
ite/~'^As_of_this_writing_(2/2/09),_the_current_version
_was_v0.96_(xyenc096.zip)',_download_the_latest_available_vers
ion.'^Situate_XYENC.COM_and_XYDEC.COM_in_the_directory_that_co
ntains_~'^~~~'^~Glo
ssary'._"Flavors"_of_XYENCode~'^"Raw"~IXYENC.COM_output
,_unmodified'^"Parboiled"~IAdds_indentation_(tabs_or_spaces)_a
nd_line_breaks_to_elucidate_program_structure,_but_keeps_code_
in_Ascii_range_32-127,_suitable_for_use_in_e-mail_messages_or_
newsgroup_posts._Decodable_with_frame_XYDEC_or_(when_saved_to_
a_file)_with_XYDEC.COM'^"Well-done"~IAdds_XyWrite_formatting_a
nd_MoDes,_and_substitutes_XyWrite_characters_for_many_XYENC_to
kens_(3-byte_":~<"_for_":'?<",_3-byte_":~>"_for_":'?>",_MoDe_B
Old_"'`~BC_~"_for_"'`BC",_reverse-video_"',~A~"_for_"',A",_etc.)_to_produce_a_listing_that_resem
bles_XPL_code_as_displayed_in_eXPanded_view,_but_with_color_an
d_structure._Decodable_with_frame_XYDEC_or_XYDEC.COM'^"Deep-fr
ied"~ISimilar_to_"well-done",_but_additionally_hides_many_XYEN
C.COM_artifacts_in_embedded_InVisible_statements_to_produce_a_
"lifelike"_display_that_is_almost_indistinguishable_from_real_
XPL._For_example,_"~'`BC_~"_[eXPanded_view'._":~<
MDBO:~>'`BC_:~"]_becomes_"~~BC_~
"_[eXPanded_view'._":~:~BC_:~"],_"',~<
MD79~>A~"_[eXPanded_view'._"',:~A:~"_be
comes_"~~A~"_[eXPanded_view'._":~:~A:~",_etc.,_etc._Decodable_with_frame_XYDE
C_only'^~'^~CMline_Usage~_(all_comma
nds_launched_with_)'^--------------------------------
-------------------'^~Encode/Decode~'^XYENC'^__E
ncode_current_file_or_DeFined_block'^__(Cf._frame_XYENC50)'^XY
ENC/'^__Same_as_XYENC,_except_omit_'`'/--'-XYENCode'-start_and
'^____'`'/--'-XYENCode'-end_boundaries_from_output'^XYDEC'^__D
ecode_current_file,_DeFined_block_or_code_within'^____'`'/--'-
XYENCode'-start_and_'`'/--'-XYENCode'-end_boundaries'^'^~Format/Unformat~_(entire_file_only,_no_DF_block_optio
n)'^XYFMT'^__Convert_from_XPL_to_"raw"_XYENCode,_to_"deep-frie
d"_XYENCode,_and_back_to_XPL_(3-way_toggle)'^XYFMTA'^__Convert
_XPL_to|from_"parboiled"_XYENCode_(toggle)_(See_Note_4,_below,
_for_options)'^XYFMTB'^__Convert_"raw"_XYENCode_to_"parboiled"
_XYENCode_(one_way_only)_(See_Note_4,_below,_for_options)'^XYF
MTA/,XYFMTB/'^__Failsafe_option_for_"parboiled"_code._See_Note
_4,_below.'^XYFMTC'^__Convert_XPL_to|from_"deep-fried"_XYENCod
e_(toggle)_(see_Notes_5_and_7,_below)_'^XYFMTD'^__Convert_"dee
p-fried"_XYENCODE_to|from_"well-done"_XYENCode_(toggle)_(see_N
ote_5_below)'^IFEI2'^__Test_XPL_code_for_balanced_IF...EndIf_s
tatements,_with_option_to_display_"deep-fried"_structured_list
ing'^'^~Run~'^XYRUN'^__Run_(execute)_XYENCoded_f
ile_or_DeFined_block'^__(Cf._frame_XYRUN50)'^'^~Notes~<
MDNM~>'^[1]'._Framenames_XYENC_and_XYENC/_accept_valid_XYENC.C
OM_arguments.'^~Examples'.'^XYENC_45_C___Specify_
45-char_line_width_and_perform_checksum_after_encoding'^XYENC_
L______Bypass_encoding_of_low-order_Ascii_characters'^XYENC_H_
_____Bypass_encoding_of_high-order_Ascii_characters'^XYENC/_B_
____Bypass_encoding_of_both_low-and_high-order_Ascii_character
s',_omit_'-start_and_'-end_boundaries'^~'^See_xyenc-ug.tx
t_or_xyenc-tr.txt,_included_in_the_XYENC_zip_archive,_for_XYEN
C.COM_command-line_options.'^'^[2]'._If_no_line_width_is_speci
fied_with_XYENC[/],_a_width_of_65_characters_is_supplied.'^'^[
3]'._Except_as_noted_below,_frame_XYENC_removes_the_":'?Z"_EOF
_code,_if_present,_from_XYENCoded_output',_deleting_the_EOF_co
de_does_not_interfere_with_decoding._Removing_the_EOF_code_avo
ids_problems_when_decoding_blocks_of_material_taken_from_multi
ple_XyWrite_files,_each_terminating_with_an_EOF_marker._See_~<
MDBU~>Comments_and_Warnings_concerning_End_of_File_(EOF)_Marke
rs~,_in_the_XYENC_User_Guide_(xyenc-ug.txt_or_xyenc-ug.
htm,_included_in_the_XYENC_zip_archive)._Exception'._The_":'?Z
"_code_is_retained_when_the_XYENC_CMline_includes_the_"C"_argu
ment,_which_instructs_XYENC.COM_to_generate_a_CRC32_checksum_t
oken_for_the_encoded_file.__If_the_EOF_code_is_removed_from_th
e_encoding,_the_checksum_will_fail_on_decoding._'^'^[4]'._Opti
ons_with_XYFMTA_and_XYFMTB'.'^A)_By_default,_XYFMTA_and_XYFMTB
_use_the_tab_character_for_indentation._To_indent_with_spaces,
_add_a_numerical_argument_(for_the_number_of_spaces_per_indent
)',_for_example,_to_specify_3_spaces_per_indent_(double_indent
=6_spaces,_etc.)'.'^__XYFMTA_3'^A_value_of_3_works_we
ll_for_viewing_"parboiled"_code_in_Draft_view',_a_value_of_4_m
ay_be_preferable_for_eXPanded_view.'^B)_"Parboiled"_code_may_r
equire_manual_editing._In_particular,_additional_line_breaks_(
CrLf'`s)_may_be_required_to_break_up_long_lines,_e.g.,_before_
pasting_output_code_into_an_e-mail_message._If_you_add_line_br
eaks_manually,_be_sure_not_to_insert_them_inside_of_multichara
cter_encodings,_such_as_'`BC,_:'?256,_',A,_'.126,_etc.,_as_thi
s_will_cause_decoding_to_fail._See_also_paragraph_C),_below.'^
C)_Check_"parboiled"_code_to_ensure_that_it_decodes_properly_b
efore_posting_it_to_a_public_forum,_such_as_the_XyWrite_mailin
g_list._If_decoding_fails,_reformat_the_original_XPL_using_the
_"failsafe"_option,_invoked_by_adding_a_forward_slash_("/")_to
_the_framename'.'^__XYFMTA/_3'^__XYFMTB/'^Fa
ilsafe_ensures_that_no_line_breaks_fall_within_multicharacter_
encodings_(the_usual_cause_of_failed_decoding)._The_trade-off_
is_that_output_may_include_lines_with_arbitrary_or_illogical_l
ine_breaks_and_possibly_unwanted_white_space,_which_must_be_re
moved_manually_to_produce_a_meaningful_listing._For_example,_a
_line_broken_like_this'.'^'^:~I:~I:'?'^'^should_be_changed_to'.'^'^:~I:~I:'?'^'^[5]'._In_order_to_maximize_the_readability_of_"deep-
fried"_XYENCode,_frame_XYFMTC_hides_some_XYENCode_tokens_in_em
bedded_":~"_formatting_deltas_(the_right_bracket,_"]",_
in_the_embedded_command_"marks"_it_as_one_added_by_frame_XYFMT
C)._As_a_result,_the_formatted_code_produced_by_XYFMTC_is_NOT_
directly_decodable,_at_the_DOS_prompt,_with_XYDEC.COM_--_altho
ugh_it_~is~_decodable_in_XyWrite_IV_with_XYDEC_or_XYFMT._Within_the_confines_of_Xy4_this_is_
not_an_issue,_but_if_you_want_to_share_"deep-fried"_code_with_
non-Xy4_users,_modifications_to_the_code_will_be_required._The
se_modifications_are_automated_with_frame_XYFMTD._Issuing'^__X
YFMTD'^against_"deep-fried"_code_removes_the_embedded
_IV_commands,_rendering_output_once_again_decodable_with_XYDEC
%.COM._See_also_Note_6,_below.'^'^[6]'._To_include_formatted_c
ode_(whether_"well-done"_or_"deep-fried")_in_the_message_body_
of_an_e-mail,_you_must_first_re-encode_it_to_pure_Ascii_with_X
YENC._In_contrast,_"parboiled"_code_can_be_e-mailed_w
ithout_further_encoding_(see_Note_4,_above).'^'^[7]'._In_rare_
instances,_XYFMTC_may_produce_unexpected_results_(a/k/a_garbag
e)_when_attempting_to_format_XPL._If_this_happens,_RECAll_your
_file_(RECA)_and_issue_XYFMT_twice_(once_to_
encode,_a_second_time_to_format),_or_XYENC/_followed_
by_XYFMT._Either_of_these_latter_methods_~will
~_work.'^'^~XPL_Usage~'^---------'^~XYENC50_and_XYDEC50'._XYENCode_or_XYDECode_the_string_in_Sav
e/Get_50~'^Examples'.'^'≪SV50,'BC'≫'JM2.xyenc50'Q2',*
',_S/G_50_has_"'`BC"'^'≪SV50,'`BC'≫'JM2.xydec50'Q2',*',_S/G_
50_has_"'BC"'^'^~XYRUN50'._RUN_XYENCoded_XPL_in_Save/Ge
t_50~'^Example'.'^'≪SV50,'`BCHello,'-World'≫'JM2.xyru
n50'Q2',*','^(Decodes_"'`BCHello,'-World"_to_"'BCHello,_World"
,_then_executes_it)'^'^~XYRUN50'._CMline_Programming~'^XYRUN50_can_also_execute_XYENCoded_XPL_from_the_CMline.
_This_is_useful_for_commands_that_include_hard-to-handle_chara
cters.'^Example'.'^SEarch_for_1-byte_Ascii-8_(impossible_to_pu
t_on_the_CMline_in_1-byte_form'|)'.'^XYRUN50_'`BXse'-|:'?H|'`Q
2'^'^Any_of_the_CMline_routines_above_can_be_called_a
s_a_child_process_within_an_XPL_program._For_example'.'^'YD'DP
'JM2.xydec'Q2',*',_XYDECode_paragraph_under_cursor'^'YD'DL'≪S
V50,'≫'JM2.xyenc/'Q2',*',_XYENCode_line_under_cursor'^Note_th
at_on_a_call_to_XYENC,_S/G_50_must_either_be_empty_or_contain_
a_valid_XYENC.COM_argument'|'^When_calling_frame_XYFMTD_as_a_s
ubroutine,_add_"/"_to_the_framename_to_suppress_the_toggle_bac
k_to_Draft+NoMarkers_view'.'^'JM2.xyfmtd/'Q2',*','^'^~B
onus_frame'._XPLFMT~'^Purpose'._Add_(mostly)_logical_li
ne_breaks_to_XPLeNCODE_(XPL_encoded_with_frame_ENCODE)'^Usage'.
_With_cursor_situated_ahead_of_"b-gin"_header'.'^__XPLFMT'^Note'._XPLeNCODE_with_added_line_breaks_remains_complete
ly_decodable_(with_frame_DECODE).'^'^~'^For_use_by_RENUMB
ER.PM'.'^Renumber_all_XYENCode_helper_frames_in_PACK_mode,'^wi
th_OPTIONs_listed_below'.'^'^XYENC*,XYDEC'^Default_S/G_range_=
_01-07',_50'^FREEZE_50'^'^XYFMT'^Default_S/G_range_=_50'^Do_no
t_REnumber'^'^XYFMTA*,XYFMTB*'^Default_S/G_range_=_01-05',_50'^
FREEZE_50'^'^XYFMTC'^Default_S/G_range_=_01-08',_49-50'^FREEZE
_49-50'^'^XYFMTD*'^Default_S/G_range_=_51-54'^Do_not_Renumber'^
'^XYENC50,XYDEC50,XYRUN50'^Default_S/G_range_=_01-04',_50'^FRE
EZE_50'^LEFT$(1)'.__'/'^'^XYRUN'^Default_S/G_range_=_01-04',_5
0'^FREEZE_50'^'^IFEI2'^Default_S/G_range_=_01-05',_50',_96'^FR
EEZE_50_96'^LEFT$_(1)'.__RK'.'^'^~'^-~I-~I-~I-~I-~I-~I-~I
-~I-~I-'^~Z
'%--_XYENCode___end--

--
Carl Distefano
cld@xxxxxxxx