cycle.txt

*cycle.txt*                                Cycle text to predefined candidates

Version:    0.4.0
Author:     bootleq <bootleq@gmail.com>
License:    Public Domain
Repository: https://github.com/bootleq/vim-cycle

==============================================================================
CONTENTS                                                      *cycle-contents*

    Introduction  .......................... |cycle-introduction|
    Usage  ................................. |cycle-usage|
    Configuration  ......................... |cycle-configuration|
      General options  ..................... |cycle-general-options|
      Define groups  ....................... |cycle-define-groups|
      Group options ........................ |cycle-group-options|
      Fallback mapping  .................... |cycle-fallback-mapping|
      Examples  ............................ |cycle-examples|
    Limitations  ........................... |cycle-limitations|
    Credits  ............................... |cycle-credits|

==============================================================================
INTRODUCTION                                              *cycle-introduction*

*cycle* takes text near cursor, replace it with predefined alternates. Save
your time from changing relative words like true/false, Yes/No, and so on.

==============================================================================
USAGE                                                            *cycle-usage*

                                                             *<Plug>CycleNext*
                                                             *<Plug>CyclePrev*
Define key mappings for |<Plug>CycleNext| in |Normal| and |Visual| modes: >
  nmap <silent> <Leader>a <Plug>CycleNext
  vmap <silent> <Leader>a <Plug>CycleNext
< to replace text-under-cursor or visual-selected-text with their alternates.
(This plugin defines <Leader>a as default)

You can add [count] to pick candidate at further index, instead of next ONE.
You can map |<Plug>CyclePrev| (Prev, not Next) to cycle in reverse direction.

For example, with items ["One", "Two", "Three"]
and your custom mapping is <C-A> for CycleNext, <C-X> for CyclePrev,
where the cursor is under "One", then

    keys you type     result in ~
    -------------     --------- ~
      <C-A>             Two
      2<C-A>            Three
      <C-X>             Three
      4<C-X>            Three

This plugin has a very small set of preset groups (says, yes/no is a group).
It's recommended to define groups by yourself, see |cycle-define-groups|.

There are some special features beside ordinary text replacing, which are
controlled by group options, see |cycle-group-options|.

You can use |.| to repeat last cycle if you have one of the following "repeat"
plugins installed:
- https://github.com/kana/vim-repeat
- https://github.com/tpope/vim-repeat

==============================================================================
CONFIGURATION                                            *cycle-configuration*

------------------------------------------------------------------------------
General options                                        *cycle-general-options*

                                                              *g:loaded_cycle*
g:loaded_cycle            (default: none) ~

  Set to 1 to prevent this plugin from being loaded.

                                                      *g:cycle_default_groups*
g:cycle_default_groups    (default: none) ~

  This is a List for setting custom default groups. If exists, no groups will
  be set by plugin itself. See |cycle-define-groups-practice|.

                                       *g:cycle_default_groups_for_{filetype}*
g:cycle_default_groups_for_{filetype} ~
                          (default: none) ~

  Like |g:cycle_default_groups| but this List will be loaded when 'filetype'
  changes, thus only available for targeted filetype.

  The {filetype} part should be replaced with real type string, e.g.: >
    let g:cycle_default_groups_for_ruby = []
< is for filetype "ruby".

                                                         *g:cycle_no_mappings*
g:cycle_no_mappings       (default: 0) ~

  Set to 1 to disable default key mappings.
  List of defaults:

    mode   {lhs}         {rhs} ~
    ----   ---------     --------------- ~
    n      <Leader>a     <Plug>CycleNext
    v      <Leader>a     <Plug>CycleNext

                                                        *g:cycle_max_conflict*
g:cycle_max_conflict      (default: 1) ~

  When there are more than 1 alternates (in different groups) for current
  text, you are prompted to select which is the wanted one.

  When the number of conflicts is more than this setting, no prompt will be
  shown, cycle aborts with a message instead.

  The default value is 1, means no conflicts will be handled. This improve
  some performance since no extra search is needed after first found.
  And it's recommended to use buffer-scoped groups to prevent conflicts, see
  |cycle-define-groups-practice|.

                                                         *g:cycle_auto_visual*
g:cycle_auto_visual       (default: 0) ~

  When starting a cycle in normal mode, and the result text is not a keyword
  (for example, it contains whitespace, see 'iskeyword'), you might want to
  select the new text with visual mode. Set this option to 1 to enable it.

                                                       *g:cycle_phased_search*
g:cycle_phased_search     (default: 1) ~

  When starting a cycle, it might not obviously know which text should be
  cycled. In most cases it's exactly the |<cword>| under cursor, however, for
  example, to cycle "Hello World", we must visual-select it because it's not a
  <cword>.

  When this option is on, the search can smartly perform with multiple phases.
  For example, while searching of <cword> in "foo_with_bar" fails, some
  secondary search can find the "with" and return intended "foo_without_bar"
  as a result.

