← Back to branch summary

~ubuntu-branches/ubuntu/trusty/bash-completion/trusty-updates

« back to all changes in this revision

Viewing changes to doc/styleguide.txt

  • Committer: Package Import Robot
  • Author(s): Sebastien Bacher
  • Date: 2012-07-23 16:07:59 UTC
  • mfrom: (5.1.12 sid)
  • Revision ID: package-import@ubuntu.com-20120723160759-lt9vn33dl3nak9l0
Tags: 1:2.0-1ubuntu1
https://launchpad.net/bugs/311525
https://launchpad.net/bugs/743208
https://launchpad.net/bugs/720541
* debian/maintscript, debian/postinst:
  - clean etc conffiles on upgrade since completion files are in /usr
    with the new version
* Resync with Debian, remaining diff
  * debian/patches/disable-avahi-browse.diff: Disable avahi-browse since
    it scales poorly in the current form: refresh patch
  * patches/101_bash_completion.oga_ogv.patch: Increase support for other
    OGG formats including .oga, .ogx, etc. (LP: #311525)
  * patches/103_colormake.patch: Add support for colormake to the make
    completion rules. (LP: #743208)
* Dropped changes:
  * Add conffile upgrade handling for a run of conffiles that were dropped
    since lucid: lucid upgrades are only supported to precise.
* Those fixes are in the new version
  * debian/patches/apt-get-changelog.patch:
  * Drop whitelists if they fail to produce any results:
  * patches/apt-get-download.patch: Add download as an apt-get
    sub-command (LP: #720541)
  * patches/102_manpager.patch: Override MANPAGER when generating perldoc
    completions.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/styleguide.txt
 
1
Coding Style Guide
 
2
==================
 
3
 
 
4
Introduction
 
5
------------
 
6
This document attempts to explain the basic styles and patterns that
 
7
are used in the bash completion.  New code should try to conform to
 
8
these standards so that it is as easy to maintain as existing code.
 
9
Of course every rule has an exception, but it's important to know
 
10
the rules nonetheless!
 
11
 
 
12
This is particularly directed at people new to the bash completion
 
13
codebase, who are in the process of getting their code reviewed.
 
14
Before getting a review, please read over this document and make
 
15
sure your code conforms to the recommendations here.
 
16
 
 
17
Indentation
 
18
-----------
 
19
Indent step should be 4 spaces, no tabs.
 
20
 
 
21
Globbing in case labels
 
22
-----------------------
 
23
 
 
24
Avoid "fancy" globbing in case labels, just use traditional style when
 
25
possible.  For example, do "--foo|--bar)" instead of "--@(foo|bar))".
 
26
Rationale: the former is easier to read, often easier to grep, and
 
27
doesn't confuse editors as bad as the latter, and is concise enough.
 
28
 
 
29
[[ ]] vs [ ]
 
30
----------------
 
31
 
 
32
Always use [[ ]] instead of [ ].  Rationale: the former is less error
 
33
prone, more featureful, and slightly faster.
 
34
 
 
35
Line wrapping
 
36
-------------
 
37
 
 
38
Try to wrap lines at 79 characters. Never go past this limit, unless
 
39
you absolutely need to (example: a long sed regular expression, or the
 
40
like). This also holds true for the documentation and the testsuite.
 
41
Other files, like ChangeLog, or COPYING, are exempt from this rule.
 
42
 
 
43
$(...) vs \`...`
 
44
----------------
 
45
 
 
46
When you need to do some code substitution in your completion script,
 
47
you *MUST* use the $(...) construct, rather than the \`...`. The former
 
48
is preferable because anyone, with any keyboard layout, is able to
 
49
type it. Backticks aren't always available, without doing strange
 
50
key combinations.
 
51
 
 
52
-o filenames
 
53
------------
 
54
 
 
55
As a rule of thumb, do not use "complete -o filenames". Doing it makes
 
56
it take effect for all completions from the affected function, which
 
57
may break things if some completions from the function must not be
 
58
escaped as filenames. Instead, use "compopt -o filenames" to turn on
 
59
"-o filenames" behavior dynamically when returning completions that
 
60
need that kind of processing (e.g. file and command names). The
 
61
_filedir and _filedir_xspec helpers do this automatically whenever
 
62
they return some completions.
 
63
 
 
64
[[ $COMPREPLY == *= ]] && compopt -o nospace
 
65
------------------------------------------------
 
66
 
 
67
The above is functionally a shorthand for:
 
68
----
 
69
if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then
 
70
    compopt -o nospace
 
71
fi
 
72
----
 
73
It is used to ensure that long options' name won't get a space
 
74
appended after the equal sign.  Calling compopt -o nospace makes sense
 
75
in case completion actually occurs: when only one completion is
 
76
available in COMPREPLY.
 
77
 
 
78
$split && return
 
79
----------------
 
80
 
 
81
Should be used in completions using the -s flag of _init_completion,
 
82
or other similar cases where _split_longopt has been invoked, after
 
83
$prev has been managed but before $cur is considered.  If $cur of the
 
84
form --foo=bar was split into $prev=--foo and $cur=bar and the $prev
 
85
block did not process the option argument completion, it makes sense
 
86
to return immediately after the $prev block because --foo obviously
 
87
takes an argument and the remainder of the completion function is
 
88
unlikely to provide meaningful results for the required argument.
 
89
Think of this as a catch-all for unknown options requiring an
 
90
argument.
 
91
 
 
92
Note that even when using this, options that are known to require an
 
93
argument but for which we don't have argument completion should be
 
94
explicitly handled (non-completed) in the $prev handling block because
 
95
--foo=bar options can often be written without the equals sign, and in
 
96
that case the long option splitting does not occur.
 
97
 
 
98
/////////////////////////////////////////
 
99
case/esac vs if
 
100
---------------
 
101
 
 
102
quoting
 
103
-------
 
104
 
 
105
awk vs cut for simple cases
 
106
---------------------------
 
107
 
 
108
variable and function naming
 
109
----------------------------
 
110
 
 
111
/////////////////////////////////////////