Version 0.2 Document Revision 1 Copyright © 2011 Codalogic Ltd. IntroductionCodalogic Code Scrapbook is a simple app designed to improve programmer productivity by acting as a repository for commonly used snippets of code that can be easily pasted into a program. Code Scrapbook has a macro expansion feature so that code snippets can be easily customized for a particular usage; for example, capturing the name of a class, or a file. Templates for snippets are defined by the user, and can be added, deleted, modified and organised as the user requires. Contents2.1 - The Data Capture Section 2.1.1 - Specifying single line text input 2.1.2 - Specifying checkbox input 2.1.3 - Specifying radio button input 2.1.4 - Specifying expression pseudo-input 2.1.5 - Specifying map pseudo-input 1 - Screen LayoutOn the left side of the Code Scrapbook app is a tree view which allows selection, addition and removal of snippet templates. Addition and removal of snippet templates is achieved via the right-click context menu associated with the tree view. (Note that each snippet template is stored in its own file and users my find it easier to edit snippet templates directly using their preferred editor rather that using the editor in Code Scrapbook.) Below the tree view on the left-hand side is a button to set options for Code Scrapbook; such as the directories where the snippet templates are stored and whether auto-copying of generated code is enabled. Multiple directories can be specified for storing snippet templates. This enables, for example, for a centralized corporate set of templates to be specified, plus general personal templates, and perhaps project specific templates. The right side of the app allows you to interact with the selected snippet template. This is a tabbed window which allows you to either edit the template, or run the template. When a template is being run, the top part of the screen displays controls that capture information from the user. The information that is captured is specified in the template, and can be text, checkbox results, and/or radio button results. Below this is displayed the expanded snippet with the relevant information captured from the user displayed in it. Code Scrapbook can automatically copy the generated snippet to the clipboard (ready for pasting into another application) when it loses focus, hence there is normally no need to press the "Copy Generated Code" button when you have entered all the required information. The generated snippet can also be saved to a file using the "Save to file..." button. If only part of the generated code is wanted, select that part in the generated code text window before doing a copy or save to file operation. 2 - Defining Templates
Code Scrapbook uses
A
The text.user_name: What is your name . Hello ^user_name$
the text 2.1 - The Data Capture Section
The # This is a comment # The blank line above is ignored text.user_name: What is your name # This is also a comment
The data capture section can specify single line text input, checkbox input and radio button input. The section can also specify Each input specification is defined on its own line and generally has the format: {type of control}.{name of control}:{question}or: {type of control}.{name of control}[{default value}]:{question}For example: checkbox.want_more[yes]: More explanation requiredcreates a checkbox control named want_more , with the label More explanation required and being checked when initially displayed.
2.1.1 - Specifying single line text input
To specify single line text input, set the type of control to text.user_name: User nameor: text.user_name[Super User]: User name
The latter creates a text box named
Text input is actually displayed as a combo box with a history of recently used values associated with the name of the control included in the pull-down. As a special case for text input, a default value of text.class[..]: Class name 2.1.2 - Specifying checkbox input
To specify checkbox input, set the type of control to checkbox.is_const: Method is constor: checkbox.is_const[on]: Method is const
These examples create a checkbox that is named
By default checkboxes are created unchecked. The latter case above shows how to create a checkbox that is initially checked. Setting the default to any value that resolves to 2.1.3 - Specifying radio button inputCreating radio buttons is slightly more complex than creating text input or checkbox input. Firstly you need to define a
The radiogroup.{name of radio group}:{label}For example: radiogroup.color: Select a color Within the radiogroup, each radio button is defined using the form: radio.{name of radio group}.{name of radio button}:{label} or: radio.{name of radio group}.{name of radio button}[{default}]:{label} For example: radio.color.red: Red
Each
One of the variables created by the radio button directives within a radio group will have a
If a radio button named A complete example for a radio group and associated radio buttons is: radiogroup.color: Select a color radio.color.red: Red radio.color.green: Green radio.color.blue: Blue 2.1.4 - Specifying expression pseudo-input
The expression pseudo-input allows you to define a repeatedly used expression in a variable rather than having to repeatedly copy and paste the expression within the The format of an expression pseudo-input is: expr.{name of expression}: {expression} For example: expr.full_name: ^first_name$ ^last_name$ 2.1.5 - Specifying map pseudo-input
The The format of an map pseudo-input is: map.{name of map}: {mapped text} For example: radiogroup.control: Type of control radio.control.button: Button radio.control.text: Text control map.button_handler: EVT_BUTTON map.text_handler: EVT_TEXT 2.2 - The Snippet Format SectionThe snippet format section defines the contents of the snippet and where the information captured by the data capture section should be placed. The contents of the snippet format section are copied to the output character by character until a directive is found. On encountering a directive, the directive is resolved, it's value output, and then the parser returns to copying subsequent characters to the output. The simplest directive has the form: ^{variable or function name}$The ^ character marks the beginning of the directive and the $ marks the end of the directive. (Hopefully these are easy to remember as they are the beginning and end anchors for regular expressions.) This form of directive would result in the value of the named variable being output. For example, if you had the following template:
text.user_name: What is your name . Hello ^user_name$
and the user entered Hello Alice Functions will be described further later. There are two other forms that a directive can take, these being: ^{conditional}?{text if condition is true}$and: ^{conditional}?{text if condition is true}?{text if condition is false}$
Note the Within the conditional part of the directive whitespace is not significant. Whitespace is significant in the other parts of the directive.
The simplest form of conditional is the name of a variable. If, as per 5 - True or False Values, the variable has a ^color.red?You have selected Red?So you don't like Red!$
if You have selected Red
The value of variables in the conditional section can be negated by preceding them with a ^ color.green | color.blue ?I like those colors too$ ^ ! color.red ?I like those colors too$
The
Observe that there is no You chose ^ color.red ?Red?^ color.green ?Green?Blue$$.Here, the directive ^ color.green ?Green?Blue$ forms the {text if condition is false} part of the directive ^ color.red ?Red?...$ . Naturally deeper nesting will require correspondingly more $ characters at the end of the directive.
Directives can be split across multiple lines. To aid formatting where the presence or absence of a set of code lines depends on the value of a conditional, the snippet template can be formatted as, for example: ^ want_destructor ? ~^ class $(); $
Here the whitespace and carriage returns associated with lines beginning with a It was mentioned earlier that functions could be used in directives. A directive using a function has the form: ^ {name of function}[{comma separate list of arguments}] $
Whitespace is significant in the
The currently defined functions are An example usage might be converting the name of a class into a suitable upper-case .h file include guard name, which could be done as: ^ uc[^class$] $_H
Note: As in a template where this kind of directive is useful it would be used multiple times, this expression could be defined as an expr.include_guard: ^ uc[^class$] $_H
and then used in the
An example usage of a ^ rstrip[^file_name$,.h] $
The radiogroup.control: Type of control radio.control.button: Button radio.control.text: Text control map.button_handler: EVT_BUTTON map.button_event: wxCommandEvent map.text_handler: EVT_TEXT map.text_event: wxCommandEvent
and the user has selected the
To output a 3 - A Complete TemplateHere are some examples of complete templates including a number of features described here. A template to add a new method is an existing class: text.class[..]: Name of class owning method text.name: Name of method text.args: Method arguments text.return_type: Return type (leave empty for void) expr.return: ^ !return_type ?void?^ return_type $$ checkbox.is_const: Is a const method . // For .h file ^ return $ ^name$(^args? ^args$ $)^is_const? const$; // For .cpp file ^ return $ ^class$::^name$(^args? ^args$ $)^is_const? const$ { } A template to add a new .h and .cpp file: text.name: Base name of file (without .h/.cpp ending) expr.inc_guard: ^ h_to_u[^uc[^name$]$] $_H . // For ^name$.h //---------------------------------------------------------------------- // IN CONFIDENCE // Copyright (c) 2011 My Company. //---------------------------------------------------------------------- #ifndef ^ inc_guard $ #define ^ inc_guard $ #endif // ^ inc_guard $ //---------------------------------------------------------------------- // IN CONFIDENCE //---------------------------------------------------------------------- // For ^name$.cpp //---------------------------------------------------------------------- // IN CONFIDENCE // Copyright (c) 2011 My Company. //---------------------------------------------------------------------- #include "^name$.h" //---------------------------------------------------------------------- // IN CONFIDENCE //---------------------------------------------------------------------- One way to use this template is to copy a generated file name, then select the part generated for that file and click the "Save to File..." button, pasting the copied file name into the file save dialog, and then repeating the operation for the other portion of the generated code. 4 - Enhanced Drag and DropCode Scrapbook allows you to drag generated code and drop it into your code editor. When enabled, Code Scrapbook will automatically minimize itself when it detects the start of a drag operation, making it easier to drag code into your editor.
To further enhance the drag-and-drop experience, if no code has been selected and a drag operation is started with the Triple clicking the mouse button will select the whole line. 5 - True or False Values
The values 6 - Licensing
The specification of the | |||||||||||||||||||
|