------------------------------------------------------------------------------
Define groups                                            *cycle-define-groups*

To start quickly, just read |cycle-define-groups-practice|.

                                                              *g:cycle_groups*
                                                              *b:cycle_groups*
All candidates are defined as groups.
The structure looks like:
>
  g:cycle_groups = [                | => groups, scoped by global/buffer
    {                               |   =>
      'items':   ['foo', 'bar'],    |   =>
      'options': {'hard_case': 1},  |   => a group
    },                              |   =>
  ],                                |
<
when there exists |b:cycle_groups|, it takes higher priority than the global
one. |g:var| |b:var|

You should not define cycle_groups directly. Use |cycle#add_group()| is the
preferred way.

                                                        *cycle-default-groups*
Without any configuration, the default preset groups are: >
  call cycle#add_groups([
        \   [['true', 'false']],
        \   [['yes', 'no']],
        \   [['on', 'off']],
        \ ])
< note this will be ignored if any |g:cycle_default_groups| configured.

                                                           *cycle#add_group()*
A group consists with "items" and optional "options".
To add a group, use |cycle#add_group()| with any of below forms >
  cycle#add_group(items)
  cycle#add_group(items, options)
  cycle#add_group(items, option, ..., option_can_be_dictionary_or_string)
  cycle#add_group(group)
< for example: >
  call cycle#add_group(['Yes', 'No'])
  call cycle#add_group(['Yes', 'No'], {'match_case': 1})
  call cycle#add_group(['Yes', 'No'], 'match_case', {'hard_case': 1})
  call cycle#add_group([['Yes', 'No'], 'match_case'])
<
                                                         *cycle#add_b_group()*
Use cycle#add_b_group() to add a group into b: scoped. |b:cycle_groups|

                                                          *cycle#add_groups()*
                                                        *cycle#add_b_groups()*
To add multiple groups at the same time, there are shortcut version of adding
functions. You have to wrap items and options as a List, for example: >
  call cycle#add_groups([
        \   [['true', 'false']],
        \   [['Yes', 'No'], 'match_case'],
        \ ])
<
                                                      *cycle#reset_b_groups()*
This clears |b:cycle_groups|.
Also accepts a parameter same as |cycle#add_b_groups| to set new groups.

                                                     *cycle#reset_ft_groups()*
Clear buffer-scoped groups for filetypes, reset to the setting for current
'filetype' (predefined by |g:cycle_default_groups_for_{filetype}|).

This function will be called automatically when 'filetype' change.

                                          *cycle#reset_b_groups_by_filetype()*
Deprecated, will be removed in future version.
Reason: now we hold ft-specified groups in another internal variable, no
longer use |b:cycle_groups|.

Reset |b:cycle_groups| with settings subject to current 'filetype', requires
variable |g:cycle_default_groups_for_{filetype}| preset.

                                                *cycle-define-groups-practice*
The recommended way to define groups is setting |g:cycle_default_groups| and
|g:cycle_default_groups_for_{filetype}| in your vimrc, this plugin will find
and applied them behind the scene.
See |cycle-config-examples|.

------------------------------------------------------------------------------
Group options                                            *cycle-group-options*

A group option is a Dictionary with key-value pair. While for convenience,
in |cycle#add_group()| and similar functions, you can set it as a string (by
its key), the option's default value will be used.

By default no options are set.

"name"              String (default: none) ~

  Name of the group.
  Will be displayed in conflict prompt, see |g:cycle_max_conflict|.

"match_case"        Number (default: 0) ~

  By default, searching of group items is case-insensitive. Thus "yes" and
  "Yes" have identical effect.
  Set this option other than 0 to enforce case-sensitive search.

"hard_case"         Number (default: 0) ~

  By default, case in original text will be copied to resulting text. Thus
  "friDAY" will become "satURDay".
  Set this option other than 0 to keep resulting text with the same case as
  they were defined.

"sub_tag"           Number (default: 1) ~

  When editing a xml tag, opening and closing parts can be substituted
  together: >
    <EM>example</EM>  =>  <STRONG>example</STRONG>
< Set this option other than 0 to enable it.

"sub_pair"          Number (default: 1) ~

  When editing special pairs (e.g.: {}, <>), opening and closing parts can be
  substituted together: >
    {example}  =>  <example>
< You have to set this option other than 0 and define "end_with" or
  "start_with" option to recognize what the opposite part is.
  Example: >
    call cycle#add_group(
          \   [ '{', '<' ], 'sub_pair', {'end_with': [ '}', '>' ]}
          \ )
< It's recommended to use "sub_pairs" other than this option.

"end_with"          List (default: none) ~
"begin_with"        List (default: none) ~

  Used with "sub_pair" option, to define opposite pairs for original text.

