From 686f63f665750f8395c4c545c446dbde4dc981d2 Mon Sep 17 00:00:00 2001 From: hyung-hwan Date: Wed, 9 Jan 2013 14:10:58 +0000 Subject: [PATCH] updated docs more --- qse/doc/Makefile.am | 3 +- qse/doc/Makefile.in | 3 +- qse/doc/page/awk-embed.md | 29 ++++++ qse/doc/page/mainpage.md | 3 +- qse/doc/page/{sed.doc => sed-cmd.md} | 144 +++++++-------------------- qse/doc/page/sed-embed.md | 15 +++ 6 files changed, 87 insertions(+), 110 deletions(-) rename qse/doc/page/{sed.doc => sed-cmd.md} (74%) create mode 100644 qse/doc/page/sed-embed.md diff --git a/qse/doc/Makefile.am b/qse/doc/Makefile.am index 9b91902c..5fcdf6fa 100644 --- a/qse/doc/Makefile.am +++ b/qse/doc/Makefile.am @@ -11,7 +11,8 @@ EXTRA_DIST = \ page/io.doc \ page/awk-embed.md \ page/awk-lang.md \ - page/sed.doc \ + page/sed-cmd.md \ + page/sed-embed.md \ image/qse-logo.png all: diff --git a/qse/doc/Makefile.in b/qse/doc/Makefile.in index 2ed26db1..7bebaba0 100644 --- a/qse/doc/Makefile.in +++ b/qse/doc/Makefile.in @@ -236,7 +236,8 @@ EXTRA_DIST = \ page/io.doc \ page/awk-embed.md \ page/awk-lang.md \ - page/sed.doc \ + page/sed-cmd.md \ + page/sed-embed.md \ image/qse-logo.png all: all-am diff --git a/qse/doc/page/awk-embed.md b/qse/doc/page/awk-embed.md index 978c582c..97140682 100644 --- a/qse/doc/page/awk-embed.md +++ b/qse/doc/page/awk-embed.md @@ -111,6 +111,10 @@ Creating multiple awk objects Memory Pool ----------- +Locale +------ + + Embedding in C++ ----------------- @@ -122,6 +126,31 @@ less numbers of lines in C++. \includelineno awk21.cpp +Customizing the console I/O is not much different in C++. When using the +QSE::StdAwk class, you can inherit the class and implement these five methods: + + - int openConsole (Console& io); + - int closeConsole (Console& io); + - int flushConsole (Console& io); + - int nextConsole (Console& io); + - ssize_t readConsole (Console& io, char_t* data, size_t size); + - ssize_t writeConsole (Console& io, const char_t* data, size_t size); + +The sample below shows how to do it to use a string as the console input +and store the console output to a string buffer. + + \includelineno awk22.cpp + +Alternatively, you can choose to implement QSE::Awk::Console::Handler +and call QSE::Awk::setConsoleHandler() with the implemented handler. +This way, you do not need to inherit QSE::Awk or QSE::StdAwk. +The sample here shows how to customize the console I/O by implementing +QSE::Awk::Console::Handler. It also shows how to run the same script +over two different data streams in a row. + + \includelineno awk23.cpp + + Changes in 0.6.0 ---------------- diff --git a/qse/doc/page/mainpage.md b/qse/doc/page/mainpage.md index 4df12d12..e1b26e81 100644 --- a/qse/doc/page/mainpage.md +++ b/qse/doc/page/mainpage.md @@ -23,8 +23,9 @@ See the subpages for more information. - @ref installation - @ref awk-lang - @ref awk-embed +- @ref sed-cmd +- @ref sed-embed - @subpage mem "Memory Management" - @subpage cenc "Character Encoding" - @subpage io "I/O Handling" -- @subpage sed "SED Stream Editor" diff --git a/qse/doc/page/sed.doc b/qse/doc/page/sed-cmd.md similarity index 74% rename from qse/doc/page/sed.doc rename to qse/doc/page/sed-cmd.md index a4efafe9..20aaa506 100644 --- a/qse/doc/page/sed.doc +++ b/qse/doc/page/sed-cmd.md @@ -1,114 +1,48 @@ -/** @page sed Stream Editor - -@section sed_contents CONTENTS -- \ref sed_intro -- \ref sed_command - -@section sed_intro INTRODUCTION +QSESED Commands {#sed-cmd} +================================================================================ +Overview +-------- A stream editor is a non-interactive text editing tool commonly used on Unix environment. It reads text from an input stream, stores it to pattern space, manipulates the pattern space by applying a set of editing commands, and writes the pattern space to an output stream. Typically, the input and output streams are a console or a file. -@b QSESED is an embeddable stream editor that supports most of -the conventional sed commands and implements input and output streams as a -callback function: - -- #qse_sed_t - C type that encapsulates a stream editor -- QSE::Sed - C++ class that wraps #qse_sed_t -- QSE::StdSed - C++ child class of QSE::Sed that implements standard input and output streams - -@code -#include -#include -#include - -#ifdef QSE_CHAR_IS_MCHAR -# define xcout std::cout -#else -# define xcout std::wcout -#endif - -int sed_main (int argc, qse_char_t* argv[]) -{ - if (argc < 2 || argc > 4) - { - xcout << QSE_T("USAGE: ") << argv[0] << - QSE_T(" command-string [input-file [output-file]]") << std::endl; - return -1; - } - - QSE::StdSed sed; - - if (sed.open () == -1) - { - xcout << QSE_T("ERR: cannot open - ") << sed.getErrorMessage() << std::endl; - return -1; - } - - if (sed.compile (argv[1]) == -1) - { - xcout << QSE_T("ERR: cannot compile - ") << sed.getErrorMessage() << std::endl; - sed.close (); - return -1; - } - - qse_char_t* infile = (argc >= 3)? argv[2]: QSE_NULL; - qse_char_t* outfile = (argc >= 4)? argv[3]: QSE_NULL; - QSE::StdSed::StdStream stream (infile, outfile); - - if (sed.execute (stream) == -1) - { - xcout << QSE_T("ERR: cannot execute - ") << sed.getErrorMessage() << std::endl; - sed.close (); - return -1; - } - - sed.close (); - return 0; -} - -int qse_main (int argc, qse_achar_t* argv[]) -{ - return qse_runmain (argc, argv, sed_main); -} -@endcode - -@section sed_command COMMAND +Commands +-------- A sed command is composed of: -- line selector (optional) -- ! (optional) -- command code -- command arguments (optional, dependent on command code) + - line selector (optional) + - ! (optional) + - command code + - command arguments (optional, dependent on command code) A line selector selects input lines to apply a command to and has the following forms: -- address - specify a single address -- address,address - specify an address range -- start~step - specify a starting line and a step. - #QSE_SED_STARTSTEP enables this form. + - address - specify a single address + - address,address - specify an address range + - start~step - specify a starting line and a step. + #QSE_SED_STARTSTEP enables this form. An @b address is a line number, a regular expression, or a dollar sign ($) while a @b start and a @b step is a line number. A regular expression for an address has the following form: -- /rex/ - a regular expression @b rex is enclosed in slashes -- \\CrexC - a regular expression @b rex is enclosed in @b \\C and @b C + - /rex/ - a regular expression @b rex is enclosed in slashes + - \\CrexC - a regular expression @b rex is enclosed in @b \\C and @b C where @b C can be any character. It treats the @b \\n sequence specially to match a newline character. Here are examples of line selectors: -- 10 - match the 10th line -- 10,20 - match lines from the 10th to the 20th. -- /^[[:space:]]*$/ - match an empty line -- /^abc$/,/^def$/ - match all lines between @b abc and @b def inclusive -- 10,$ - match the 10th line down to the last line. -- 3~4 - match every 4th line from the 3rd line. + - 10 - match the 10th line + - 10,20 - match lines from the 10th to the 20th. + - /^[[:space:]]*$/ - match an empty line + - /^abc$/,/^def$/ - match all lines between @b abc and @b def inclusive + - 10,$ - match the 10th line down to the last line. + - 3~4 - match every 4th line from the 3rd line. Note that an address range always selects the line matching the first address regardless of the second address; For example, 8,6 selects the 8th line. @@ -289,29 +223,25 @@ Prints the last line. If #QSE_SED_QUIET is on, try $p. - 1!G;h;$!d Prints input lines in the reverse order. That is, it prints the last line first and the first line last. -@code -$ echo -e "a\nb\nc" | qsesed '1!G;h;$!d' -c -b -a -@endcode + + $ echo -e "a\nb\nc" | qsesed '1!G;h;$!d' + c + b + a - s/[[:space:]]{2,}/ /g Compacts whitespaces if #QSE_SED_REXBOUND is on. - C/d:,f3,1/ Prints the third field and the first field from a colon separated text. -@code -$ head -5 /etc/passwd -root:x:0:0:root:/root:/bin/bash -daemon:x:1:1:daemon:/usr/sbin:/bin/sh -bin:x:2:2:bin:/bin:/bin/sh -sys:x:3:3:sys:/dev:/bin/sh -sync:x:4:65534:sync:/bin:/bin/sync -$ qsesed '1,3C/d:,f3,1/;4,$d' /etc/passwd -0 root -1 daemon -2 bin -@endcode -*/ + $ head -5 /etc/passwd + root:x:0:0:root:/root:/bin/bash + daemon:x:1:1:daemon:/usr/sbin:/bin/sh + bin:x:2:2:bin:/bin:/bin/sh + sys:x:3:3:sys:/dev:/bin/sh + sync:x:4:65534:sync:/bin:/bin/sync + $ qsesed '1,3C/d:,f3,1/;4,$d' /etc/passwd + 0 root + 1 daemon + 2 bin diff --git a/qse/doc/page/sed-embed.md b/qse/doc/page/sed-embed.md new file mode 100644 index 00000000..375dc289 --- /dev/null +++ b/qse/doc/page/sed-embed.md @@ -0,0 +1,15 @@ +QSESED Embedding Guide {#sed-embed} +================================================================================ + +Overview +-------- + + +Embedding In C++ +---------------- + +The QSE::Sed and QSE::StdSed classes are provided for C++. The sample here shows +how to embed QSE::StdSed for stream editing. + + \includelineno sed02.cpp +