2010, March 7: Libgettext.cmd 0.7.4 released
Libgettext.cmd version 0.7.4 (the first stable version) has been released for general use. You may download it and take it for a spin.
Libgettext.cmd is a Windows command-line script helper for extracting blocks of text from data files with marked sections.
The library is intended to be "call"ed from a primary script i.e. it is supposed to be used by a user-facing tool or console application. However, it is possible to interact directly with libgettext.cmd through its command line interface.
Libgettext.cmd can extract content from any file with markers that indicate the beginning and end of a block of text. In addition, it has the ability to substitute user supplied or global environment variables into the extracted text before output.
Motivation and goals
Libgettext was derived from the code-base of the Re.cmd project. The driving force behind its existence was the need for a tool that would be used to enable internationalization (I18n) support in the project. Actually, the core functionality to enable I18n was baked into the project. It was only after it looked as though it could be of use to other projects that it was extracted into a reusable library.
The goals of libgettext.cmd are:
- Provide a simple and consistent API to extract blocks of text from a file
- Be easy to maintain and when necessary, extend to add useful functionality
NOTE: If you are an expert at creating usable windows console applications, and using command-line libraries with function calls, then this section is for you. Just follow the three steps below to get started, you may always return to run through the User guide and look at the API documentation. For everyone else, please go to the User guide for an introduction to the library.
- Download the latest version of libgettext.cmd
- Extract the "libgettext.cmd" directory from the distribution archive.
- Follow the instructions in the README file contained in the "libgettext.cmd" directory.
- Download the latest version of libgettext.cmd.
- Extract the "libgettext.cmd" directory
from the distribution archive to an appropriate location.
- If you are just trying it out, you may extract it to a location that is easy to get to -- e.g. "C:\env\libgettext.cmd\".
- If you will be using it in an application you are developing, it is best to place the library in a subdirectory of your application -- e.g. "C:\myapp\libs\libgettext.cmd\".
- Open your console (Windows Start button => click "Run" => type "cmd", without the quotes).
- In the command line, go to the directory that contains the libgettext.cmd script.
- Type "libgettext.cmd :about" at the prompt (without the quotes)
- You should get an output with information about libgettext.cmd
- That's it, you have installed the library and you may now proceed to use it.
Simply extract text from a simple text file.
In its simplest usage scenario, libgettext.cmd can handle any Windows formatted text file -- i.e. the file must have cr + lf line endings. The file must also contain start and end markers for the block of text to be extracted. e.g.:
e.g. file: sometextfile.txt
extract_this: Some text entry in the block all this will be extracted as well.
You may use libgettext.cmd to extract the labeled ("extract_this") text above with:
> libgettext.cmd extract sometextfile.txt extract_this Some text entry in the block all this will be extracted as well.
By default the extraction stops at the first empty line. You will see later how this behaviour may be modified through an additional parameter to the "extract" action.
Let's walk through an example that involves extracting blocks of text from a simple text file.
1. Create the sample data file (simple_text.txt)
Before you proceed, you will need to create a text file like the example below in the same directory as the libgettext.cmd library.
hello_world: This is the usual "hello world" message hello_vars: #? Hello %who%, this message spans multiple lines! This is %what% hello_custom_marker: This is yet another message. It is quite simple really, however, it only ends when the custom end marker is reached. Which is right about now. *** END *** Oops, you should not see this message if the custom end marker was enabled
2. Extract as-is
> libgettext.cmd extract simple_text.txt hello_world This is the usual "hello world" message
3. Extract with variable substitution
If you extract a block of text marked with a label that has substitution enabled ("#?"), libgettext.cmd will handle the substitutions for you. As an example, given a label "label: #?" with a block of text with variable references "%SOME_VAR%", when the extraction is done, the references to variables in the block will be replaced by values from matching global variables or additional keyword parameters supplied to the extract action.
> libgettext.cmd extract simple_text.txt hello_vars "" "who=Amina" "what=awesome!" Hello Amina, this message spans multiple lines! This is awesome!
Note that in the above example, since we did not supply a custom end marker, we had to provide an empty string parameter ("") to the extract action in order to be able to specify the variables for substition.
4. Extract with a custom end marker
> libgettext.cmd extract simple_text.txt hello_custom_marker This is yet another message. It is quite simple really, however, it only ends when the custom end marker is reached. Which is right about now. *** END *** Oops, you should not see this message if the custom end marker was enabled
Since we did not specify an end marker in the above example, libgettext.cmd output everything from the begin marker until it reached an empty line. We can easily fix this by providing an "end" marker.
> libgettext.cmd extract simple_text.txt hello_custom_marker "*** END ***" This is yet another message. It is quite simple really, however, it only ends when the custom end marker is reached. Which is right about now.
Recommended usage pattern
As shown in the "Basic usage" section, it is possible to use libgettext.cmd to output text from adhoc text files with begin/end markers. In an effort to keep libgettext.cmd in sync with modern structured document formats, it understands a subset of the YAML document format.
The steps below will help you understand how you may leverage this awesome document format to standardize any messages output by your script/tool/application.
1. Create the sample data file (messages.yml)
Before you proceed, you will need to create a YAML (.yaml or .yml) file like the example below in the same directory as the libgettext.cmd library.
--- hello_world: Hello World! ... --- current_dir: #? This message simply displays your current directory. it is... %CD% ... --- about: #? This is some information about %LIBGETTEXT_INFO_LONGNAME% %LIBGETTEXT_INFO_SUMMARY% License: %LIBGETTEXT_INFO_LICENSE% ...
NOTE: In YAML, "---" indicates the beginning of a document stream, while "..." indicates the end of a document stream. In this case, those the "..." serves as the end marker for a block of text. The keys ("label: "), in this case, one per block serve as the markers for the beginning of a block.
2. Extract a text block from a basic YAML file
> libgettext.cmd extract messages.yml hello_world "..." Hello World!
3. Extract a text block with variable substitution
> libgettext.cmd extract messages.yml current_dir "..." This message simply displays your current directory. it is... C:\env\libgettext.cmd
4. Extract a text block with multiple global variables substitution
> libgettext.cmd extract messages.yml about "..." This is some information about Libgettext.cmd Extracts blocks of text from a data files with marked sections. License: Simplified BSD License
Libgettext.cmd provides accessors to metainfo about itself.
To display general meta information (copyright, license, etc) about libgettext.cmd::
> libgettext.cmd :about > libgettext.cmd :version
To get details about exit/status codes use the ":xcode" accessor.::
> libgettext.cmd noaction > echo %errorlevel% 3 > libgettext.cmd :xcode %errorlevel% libgettext.cmd: Invalid action
Below is an overview of the libgettext.cmd API.
extract FILE_PATH, START, [END], [VARIABLES...]
|FILE_PATH||in||file containing the block of text to extract|
|START||in||marker for beginning of block to extract|
|[END]||in, optional||end of block, defaults to first empty line|
|[VARIABLES...]||in, optional||variables, specified as "key=value" pairs, to be substituted into extracted block|
:xcode STATUS_CODE [RESULT]
displays the message corresponding to the given status code
displays information about the library. Copyright, license, etc.
returns/displays the version of the library
|Concept and development||Rudy Lattae|
|License||Simplified BSD License|
|Copyright||(c) 2010, Rudy Lattae|
Libgettext.cmd was inspired by and based on www.dostips.com - Function.extractFileSection. http://www.dostips.com/ is a great resource for windows batch script development. You should check it out if you have not already been there.