"sub_pairs"         String (default: ':') ~

  This is a shortcut to set "sub_pair", "end_with" and "begin_with" options at
  the same time. Each group item will be split with this value into "begin"
  and "end" parts.
  Example: >
    call cycle#add_group(
          \   [ '{:}', '<:>' ], 'sub_pairs'
          \ )
< Internally, this group will be translated into two groups, just identical
  with original 'sub_pair' version.

"before_sub"        (List) ~
"after_sub"         (List) ~
"restrict_cursor"   (Number) ~

  Internal usage only, don't set them.

"match_word"        Number (default: none) ~

  Restrict group items to be matched within word-boundary, see 'iskeyword'.
  For example, on/off only matches "on" but not "Mon".
  Set this option other than 0 to enforce word-bounded search.


------------------------------------------------------------------------------
Fallback mapping                                      *cycle-fallback-mapping*

When |<Plug>CycleNext| or |<Plug>CyclePrev| fails to find any matched
alternates, some key sequences can be set as fallbacks.
                                                     *<Plug>CycleFallbackNext*
                                                     *<Plug>CycleFallbackPrev*
For example, define below mappings: >
  noremap <silent> <Plug>CycleFallbackNext <C-A>
  noremap <silent> <Plug>CycleFallbackPrev <C-X>
< then Vim defult |Ctrl-A| (adding) or |Ctrl-X| (subtracting) will be
performed, if there were nothing to cycle.

Note that you will have to use |map| instead of |noremap| if the fallback key
needs further remapping. e.g.: >
  map <silent> <Plug>CycleFallbackNext <Plug>SpeedDatingUp
<

------------------------------------------------------------------------------
Configuration examples:                                 *cycle-config-examples*

General options:
>
    let g:cycle_no_mappings = 1
    let g:cycle_max_conflict = 1
    let g:cycle_phased_search = 1
<

Key mappings:
>
    nmap <silent> <LocalLeader>a <Plug>CycleNext
    vmap <silent> <LocalLeader>a <Plug>CycleNext
    nmap <silent> <Leader>a <Plug>CyclePrev
    vmap <silent> <Leader>a <Plug>CyclePrev
    noremap <silent> <Plug>CycleFallbackNext <C-A>
    noremap <silent> <Plug>CycleFallbackPrev <C-X>
<

Global groups:
>
    let g:cycle_default_groups = [
          \   [['true', 'false']],
          \   [['yes', 'no']],
          \   [['on', 'off']],
          \   [['+', '-']],
          \   [['>', '<']],
          \   [['"', "'"]],
          \   [['==', '!=']],
          \   [['0', '1']],
          \   [['and', 'or']],
          \   [["in", "out"]],
          \   [["up", "down"]],
          \   [["min", "max"]],
          \   [["get", "set"]],
          \   [["add", "remove"]],
          \   [["to", "from"]],
          \   [["read", "write"]],
          \   [["only", "except"]],
          \   [['without', 'with']],
          \   [["exclude", "include"]],
          \   [["asc", "desc"]],
          \   [['是', '否']],
          \   [['{:}', '[:]', '(:)'], 'sub_pairs'],
          \   [['（:）', '「:」', '『:』'], 'sub_pairs'],
          \   [['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday',
          \     'Friday', 'Saturday'], 'hard_case', {'name': 'Days'}],
          \ ]

    " ruby, rails
    let g:cycle_default_groups += [
          \   [["if", "unless"]],
          \   [["blank", "present"]],
          \   [["while", "until"]],
          \   [["begin", "end"]],
          \   [["foreign_key", "primary_key"]],
          \   [["inspect", "to_yaml"]],
          \ ]

    " CSS
    let g:cycle_default_groups += [
          \   [["none", "block"]],
          \   [["show", "hide"]],
          \   [["left", "right"]],
          \   [["top", "bottom"]],
          \   [["margin", "padding"]],
          \   [["before", "after"]],
          \   [["absolute", "relative"]],
          \   [["first", "last"]],
          \ ]

    " HTML
    let g:cycle_default_groups += [
          \   [['h1', 'h2', 'h3'], 'sub_tag'],
          \   [['ul', 'ol'], 'sub_tag'],
          \   [['em', 'strong', 'small'], 'sub_tag'],
          \ ]
<

Filetype specified groups:
>
    " ruby only
    let g:cycle_default_groups_for_ruby = [
          \   [['accessible', 'protected']],
          \   [['stylesheet_link_tag ', 'javascript_include_tag ']],
          \ ]
<

==============================================================================
LIMITATIONS                                                *cycle-limitations*

- Can't handle multi line text.

==============================================================================
CREDITS                                                        *cycle-credits*

- Michael Brown ~
  Author of SwapIt.vim: https://github.com/mjbrownie/swapit
  SwapIt originally provides lots of awesome features include visual
  multi-words, xml tag pairs, omni-completion cycling.

==============================================================================
vim:tw=78:fo=tcroq2mM:et:sts=2:sw=2:ft=help:norl: